[← Back to Home](Home)

# 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:

1. Install MokoOnyx via **System → Install → Extensions**
2. Go to **System → Site Templates** and verify MokoOnyx appears with your settings
3. Visit any page on your site to confirm the template is active
4. 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:

1. Uninstall MokoCassiopeia from **Extensions → Manage**
2. 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 [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) -- Moko Consulting*

---

*Repo: [MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx) · [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*

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