Best procedure for moving a JCB instance from J!3 to J!5

[kmd-muc]

I have a JCB instance with an importatnt project still in a Joomla 3 instance. I did try to migrate to J!5 multiple times some time ago, but I always ran into problems especially after updating JCB, so I didn't try again for at least a year and a half.
Now there are some major changes to be made to the project which also is still a J!3 component and needs to be upgraded to J!5 and I want to modernize the whole environment. What is the recommended way to upgrade a JCB 3.2.3 running on a Joomla 3.10.12 to a current JCB running on J!5 while keeping the components that have been developed within it?

[Llewellynvdm]

🚀 Joomla Component Builder (JCB) Migration Guide

From Joomla 3 + JCB 3.x to Joomla 5 + JCB 5.x

Last updated: July 2025

---

🧭 Overview

Migrating your JCB projects from Joomla 3 (JCB v3.2.3 or earlier) to Joomla 5 is a multi-stage process. It involves:

• Gradual Joomla upgrades (3.10 → 4.x → 5.x)
• Gradual JCB upgrades (v3 → v4 → v5)
• Handling database schema differences
• Adapting any custom code to modern PHP standards (namespaces, type hints, etc.)

---

📋 Step-by-Step Migration Plan

🔒 1. Clone & Back Up First

Before you touch anything:

• ✅ Backup your Joomla 3.10.12 site, including:

  • Filesystem
  • Full MySQL database dump

• ✅ Clone your site to a staging environment

This will be your working ground for the upgrade.

---

🧱 2. Restore the Correct JCB Version (If Needed)

If your current JCB version is not exactly the same as when the component was last exported:

• 🔄 Reinstall JCB 3.2.3 or the original version used to build the component.
• 🧩 Import your .jcb package (ignore checksum warning if trusted).
• ✅ Ensure the component compiles successfully in this version.

⚠️ The import/export feature is no longer maintained in JCB v4/v5. Only JCB 3.x supports it.

---

🛠️ 3. Compile & Verify in Joomla 3 + JCB 3

• Use JCB 3.2.3 to compile the component
• Install it into Joomla 3
• Confirm everything works as expected
• Note any custom code, overrides, or injected logic for later review

---

⬆️ 4. Upgrade to Joomla 4

• Upgrade your Joomla site to the latest Joomla 4.x version

• Fix any post-upgrade errors (especially 3rd-party plugins or templates)

• Use CLI to run Joomla database fixes:

  php cli/joomla.php database:fix
  php cli/joomla.php database:migrate

---

⚙️ 5. Install JCB 4.x

• Install the latest stable JCB v4.x compatible with Joomla 4
• Open JCB and confirm your component is recognized
• Compile it and confirm it works in Joomla 4
• Fix any minor issues (custom code compatibility, field types, etc.)

---

🧠 6. Migrate or Refactor Custom Code (J3 → J4)

This is the critical step. Joomla 4 uses fully namespaced class names, so:

• ✅ Replace legacy Joomla classes (e.g., JFactory) with Joomla Power Keys (JPK)

• JCB will automatically:

  • Add correct namespaced class names
  • Insert use statements

• 🔧 Update any deprecated or custom code that doesn't follow modern standards

• 🧪 Fully test component output in Joomla 4

---

🧬 7. Upgrade to Joomla 5

Once your Joomla 4 site + JCB 4 build is stable:

• Upgrade your site to Joomla 5.x
• Fix any Joomla 5-specific issues
• Use CLI migration tools again if needed

---

🚀 8. Install JCB 5.x

• Install latest stable JCB 5.x version

• Reopen your project in JCB

• Compile it and install the component into Joomla 5

• 🔍 Test thoroughly for:

  • PHP 8.2+ compatibility
  • Deprecated method usage
  • Namespace issues
  • Plugin or template conflicts

---

🧰 Troubleshooting Guide

❌ Compilation Errors After Migration

• Check:

  • Custom code overrides
  • Deprecated J3-style syntax
  • Missing Joomla Power Keys

• Debug step-by-step; JCB debug mode helps

---

🧪 Schema Sync Strategy (Advanced)

If you're manually copying database entries:

• Do not import JCB tables directly from Joomla 3 to Joomla 5

• Instead:

  • Export only essential #__componentbuilder_* entries
  • Use tools like [MySQL Workbench] or mysqldump with --no-create-info

• Compare table structures between JCB 3.x and JCB 5.x

• Ensure all default values and nullability match

---

🧩 Joomla Power Keys (JPK)

JCB now supports Power Keys, replacing old Joomla class names.

Legacy Class	JPK Equivalent
JFactory	Joomla___39403062_84fb_46e0_bac4_0023f766e827___Power
JUri	Joomla___eecc143e_b5cf_4c33_ba4d_97da1df61422___Power
JUser	Joomla___effdaf6d_2275_425d_9f52_d4952e564d34___Power
...	...

When compiling, JCB will auto-resolve these to:

$app = Joomla___39403062_84fb_46e0_bac4_0023f766e827___Power::getApplication();

If you're unsure of the exact JPK to use, visit the Joomla Power Repo.

---

👥 Get Help

• Join the JCB Telegram Group to get real-time help from other developers

• Share your:

  • Joomla version
  • JCB version
  • Component export file
  • Exact error messages
  • PHP version

Community members are often willing to help — or even take on contract work.

---

🧾 Summary Checklist

✅ Backup original Joomla 3 site
✅ Verify JCB 3 component compiles
✅ Upgrade Joomla 3 → 4 → 5
✅ Upgrade JCB 3 → 4 → 5
✅ Replace legacy Joomla class names with JPK
✅ Refactor any custom code
✅ Fix schema issues and missing defaults
✅ Test component on Joomla 5
✅ Ask the community if stuck

---

✅ Final Thoughts

Yes, it's a multi-step process — but it's doable, and we've done it hundreds of times internally. If you're stuck, it's often due to custom overrides or manual SQL transfers that don't align with the evolving schema.

We're actively working to bring portable, repo-based import/export back in JCB, but until then, this path ensures data integrity and version compatibility.

Let us know where you hit trouble — we'll update this document to help others too.

---

Let's modernize JCB the right way. 🚀

[Llewellynvdm]

Also check out this checklist: https://git.vdm.dev/joomla/upgrade-checklist

[kmd-muc]

worked like a charm - thank you so much!