Articirra Cache Rules 1.1.9
Copyright (C) 2026 Jouweb Agency. GNU GPL version 2 or later.
Full licence: LICENSE.txt. Website: https://jouweb.co.za

PURPOSE
Clear Joomla cache groups automatically after selected events. This is a
system plugin with configurable rules. It does not require cron, a Scheduled
Task, an API key, RAXO, or an external service to perform cache clearing.
It does not purge browser, CDN, hosting or private extension caches outside
Joomla's cache API.

REQUIREMENTS AND COMPATIBILITY
Intended platforms: Joomla 5 and Joomla 6. Minimum Joomla 5.0 / PHP 8.1;
Joomla 6 requires PHP 8.3. The installer rejects older platforms. Joomla 7
compatibility is not claimed. Joomla 6 remains pending a clean runtime test.
No particular cache backend beyond Joomla's API is required. Clear all needs
a backend capable of enumerating groups. Shared-memory backends need separate
testing and may share group namespaces across cache locations.

INSTALLATION / UPGRADE
Upload the plugin ZIP through System > Install > Extensions. Install over the
existing system plugin to retain its identity, enabled state and saved rules.
Then open System > Manage > Plugins > System - Articirra Cache Rules.
Enable it and review the rules. The original internal element
jouwebcacheclear is retained for compatible upgrades.
An earlier Content - Jouweb Article Cache Clear plugin is disabled if found;
on first installation its enabled state is transferred. Do not enable both.
The one-time 1.1.5 migration changes Site-only article-save rules to Both;
other settings are retained. Later manual location choices are respected.

CONFIGURE RULES
Each rule has a name, enabled state, trigger events, clearing mode and cache
location. Any selected trigger can run the rule. Both locations is recommended:
frontend caches may be stored under the administrator cache directory.
The initial article rule selects com_content and mod_raxo_content_spotlight.
RAXO is an example cache group, not a required extension. Newly added rules
have no automatic group selections. Disable/delete rules to stop them.
An explicitly empty rules list means no clearing; absent legacy settings use
the initial article rule.

SELECTED CACHE GROUPS
Select the named groups that should be cleared. The searchable picker lists
groups exposed by Joomla's cache API. Labels show where groups were found;
Cache location determines where clearing occurs. Saved selections remain
available even when no files currently exist. Viewing settings does not clear
caches. Populate caches by visiting pages, then reopen settings to discover them.

CLEAR ALL CACHE GROUPS
Choose Clear all cache groups, the trigger events and location. The individual
group picker is hidden, and any saved group selections are ignored. All mode
discovers groups each time the event occurs, then clears them individually.
A backend that cannot enumerate groups produces a warning: choose Selected
mode on that backend. It does not flush an entire shared cache server.
Concurrent requests can rebuild caches during or immediately after clearing.

TRIGGERS
Article save/delete/state change; module, banner, category, menu item, contact
and tag saves; content-model saves; extension-settings saves; successful
extension installation/update/removal; successful user save/delete; Joomla
core update completion. Direct SQL changes do not dispatch these events.
Custom event names and optional exact contexts are supported. No PHP code is
entered or evaluated. Custom listeners register after initialisation; earlier
events and onAfterInitialise are unsupported. Prefer after-events: arbitrary
third-party events may fire before completion or on failure. Built-in installer
and user success checks also apply when those events are selected as custom.

CONFIRMATION AND LOGGING
Show cache-clearing confirmation is enabled by default. It applies to all
matched administrator triggers, including installer uploads using JSON.
Successful API calls list cleared groups. Empty locations are reported;
discovery/clearing failures produce warnings. Frontend/API applications receive
no confirmation. No matching rule or a disabled confirmation option means no
message. A successful clean call may mean a group was already empty; the
message does not prove physical file counts or visible content changed.
Log successful cache clearing is optional. Failures/invalid group names are
logged regardless in jouweb-cache-clear.php in Joomla's configured log folder.
Cache maintenance failures do not interrupt completed operations.

TESTING
1. Visit relevant pages to populate caches; note groups/file counts in Clear Cache.
2. Perform a selected trigger. Check the message and cache list before loading
   the frontend, which may rebuild files. Check the visible content afterwards.
3. Test Selected/All and Site/Administrator/Both; save/reopen settings to verify.
4. For installer triggers, install/update another extension. Updating the cleaner
   itself can use the previously loaded version during that request.
5. Check disabled rules, unrelated groups, empty caches and warning behaviour.

UPDATES AND UNINSTALL
Joomla checks https://jouweb.co.za/updates/articirra-cache-rules.xml for updates.
The publisher must deploy that feed and its referenced ZIP before public release.
Disable or uninstall via Joomla's normal extension manager. No custom tables
or scheduled tasks are created. Existing cached files are not deleted simply
by uninstalling the plugin. A previously disabled legacy plugin stays disabled.

1.1.9 CHANGES
Full GPL licence/copyright notices; minimum platform preflight checks;
update-server declaration; rewritten documentation and release materials.
Cache-clearing logic is unchanged from 1.1.7.

VALIDATION STATUS
Package/XML integrity and static source checks completed. Article-save cache
clearing was verified on ABR Buzz Joomla 5.4.10; the user confirmed 1.1.7
installer-trigger confirmations. Those observations do not establish clean
1.1.9 installation/migration/uninstall, Joomla 6 or other cache-backend support.
PHP lint, JED Checker and the clean Joomla 5/6 runtime matrix remain outstanding.

1.1.9 FIX
Cache discovery and maintenance explicitly enable their cache controller,
independent of Joomla global caching. This allows existing groups to be
listed and cleared even when System Cache is OFF. Global configuration is
not changed and page caching is not enabled by this maintenance operation.
