Postinstall messages in Joomla

1. The Basics

1.1 What com_postinstall Is

com_postinstall is a small core component that shows post-installation and upgrade messages. When Joomla itself, or one of your extensions, needs to tell you something right after an install or update, it stores a message and com_postinstall displays it. The official description is short and exact: "Displays post-installation and post-upgrade messages for Joomla and its extensions."

It is an administrator-only component. It has no frontend, no articles, and no public URL. It exists to deliver one-time notices to the people who run the site.

If you ever saw a Joomla notice like "Your old TinyMCE setting changed, click here to review it," that was com_postinstall.

1.2 Where to Find It

The screen lives under the System menu in the administrator:

System
 └─ Manage
     └─ Post-installation Messages

The full title of the page is Post-installation and Upgrade Messages. Its URL is index.php?option=com_postinstall in the administrator. You can also reach it from the System Dashboard, where a small notification panel shows how many messages wait for you.

1.3 Why It Exists

Some changes cannot be applied silently. A new Joomla version might add a security setting that you must turn on yourself, or change a default that affects your content. A normal email or changelog is easy to miss. A message that sits in the administrator, with a button that performs the change for you, is much harder to ignore. That is the whole point of com_postinstall: the right notice, in the right place, at the right time.

3. The Three Message Types

Every message has a type. The type decides whether there is a button and what the button does. There are exactly three types.

3.1 message

The simplest type. There is no action button, only the title, the description, and the management buttons. Use it when you only need to inform.

3.2 link

The action button sends you to a URL. The URL is stored with the message. A common example is a button that opens a specific Options screen: index.php?option=com_foobar&view=tools&task=installSampleData. The user clicks, Joomla redirects, and the user finishes the change there.

3.3 action

The most powerful type. The button calls a PHP function inside the extension. Joomla loads a file, runs a named function, and the function does the work. This is how a message can say "Click here to fix this for you" and actually apply the fix when clicked.

5. Message States: Published, Hidden, Archived

Behind the buttons there is a single column, enabled, that holds the state of every message. It has three values.

The list screen loads messages where enabled is 1 or 2, so hidden messages (0) never appear. The notification count on the System Dashboard, however, counts only the 1 (published) messages, because those are the ones that still need your attention.

The buttons simply change this one value: Hide sets it to 0, Archive sets it to 2, Read Again and Reset set it back to 1.

7. Under the Hood: How Messages Are Displayed

com_postinstall is a standard Model-View-Controller (MVC) component. When you open the screen, the flow is straightforward.

1. The view asks the model (MessagesModel) for the messages of the selected extension.
2. The model reads the rows from #__postinstall_messages where enabled is 1 or 2.
3. The model post-processes the list: it loads the right language files and runs each message's display condition.
4. The template renders each surviving message as a card.

7.1 Conditions Decide Visibility

A message can carry a condition_file and a condition_method. During post-processing the model includes the file and calls the function. If the function returns false, the message is dropped from the list before it is ever shown. This is how a message can appear only when it is relevant, for example "only show this if the old setting is still active." Once the user fixes the problem, the condition returns false and the message quietly disappears.

7.2 Caching

The model caches its results in the com_postinstall cache group, because reading and evaluating messages on every page load would be wasteful. Whenever a message changes state (hide, archive, republish, reset), the component clears this cache so the list and the dashboard count stay correct.

7.3 Language Loading

Before rendering, the model loads each message's language extension, using the frontend or backend path based on language_client_id. This is why a message from com_foobar shows its own translated title and description, even though com_postinstall knows nothing about that extension's wording.

9. Creating Your Own Post-installation Messages

If you build extensions, you can add your own messages. The usual place is your extension's post-installation script, the script Joomla runs after your package is installed or updated. You call one method on the com_postinstall model and pass an array of options.

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);

The example above is a plain message: the simplest type and the one most likely to just work. The link and action types need a few more keys, described below.

9.1 The Required Options

The method validates your input and throws a clear exception when something is missing. The rules are:

• extension_id, type, title_key, description_key, and language_extension are always required.
• type must be exactly message, link, or action.
• For link and action, you also need an action_key and a condition_file plus condition_method.
• For link, set action to the URL. For action, set action_file and action (the function name), and the file must exist on disk.

9.2 Finding the extension_id

Every message needs the numeric extension_id of the extension that owns it. You can read it from the #__extensions table. For a component:

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

For a plugin you must also match the folder, because the same element name can exist in different plugin groups:

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

Inside an install or update script you do not need raw SQL: Joomla already knows your own extension id, so read it from the installer adapter instead of hard-coding a number.

9.3 Adding Is Safe to Repeat

The method checks for an existing row with the same extension, type, and title key. If the definition is identical, it does nothing. If it changed, it removes the old row and inserts the new one. This means you can call it on every update without creating duplicates, which is exactly what a post-installation script needs.

9.4 A Caveat With link Messages

Be careful with type = link when you register it through addPostInstallationMessage. In current Joomla 6 the method validates a link key, but that key is not part of the accepted option list and is stripped out before the check runs. The practical result is that a link definition can throw "needs an action (URL)" even when you supplied the URL in the action key as the documentation says.

Until this is resolved, the safe choices are: use message when you only need to inform, use action for a controlled internal task, and if you really need a link, test it on a clean install of the exact Joomla version you target and inspect MessagesModel::addPostInstallationMessage() first. A plain database row also works if you insert it yourself.

9.5 Security: action Messages Run PHP

An action message is powerful precisely because its button executes a PHP function from action_file. Treat that power with care.

• Keep the action_file inside your own extension. Never point it at user-supplied or remote content.
• Inside the function, check the user's permissions before doing anything that changes data.
• Make the action idempotent, so clicking the button twice does no harm.
• Use the condition function only to return true or false. Never let it migrate data, write files, or change settings; conditions run often, including when Joomla counts messages.
• Log important changes and fail gracefully, rather than trusting request input.

9.6 How This Differs From enqueueMessage()

Joomla has a second, more familiar way to show a message: Factory::getApplication()->enqueueMessage('Saved successfully.'). It looks similar but solves a different problem. Post-installation messages are durable; enqueued messages are not.

Use enqueueMessage() for "your changes were saved" feedback during a single request. Use com_postinstall for guidance that must wait on the dashboard until the administrator acts on it.

11. Web Services API

Many Joomla core components ship a REST API under /api/index.php/v1/... so external tools can read or change data. com_postinstall is a deliberate exception: it has no Web Services API. There is no API controller, no public route, and no token-based endpoint for post-installation messages.

The reason is practical. These messages are short-lived, administrator-only notices that often run PHP actions or evaluate live conditions. Exposing them to remote clients would add risk without adding real value. If you need to read or clear them programmatically, you do it inside Joomla, through the same model method that the component itself uses, for example from a CLI plugin:

use Joomla\CMS\Factory;

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

$count = $model->getItemsCount();

This keeps the logic, the conditions, and the cache handling consistent with the screen you see in the administrator.

13. Common Mistakes and Pitfalls

13.1 Treating Messages as Spam

Symptom: You click "Hide All" without reading, every time.

Fix: Post-installation messages are rare and usually important. Read each one before hiding it. Many describe a security or behaviour change you genuinely need to know about.

13.2 Thinking Hidden Means Deleted

Symptom: You hid a message and now you cannot find it again.

Fix: Hidden messages are not deleted, only set to enabled = 0. Use the Reset Messages button on the empty-state screen to bring them all back, or Read Again for an archived one.

13.3 Looking at the Wrong Extension

Symptom: A message you expected is not in the list.

Fix: The screen filters by extension. By default it shows the Joomla core. Use the Showing messages for dropdown to switch to the extension that left the message.

13.4 Developer: Missing Condition File

Symptom: addPostInstallationMessage throws an exception during install.

Fix: For link and action types, the condition_file (and, for actions, the action_file) must exist on disk at the moment you register the message. Check your RAD path prefix (admin:// or site://) and that the file ships in your package.

13.5 Developer: Wrong Language Settings

Symptom: The card shows raw keys like COM_FOOBAR_POSTINSTALL_TITLE instead of text.

Fix: Set language_extension to the extension that owns the keys and language_client_id to the right side (1 for backend, 0 for frontend), and make sure the language file is installed.

13.6 Developer: link Message Throws on Registration

Symptom: Registering a type = link message with addPostInstallationMessage throws "needs an action (URL)", even though you set the URL.

Fix: This is a known validation quirk in current Joomla 6, where the method checks a link key that it has already stripped from the options. Use message or action instead, or insert the row directly, and test link messages on the exact Joomla version you target. See section 9.4.

15. Quick Reference

SCREEN
  System > Manage > Post-installation Messages
  URL: index.php?option=com_postinstall

MESSAGE TYPES
  message   informative only, no button
  link      button opens a URL
  action    button runs a PHP function

STATES (enabled column)
  1   published   shown as active card
  2   archived    shown with "Read Again"
  0   hidden      stored but not shown

BUTTONS
  Hide this message   enabled -> 0
  Archive             enabled -> 2
  Read Again          enabled -> 1 (from archived)
  Hide All Messages   all of one extension -> 0
  Reset Messages      all of one extension -> 1

DATABASE
  #__postinstall_messages   one row per message

RAD PATH PREFIXES
  site://    -> site root (JPATH_ROOT)
  admin://   -> administrator (JPATH_ADMINISTRATOR)

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

PERMISSIONS
  core.manage       open and read
  core.edit.state   hide / archive / republish
  core.admin        Options screen

WEB SERVICES API
  none (no REST endpoint)