Technical Lessons from a Complex eZ Publish → Ibexa Migration

We recently completed a complex eZ Publish to Ibexa OSS migration for a European SME. Not a simple content lift — a full migration including custom CKEditor plugins, approval workflows built from scratch, and years of accumulated content that needed careful transformation.

This post shares what we learned. If you're planning an eZ Publish migration, these lessons might save you significant time and trouble.

The project in brief

The client had been running a content-heavy B2B portal on eZ Publish for over a decade. The original developer had left. They were stuck on an old PHP version, running an outdated server OS, facing mounting pressure from their hosting provider.

They needed to migrate. We recommended Ibexa OSS as the target platform — same content model foundations, modern stack, active development.

But this wasn't a standard migration. The site had:

• Custom content types built over years
• Specialized editor features (footnotes, marginal numbering)
• Rich text content with custom tags
• Editorial approval workflows
• Role-based field-level permissions
• Multi-language content
• Deep URL hierarchies

What follows are the specific challenges we encountered and how we addressed them.

1Rich text migration is where the pain lives

If your eZ Publish site uses the rich text editor (ezoe/ezxmltext), content migration will be your biggest challenge.

eZ Publish stores rich text as ezxmltext. Ibexa uses a different format (richtext, based on DocBook). The content must be transformed.

What we found:

Years of content accumulates problems. Invalid XML structures. Empty tags. Broken anchor links. References to content that no longer exists. Custom tags that need special handling.

The official migration scripts handle basic content. They don't handle edge cases. After running the standard migration, we had content that wouldn't render or wouldn't save.

What we did:

We built custom migration scripts that:

• Fixed invalid anchors and broken internal links before migration
• Cleaned up malformed XML structures
• Removed empty tags that caused rendering issues
• Converted custom tags to their Ibexa equivalents
• Logged every content item that needed manual review

2Ibexa OSS is missing features you might need

Ibexa comes in several editions. The open-source edition (Ibexa OSS) doesn't include everything.

What's not in Ibexa OSS:

• Content approval workflows
• Advanced permission systems
• Some collaboration features

If your eZ Publish site relied on content approval (editor submits → reviewer approves → content publishes), that workflow doesn't exist in Ibexa OSS. It's a paid feature in higher editions.

What we did:

We built it.

Our custom approval workflow implementation includes:

• Approval queue with pending, approved, and denied version tracking
• Modified publishing flow that intercepts content requiring approval
• Approval interface with commenting capability
• Version diff view showing exactly what changed
• Automatic handling of superseded drafts

This was significant custom development. But for this client, buying the commercial Ibexa edition would have been more expensive over time than building exactly what they needed.

3Custom editor features require CKEditor5 plugin development

The client's editors used specialized features: footnotes and marginal reference numbers (sidenumbers). These don't exist in standard Ibexa.

eZ Publish used an older editor. Ibexa uses CKEditor5 — completely different architecture.

What we built:

CKEditor5 plugin development has a learning curve. The documentation is good but the architecture is complex. Budget more time than you expect.

4Role-based field permissions need custom work

The client needed editors to see only the fields they were permitted to edit. Different roles should see different fields on the same content type.

Ibexa has a robust permission system, but field-level visibility based on roles isn't built in.

What we did:

We created an event subscriber for the edit view that:

• Reads a configuration file defining which fields are visible per role per content type
• Injects a view parameter with the list of hidden fields
• Overrides the content edit template to hide fields the user shouldn't see

This isn't about security (field data is still protected by permissions) — it's about UX. Editors shouldn't see fields they can't edit. It reduces confusion and prevents errors.

5URL migration matters more than you think

The existing site had deep content hierarchies. Some URLs were very long. The client wanted shorter, cleaner URLs for new content while ensuring all old URLs still worked for SEO.

The challenges:

• Ibexa generates URL aliases based on content tree location by default
• Old URLs needed 301 redirects to new locations
• Some content was being reorganized in the migration

What we did:

• Created custom URL alias generation that produces shorter URLs (removing the full directory path)
• Built a script to generate URL wildcards for redirecting legacy URLs
• Added a PublishVersionEvent subscriber to generate custom aliases for new content
• Overwrote the UrlAliasGenerator service to use custom aliases in navigation

We also added structured data markup (JSON-LD) for article content, since we were already touching the frontend templates.

6Plan for the admin UI customizations

Ibexa's admin interface is flexible, but you'll likely need to customize it.

What we customized:

• Custom dashboard showing approval queue and collaboration items
• Bulk content operations
• Custom search interface with preset filters
• Version comparison tool for any two versions in any language
• Conditionally visible tabs based on user role
• Custom buttons for common operations

Some of this was straightforward template overriding. Some required event subscribers. Some needed custom controllers.

7Migration is not a one-time event

We didn't flip a switch and migrate everything at once. The process was iterative:

1. Set up Ibexa environment
2. Run initial content migration
3. Identify failures and edge cases
4. Fix source data or improve migration scripts
5. Re-run migration
6. Repeat until clean

The client's editorial team continued working in eZ Publish during most of the migration. We ran delta migrations to capture changes.

Plan for overlap. Plan for iteration. Plan for things to take longer than expected.

Technical summary

Was it worth it?

The client is now running on a modern, supported stack. Their editorial workflows are preserved — in some ways improved. They have a platform with active development and a clear future.

Could they have rebuilt on a different platform? Yes. But they would have lost years of content model investment and spent more time and money getting less.

For complex eZ Publish installations, migration to Ibexa OSS is often the most practical path — if you have the expertise to handle what the standard migration tools don't cover.