Joomla 3 naar 4: de triagetabel voor stukke extensies

Een Nederlands bureau waar we mee samenwerken droeg een Joomla-site over aan een nieuwe klant. De klant wilde Joomla 4. De site had 47 third-party extensies. Na de testmigratie kreeg de admin een wit scherm met "Class 'JFactory' not found" in de error log. Zes extensies lieten je niet eens bij het dashboard komen. Vrijdagmiddag lag er een lijst met 23 dingen die een beslissing nodig hadden, en niemand wist waar te beginnen.

Dit is de tabel die we voor zulke momenten bij de hand houden. Het is geen checklist. Het is een manier om 47 extensies in ongeveer twee uur in vier bakjes te sorteren, voordat er ook maar één regel code wordt aangeraakt.

Hoe de breuk tussen J3 en J4 eruitziet

De sprong van Joomla 3 naar Joomla 4 is geen point release. Het framework is genoeg veranderd dat elke extensie die voor Joomla 3 is geschreven en sinds 2020 niet meer is bijgewerkt waarschijnlijk fatals gooit. De gebruikelijke verdachten:

• JFactory::getDbo()-aanroepen (nu Joomla\CMS\Factory in de namespaced vorm)
• JText::_() (nu Joomla\CMS\Language\Text)
• jimport()-aanroepen (verwijderd)
• MooTools-aannames in admin-JS (MooTools is weg, alleen jQuery, en steeds vaker vanilla)
• Bootstrap 2-markup die breekt onder een Bootstrap 5-template

Heeft je site meer dan tien extensies, dan ga je dit niet allemaal oplossen door broncode te lezen. Eerst sorteren, dan werken.

De triagetabel

Vijf kolommen. Print het, plak het in een spreadsheet, wat je wilt. De kolommen:

1. Naam en geïnstalleerde versie
2. J4-versie uitgebracht? (ja / nee / maintainer stil)
3. Gebruikt? (front-end, alleen admin, scheduled task, dood)
4. Eigen DB-tabellen? (ja / nee)
5. Bakje (Update, Vervangen, Forken, Slopen)

De eerste vier kolommen zijn feiten. Die vul je in één doorloop van de Extensions Manager en een snelle check op de site van elke leverancier. De vijfde kolom is de beslissing.

Kolom 2 snel invullen

Je hoeft niet op elk leveranciersportaal in te loggen. De Joomla Extensions Directory (JED) toont per extensie de J4-compatibiliteit. Open de directory, zoek op naam, kijk naar de compatibility-badge. Staat de extensie niet op JED, check dan de site van de ontwikkelaar. Is die site offline of dateert de laatste blogpost uit 2021, dan is dat het antwoord voor kolom 2: "maintainer stil".

Kolom 3 eerlijk invullen

De verleiding is om elke extensie op "gebruikt" te zetten. Niet doen. Open de front-end met het netwerkpaneel open en een schone session. Kijk wat er laadt. Vraag daarna aan de klant welke admintools ze in een normale maand echt aanraken. Alles wat op geen van beide lijsten staat, gaat in "dood".

De helft van een Joomla 3-site met 47 extensies is meestal dood. ACL Manager ooit geïnstalleerd voor een rechten-noodgeval. Twee back-upextensies omdat de één Akeeba probeerde en de ander iets anders. Een SEO-extensie die vervangen werd door een andere SEO-extensie. Je trekt er tien uit voordat je één regel code schrijft.

De bakjes van boven naar beneden afwerken

Zodra de tabel vol is, werk je de bakjes in deze volgorde: eerst Slopen, dan Update, dan Vervangen, dan Forken. De volgorde doet ertoe, want elk bakje verkleint het werk in het volgende.

Eerst slopen

Elke rij die "dood" is, gaat eruit. Deïnstalleren via de Extensions Manager. Gooit de uninstaller een fout (wat vaak gebeurt op een half kapotte Joomla 4), dan haal je de rijen handmatig weg uit #__extensions, #__menu, en de eigen tabellen van de extensie.

DELETE FROM j_extensions WHERE element = 'com_deadext';
DELETE FROM j_menu       WHERE component_id = 1234;
DROP TABLE IF EXISTS j_deadext_items;

Eerst een back-up. Altijd. Het aantal extensies dat met een nette uninstaller wordt geleverd is kleiner dan je denkt, en wees-rijen in #__assets achtervolgen je ook bij de volgende migratie.

Daarna update

Rijen waar kolom 2 "ja, J4-versie bestaat" zegt en de maintainer nog leeft: installeer de nieuwe versie op staging, draai hem één keer, kijk naar de log. Dit zijn meestal vijf-minuten-klusjes. Akeeba Backup, JCE Editor, Admin Tools: deze leveranciers hebben het werk gedaan. Vertrouw erop en ga door.

De valkuil hier is dat sommige extensies een specifieke tussenversie nodig hebben vóór de sprong naar J4. JCE wilde bijvoorbeeld dat je eerst op de laatste J3-compatibele release zat. Lees de release notes. Sla niets over.

Dan vervangen

Rijen waar kolom 2 "geen J4-versie, maar de functie is generiek" zegt. Een formulierenbouwer die sinds 2020 niet meer is bijgewerkt heeft een dozijn onderhouden vervangers. Een simpele galerijextensie kun je in een middag inruilen. Je verliest wat configuratie. Dat is prima. De kosten van een dode formulierenbouwer levend houden over een Joomla-hoofdversie heen zijn hoger dan drie formulieren opnieuw bouwen.

Pas dan forken

Gereserveerd voor extensies waar (a) geen J4-versie van bestaat, (b) geen vervanger doet wat zij doet, en (c) de extensie niet enorm is. Een eigen component voor de offerte-aanvraagflow van een klant. Een directory-plugin met een zelf in elkaar gezet ratingsysteem. Vijf bestanden, twee databasetabellen, en een specifiek stukje bedrijfslogica waar de klant aan hecht.

Forken betekent: pak de broncode, doe een zoek-en-vervang-ronde op de Joomla 3-idiomen, registreer de namespaces, en lever het uit als een private extensie. De Joomla 4-migratiedocs zijn de canonieke referentie en ze zijn beter dan vroeger. De Joomla API reference vertelt je welke nieuwe namespaced class hoort bij elke deprecated J3-aanroep die je tegenkomt.

Wat de tabel niet vangt

Drie dingen die de triagetabel niet boven water haalt. Goed om te weten voordat je hem inzet.

Template-breuk. Een J3-template dat op Bootstrap 2 leunt, ziet er verkeerd uit, ook als elke extensie werkt. Test de front-end op een echt toestel na de extensieronde. Is de template custom en oud, dan heb je misschien een aparte triage nodig voor de override-bestanden in templates/yourtemplate/html/.

Editor-content. Artikelen die in TinyMCE 4 zijn geschreven, renderen soms vreemd in TinyMCE 5, vooral rond tabellen en inline styles. Steekproef de top 20 artikelen op verkeer voordat je aftekent.

PHP-versie. Joomla 4 wil minimaal PHP 7.2.5 en draait het best op 8.1 of 8.2. De PHP 8.0 migration guide beschrijft de breukvlakken. Extensies die door de Joomla-versiecheck komen kunnen alsnog fatalen op PHP 8 door strengere type checks of verwijderde functies zoals create_function(). Draai de gemigreerde site op dezelfde PHP-versie als waarop hij in productie zal draaien.

De tool achter de tabel

Zulke triage betekende vroeger een map met SQL-bestanden, een handgeschreven changelog en een schietgebed. Toen we Pier bouwden, liepen we hier zelf tegenaan bij ons eigen werk aan verouderde sites. We hebben het uiteindelijk zo opgelost dat elke database-write en bestandsbewerking gekoppeld is aan een version history-entry, zodat een mislukte extensie-deïnstallatie één toetsaanslag van ongedaan maken is, en de MySQL editor de opruimactie voor wees-rijen kan draaien zonder SSH-tunnel.

De kleinste stap voor vandaag

Open een van je Joomla 3-sites. Tel de geïnstalleerde extensies. Markeer welke daadwerkelijk worden gebruikt. Dat getal is je triagebudget voor de uiteindelijke migratie, en het kennen voordat de klant ernaar vraagt is meer waard dan al het codewerk dat erna komt.