Postinstall messages in Joomla

1. De basis

1.1 Wat com_postinstall Is

com_postinstall is een kleine kerncomponent die post-installatie- en upgradeberichten toont. Wanneer Joomla zelf, of een van je extensies, je iets moet vertellen vlak na een installatie of update, slaat het een bericht op en toont com_postinstall het. De officiele beschrijving is kort en exact: "Toont post-installatie- en post-upgradeberichten voor Joomla en zijn extensies."

Het is een component die alleen in de beheeromgeving werkt. Het heeft geen frontend, geen artikelen en geen openbare URL. Het bestaat om eenmalige meldingen af te leveren bij de mensen die de site beheren.

Heb je ooit een Joomla-melding gezien als "Je oude TinyMCE-instelling is gewijzigd, klik hier om te controleren"? Dat was com_postinstall.

1.2 Waar je het vindt

Het scherm zit onder het menu Systeem in de beheeromgeving:

Systeem
 └─ Beheren
     └─ Post-installatieberichten

De volledige titel van de pagina is Post-installatie- en upgradeberichten. De URL is index.php?option=com_postinstall in de beheeromgeving. Je kunt het ook bereiken via het Systeemdashboard, waar een klein meldingenpaneel laat zien hoeveel berichten op je wachten.

1.3 Waarom het bestaat

Sommige wijzigingen kun je niet stilletjes doorvoeren. Een nieuwe Joomla-versie kan een beveiligingsinstelling toevoegen die je zelf moet aanzetten, of een standaardwaarde wijzigen die je inhoud raakt. Een gewone e-mail of changelog mis je makkelijk. Een bericht dat in de beheeromgeving blijft staan, met een knop die de wijziging voor je uitvoert, negeer je veel moeilijker. Dat is precies het punt van com_postinstall: de juiste melding, op de juiste plek, op het juiste moment.

3. De drie berichttypen

Elk bericht heeft een type. Het type bepaalt of er een knop is en wat die knop doet. Er zijn precies drie typen.

3.1 message

Het eenvoudigste type. Er is geen actieknop, alleen de titel, de beschrijving en de beheerknoppen. Gebruik dit als je alleen wilt informeren.

3.2 link

De actieknop stuurt je naar een URL. De URL wordt bij het bericht opgeslagen. Een veelvoorkomend voorbeeld is een knop die een specifiek Opties-scherm opent: index.php?option=com_foobar&view=tools&task=installSampleData. De gebruiker klikt, Joomla stuurt door, en de gebruiker rondt de wijziging daar af.

3.3 action

Het krachtigste type. De knop roept een PHP-functie binnen de extensie aan. Joomla laadt een bestand, voert een benoemde functie uit, en de functie doet het werk. Zo kan een bericht zeggen "Klik hier om dit voor je op te lossen" en de oplossing daadwerkelijk toepassen bij de klik.

5. Berichtstatussen: Gepubliceerd, verborgen, gearchiveerd

Achter de knoppen zit een enkele kolom, enabled, die de status van elk bericht bewaart. Die heeft drie waarden.

Het lijstscherm laadt berichten waar enabled gelijk is aan 1 of 2, dus verborgen berichten (0) verschijnen nooit. De meldingenteller op het Systeemdashboard telt echter alleen de berichten met 1 (gepubliceerd), want dat zijn de berichten die nog je aandacht nodig hebben.

De knoppen wijzigen simpelweg deze ene waarde: Verbergen zet hem op 0, Archiveren zet hem op 2, Opnieuw lezen en Herstellen zetten hem terug op 1.

7. Onder de motorkap: Hoe berichten worden getoond

com_postinstall is een standaard Model-View-Controller (MVC)-component. Als je het scherm opent, is de flow rechttoe rechtaan.

1. De view vraagt het model (MessagesModel) om de berichten van de geselecteerde extensie.
2. Het model leest de rijen uit #__postinstall_messages waar enabled gelijk is aan 1 of 2.
3. Het model verwerkt de lijst na: het laadt de juiste taalbestanden en voert per bericht de weergaveconditie uit.
4. De template rendert elk overgebleven bericht als een kaart.

7.1 Condities bepalen de zichtbaarheid

Een bericht kan een condition_file en een condition_method dragen. Tijdens de naverwerking voegt het model het bestand in en roept de functie aan. Geeft de functie false terug, dan valt het bericht uit de lijst voordat het ooit getoond wordt. Zo kan een bericht alleen verschijnen wanneer het relevant is, bijvoorbeeld "toon dit alleen als de oude instelling nog actief is." Zodra de gebruiker het probleem oplost, geeft de conditie false terug en verdwijnt het bericht stilletjes.

7.2 Caching

Het model cachet zijn resultaten in de cachegroep com_postinstall, omdat berichten bij elke paginaweergave lezen en evalueren verspilling zou zijn. Telkens als een bericht van status verandert (verbergen, archiveren, opnieuw publiceren, herstellen), leegt de component deze cache zodat de lijst en de dashboardteller kloppen.

7.3 Taalbestanden laden

Voor het renderen laadt het model per bericht de taalextensie, via het frontend- of backendpad op basis van language_client_id. Daarom toont een bericht van com_foobar zijn eigen vertaalde titel en beschrijving, ook al weet com_postinstall niets van de bewoording van die extensie.

9. Je eigen Post-installatieberichten maken

Als je extensies bouwt, kun je je eigen berichten toevoegen. De gebruikelijke plek is het post-installatiescript van je extensie, het script dat Joomla uitvoert nadat je pakket is geinstalleerd of bijgewerkt. Je roept een methode aan op het com_postinstall-model en geeft een array met opties mee.

use Joomla\CMS\Factory;

$options = [
    'extension_id'       => $myExtensionId,
    'type'               => 'message',
    'title_key'          => 'COM_FOOBAR_POSTINSTALL_TITLE',
    'description_key'    => 'COM_FOOBAR_POSTINSTALL_DESCRIPTION',
    'language_extension' => 'com_foobar',
    'language_client_id' => 1,
    'version_introduced' => '2.0.0',
    'enabled'            => 1,
];

Factory::getApplication()
    ->bootComponent('com_postinstall')
    ->getMVCFactory()
    ->createModel('Messages', 'Administrator', ['ignore_request' => true])
    ->addPostInstallationMessage($options);

Het voorbeeld hierboven is een gewoon message: het eenvoudigste type en het type dat het meest waarschijnlijk gewoon werkt. De typen link en action hebben een paar sleutels meer nodig, zoals hieronder beschreven.

9.1 De verplichte opties

De methode valideert je invoer en gooit een duidelijke exception als er iets ontbreekt. De regels zijn:

• extension_id, type, title_key, description_key en language_extension zijn altijd verplicht.
• type moet exact message, link of action zijn.
• Voor link en action heb je ook een action_key en een condition_file plus condition_method nodig.
• Voor link zet je action op de URL. Voor action zet je action_file en action (de functienaam), en het bestand moet op schijf bestaan.

9.2 Het extension_id vinden

Elk bericht heeft het numerieke extension_id nodig van de extensie die het bezit. Die lees je uit de tabel #__extensions. Voor een component:

SELECT extension_id, name, type, element, client_id
FROM #__extensions
WHERE element = 'com_foobar';

Voor een plugin moet je ook de folder matchen, omdat dezelfde elementnaam in verschillende plugingroepen kan voorkomen:

SELECT extension_id, name, type, element, folder, client_id
FROM #__extensions
WHERE type = 'plugin'
  AND folder = 'system'
  AND element = 'foobar';

Binnen een installatie- of updatescript heb je geen ruwe SQL nodig: Joomla kent je eigen extensie-id al, dus lees die uit de installer-adapter in plaats van een nummer hard te coderen.

9.3 Toevoegen is veilig om te herhalen

De methode controleert of er al een rij bestaat met dezelfde extensie, type en titelsleutel. Is de definitie identiek, dan doet hij niets. Is hij gewijzigd, dan verwijdert hij de oude rij en voegt een nieuwe in. Zo kun je hem bij elke update aanroepen zonder duplicaten te maken, precies wat een post-installatiescript nodig heeft.

9.4 Een valkuil bij link-berichten

Wees voorzichtig met type = link als je het registreert via addPostInstallationMessage. In het huidige Joomla 6 valideert de methode een sleutel link, maar die sleutel hoort niet bij de geaccepteerde optielijst en wordt eruit gestript voordat de controle draait. Het praktische gevolg is dat een link-definitie "needs an action (URL)" kan gooien, zelfs als je de URL in de sleutel action hebt gezet zoals de documentatie voorschrijft.

Tot dit is opgelost zijn de veilige keuzes: gebruik message als je alleen wilt informeren, gebruik action voor een gecontroleerde interne taak, en heb je echt een link nodig, test die dan op een schone installatie van precies de Joomla-versie die je beoogt en inspecteer eerst MessagesModel::addPostInstallationMessage(). Een gewone databaserij werkt ook als je die zelf invoegt.

9.5 Beveiliging: action-berichten voeren PHP uit

Een action-bericht is krachtig juist omdat zijn knop een PHP-functie uit action_file uitvoert. Ga zorgvuldig met die kracht om.

• Houd de action_file binnen je eigen extensie. Wijs hem nooit naar door gebruikers aangeleverde of externe inhoud.
• Controleer binnen de functie de rechten van de gebruiker voordat je iets doet dat data wijzigt.
• Maak de actie idempotent, zodat twee keer op de knop klikken geen schade aanricht.
• Gebruik de conditiefunctie alleen om true of false terug te geven. Laat hem nooit data migreren, bestanden schrijven of instellingen wijzigen; condities draaien vaak, ook wanneer Joomla berichten telt.
• Log belangrijke wijzigingen en faal netjes, in plaats van invoer uit het verzoek te vertrouwen.

9.6 Hoe dit verschilt van enqueueMessage()

Joomla heeft een tweede, bekendere manier om een bericht te tonen: Factory::getApplication()->enqueueMessage('Saved successfully.'). Het lijkt erop, maar lost een ander probleem op. Post-installatieberichten zijn duurzaam; in de wachtrij gezette berichten niet.

Gebruik enqueueMessage() voor "je wijzigingen zijn opgeslagen"-feedback binnen een enkel verzoek. Gebruik com_postinstall voor begeleiding die op het dashboard moet blijven wachten tot de beheerder erop handelt.

11. Web services API

Veel Joomla-kerncomponenten leveren een REST API onder /api/index.php/v1/... zodat externe tools data kunnen lezen of wijzigen. com_postinstall is een bewuste uitzondering: het heeft geen Web Services API. Er is geen API-controller, geen openbare route en geen token-gebaseerd eindpunt voor post-installatieberichten.

De reden is praktisch. Deze berichten zijn kortlevende meldingen die alleen voor de beheeromgeving zijn en vaak PHP-acties uitvoeren of live condities evalueren. Ze blootstellen aan externe clients zou risico toevoegen zonder echte waarde. Moet je ze programmatisch lezen of opruimen, dan doe je dat binnen Joomla, via dezelfde modelmethode die de component zelf gebruikt, bijvoorbeeld vanuit een CLI-plugin:

use Joomla\CMS\Factory;

$model = Factory::getApplication()
    ->bootComponent('com_postinstall')
    ->getMVCFactory()
    ->createModel('Messages', 'Administrator', ['ignore_request' => true]);

$count = $model->getItemsCount();

Zo blijven de logica, de condities en de cacheafhandeling consistent met het scherm dat je in de beheeromgeving ziet.

13. Veelgemaakte fouten en valkuilen

13.1 Berichten als spam behandelen

Symptoom: Je klikt elke keer op "Alle verbergen" zonder de berichten te lezen.

Oplossing: Berichten na de installatie komen zelden voor en zijn meestal belangrijk. Lees elk bericht voordat je het verbergt. Veel berichten gaan over een beveiligingswijziging of een wijziging in het gedrag waarvan je echt op de hoogte moet zijn.

13.2 Denken dat verborgen verwijderd betekent

Symptoom: Je hebt een bericht verborgen en kunt het nu niet meer terugvinden.

Oplossing: Verborgen berichten worden niet verwijderd, alleen op enabled = 0 gezet. Gebruik de knop Berichten herstellen op het lege-staatscherm om ze allemaal terug te halen, of Opnieuw lezen voor een gearchiveerd bericht.

13.3 Naar de verkeerde extensie kijken

Symptoom: Een bericht dat je verwachtte, staat niet in de lijst.

Oplossing: Het scherm filtert op extensie. Standaard toont het de Joomla core extensies. Gebruik de keuzelijst Berichten weergeven voor om naar de extensie te wisselen die het bericht achterliet.

13.4 Ontwikkelaar: Ontbrekend conditiebestand

Symptoom: addPostInstallationMessage gooit een exception tijdens de installatie.

Oplossing: Voor de typen link en action moet het condition_file (en, voor acties, het action_file) op schijf bestaan op het moment dat je het bericht registreert. Controleer je RAD-pad-voorvoegsel (admin:// of site://) en of het bestand in je pakket wordt meegeleverd.

13.5 Ontwikkelaar: Verkeerde taalinstellingen

Symptoom: De kaart toont ruwe sleutels zoals COM_FOOBAR_POSTINSTALL_TITLE in plaats van tekst.

Oplossing: Zet language_extension op de extensie die de sleutels bezit en language_client_id op de juiste kant (1 voor backend, 0 voor frontend), en zorg dat het taalbestand is geinstalleerd.

13.6 Ontwikkelaar: foutmelding bij registratie van een linkbericht

Symptoom: Het registreren van een bericht met type = link via addPostInstallationMessage verschijnt de foutmelding „needs an action (URL)”, ook al heb je de URL opgegeven.

Oplossing: Dit is een bekende validatiefout in de huidige versie van Joomla 6, waarbij de methode controleert op een link-sleutel die al uit de opties is verwijderd. Gebruik in plaats daarvan ‘message’ of ‘action’, of voeg de rij rechtstreeks in, en test linkberichten op de exacte Joomla-versie waarop u zich richt. Zie paragraaf 9.4.

15. In het kort

SCHERM
  Systeem > Beheren > Post-installatieberichten
  URL: index.php?option=com_postinstall

BERICHTTYPEN
  message   alleen informatief, geen knop
  link      knop opent een URL
  action    knop voert een PHP-functie uit

STATUSSEN (kolom enabled)
  1   gepubliceerd   getoond als actieve kaart
  2   gearchiveerd   getoond met "Opnieuw lezen"
  0   verborgen      opgeslagen maar niet getoond

KNOPPEN
  Verberg dit bericht       enabled -> 0
  Archiveren                enabled -> 2
  Opnieuw lezen             enabled -> 1 (vanuit gearchiveerd)
  Alle berichten verbergen  alles van een extensie -> 0
  Berichten herstellen      alles van een extensie -> 1

DATABASE
  #__postinstall_messages   een rij per bericht

RAD-PAD-VOORVOEGSELS
  site://    -> siteroot (JPATH_ROOT)
  admin://   -> administrator (JPATH_ADMINISTRATOR)

ONTWIKKELAARS-API
  bootComponent('com_postinstall')
    ->getMVCFactory()
    ->createModel('Messages', 'Administrator', ['ignore_request' => true])
    ->addPostInstallationMessage($options);

RECHTEN
  core.manage       openen en lezen
  core.edit.state   verbergen / archiveren / opnieuw publiceren
  core.admin        Opties-scherm

WEB SERVICES API
  geen (geen REST-eindpunt)