Migration from MokoCassiopeia

MokoOnyx is the successor to MokoCassiopeia. The migration runs automatically during install/update -- no manual steps are required beyond installing MokoOnyx.

When Does Migration Run?

The migration runs in the postflight() method of the installer script (script.php), which executes during both install and update operations. It checks for existing MokoCassiopeia template styles in the database and only runs if they are found.

What Gets Migrated

1. Template Styles and Parameters

All MokoCassiopeia template styles are detected from the #__template_styles table
For each MokoCassiopeia style, a matching MokoOnyx style is created with the same parameters
The first MokoCassiopeia style's parameters are applied to the installer-created default MokoOnyx style
Additional styles are created as new entries
Parameter values are updated to replace mokocassiopeia references with mokoonyx

2. Default Template Assignment

If MokoCassiopeia was set as the default site template (home = 1), MokoOnyx automatically takes over as the default. The MokoCassiopeia style is unset as default.

3. Custom User Files

The following files are copied from the MokoCassiopeia media directory to MokoOnyx (only if the destination file does not already exist):

File	Purpose
`css/theme/light.custom.css`	Custom light palette
`css/theme/dark.custom.css`	Custom dark palette
`css/theme/light.custom.min.css`	Minified custom light palette
`css/theme/dark.custom.min.css`	Minified custom dark palette
`css/user.css`	Custom CSS overrides
`css/user.min.css`	Minified custom CSS
`js/user.js`	Custom JavaScript
`js/user.min.js`	Minified custom JavaScript

Source: media/templates/site/mokocassiopeia/ Destination: media/templates/site/mokoonyx/

4. Content References

All references to "MokoCassiopeia" and "mokocassiopeia" in article content (introtext and fulltext columns) and module content are automatically replaced with "MokoOnyx" and "mokoonyx". This covers:

Image paths (e.g., media/templates/site/mokocassiopeia/...)
Template name references in custom HTML modules
Any other text references in content

5. Additional Post-Install Tasks

These tasks run during every install/update (not just migration):

Task	Description
Favicon stamp cleared	Deletes `.favicon_generated` stamp so favicons regenerate. Also removes the old `/images/favicons/` directory and root-level favicon files from previous versions.
Media folder cleaned	Removes stale `.min.css` and `.min.js` files (regenerated by `MokoMinifyHelper`), unminified vendor files, and deprecated files (`custom.css`, `custom.js`, `template-rtl.css`).
Extension locked	Sets `locked = 1` in `#__extensions` to prevent accidental uninstallation.

How to Trigger Migration

Migration runs automatically during installation. If you need to observe the results:

Install MokoOnyx via System → Install → Extensions
Go to System → Site Templates and verify MokoOnyx appears with your settings
Visit any page on your site to confirm the template is active
Check administrator/logs/mokoonyx.log.php for migration log entries

Re-Running Migration

The migration runs on every install/update operation via the postflight() method. It is safe to re-run because:

Style creation checks for existing styles before creating duplicates
File copies only occur when the destination file does not exist
Content replacements are idempotent (replacing "MokoOnyx" with "MokoOnyx" is a no-op)

To force a fresh migration, you can reinstall MokoOnyx by uploading the ZIP package again.

After Migration

Once you have confirmed everything is working:

Uninstall MokoCassiopeia from Extensions → Manage
Optionally clean up any remaining MokoCassiopeia files in media/templates/site/mokocassiopeia/

Troubleshooting

Issue	Solution
Settings not migrated	Check `administrator/logs/mokoonyx.log.php` for error messages. Verify MokoCassiopeia styles exist in `#__template_styles`.
Custom theme files missing	Verify files exist in `media/templates/site/mokocassiopeia/css/theme/`. The copy only runs if the destination does not already exist -- if MokoOnyx files are already present, they are not overwritten.
Content references not updated	Check the log for "Content replacement failed" or "Module replacement failed" warnings. Database permissions may be insufficient.
PHP version error	MokoOnyx requires PHP 8.1+. The preflight check blocks installation if this is not met.
Joomla version error	MokoOnyx requires Joomla 4.4+. The preflight check blocks installation if this is not met.

Built with MokoStandards -- Moko Consulting

Repo: MokoOnyx · MokoStandards

Revision	Date	Author	Description
1.0	2026-05-09	Moko Consulting	Initial version