J6.1 plugin constructor: drop DispatcherInterface arg (deprecation)

CHANGELOG.md

@@ -42,6 +42,9 @@ All notable changes to the Joomla skill are documented here. The format follows
 - `references/component.md` — `\Namespace\Component\Example\…` typos in two `@var` type-hint comments (List and Edit views) replaced with `\Vendor\…` so IDEs resolve the model class correctly.
 - `references/component.md` — `CustomlistField` example was calling `HTMLHelper::_('select.option', …)` without importing `Joomla\CMS\HTML\HTMLHelper`. Added the missing `use` statement so the example runs as-is.
 - `references/component.md` — Install/Update Script section now opens with an explicit scope split: PHP lifecycle hooks here, DDL in the new Database Schema & Migrations section. Adds a forward cross-link to the schema section, a reverse note in the migrations section, and a one-line guard against the common mistake of putting `ALTER TABLE` in `postflight()` (races during partial upgrades because schema files run first). Bumped the install-script `$minimumPhp` example from `'8.2.0'` to `'8.3.0'` to match the J6.x floor; the previous value was missed in the SKILL.md PHP audit because it lives in the reference, not the SKILL itself.
+- `references/plugin.md` — Service-provider example updated to the **Joomla 6.1+** `CMSPlugin::__construct($config = [])` signature (single arg, no `DispatcherInterface`). The legacy two-arg form is documented as a J5/J6.0 backward-compat option that emits `E_USER_DEPRECATED` on J6.1 and will be removed in J7.0. Quote of the deprecation message and a permalink to [`libraries/src/Plugin/CMSPlugin.php` on `joomla-cms` `6.1-dev`](https://github.com/joomla/joomla-cms/blob/6.1-dev/libraries/src/Plugin/CMSPlugin.php) included so the citation doesn't drift. Verified against [PR #46683](https://github.com/joomla/joomla-cms/pull/46683) and the migrated `plg_captcha_powcaptcha` provider.
+- `references/plugin.md` — Removed the now-dead `use Joomla\Event\DispatcherInterface;` import from the plugin class example (it was only there to satisfy the old constructor's typed parameter).
+- `references/service-provider.md` — Plugin row in the "what each extension type registers" table updated: plugins don't use any `Service\Provider\*` factory shorthand; the provider just `new`s the class with `$config`. Added the J6.0 → J6.1+ deprecation note pointing at `references/plugin.md` for the full story.
 
 ### Fixed
 - Removed brand-specific references (CWM / Proclaim / EventBooking) from `SKILL.md` and `references/module.md`. The skill is generic Joomla guidance and shouldn't lean on specific third-party extension code or naming conventions as canonical examples. Replaced with vendor-neutral placeholders (`<Vendor>`, `Acme`, generic `bookings`/`items`) and a generic note about projects shipping admin + site modules in one source tree. The `Joomla-Bible-Study/claude-skill-joomla` GitHub URL stays — that's the skill's own home, not borrowed code.

skills/joomla/references/plugin.md

@@ -85,6 +85,8 @@ Key points:
 
 **File:** `services/provider.php`
 
+The Joomla 6.1+ pattern: instantiate the plugin with **just** `(array) PluginHelper::getPlugin($group, $element)`. Don't pass a dispatcher — `CMSPlugin::__construct()` no longer accepts one (see the J6.0 → J6.1 callout below).
+
 ```php
 <?php
 
@@ -95,7 +97,6 @@ use Joomla\CMS\Factory;
 use Joomla\CMS\Plugin\PluginHelper;
 use Joomla\DI\Container;
 use Joomla\DI\ServiceProviderInterface;
-use Joomla\Event\DispatcherInterface;
 use Vendor\Plugin\Content\Example\Extension\Example;
 
 return new class () implements ServiceProviderInterface {
@@ -104,9 +105,7 @@ return new class () implements ServiceProviderInterface {
         $container->set(
             PluginInterface::class,
             function (Container $container) {
-                $dispatcher = $container->get(DispatcherInterface::class);
-                $plugin     = new Example(
-                    $dispatcher,
+                $plugin = new Example(
                     (array) PluginHelper::getPlugin('content', 'example')
                 );
                 $plugin->setApplication(Factory::getApplication());
@@ -118,6 +117,28 @@ return new class () implements ServiceProviderInterface {
 };
 ```
 
+### Joomla 6.0 / 6.1 / 7.0 — dispatcher constructor change
+
+**Before (J5 and J6.0):** `CMSPlugin::__construct(DispatcherInterface $dispatcher, array $config = [])`. Service providers had to fetch the application dispatcher and pass it as the first argument:
+
+```php
+// Legacy two-arg form — works on J5 and J6.0, deprecated on J6.1+, removed in J7.0
+$dispatcher = $container->get(DispatcherInterface::class);
+$plugin     = new Example($dispatcher, (array) PluginHelper::getPlugin('content', 'example'));
+```
+
+**After (J6.1+):** `CMSPlugin::__construct($config = [])`. The dispatcher is no longer a constructor concern — `SubscriberInterface` plugins register their listeners on the application's main dispatcher via `getSubscribedEvents()`, no per-plugin dispatcher reference required.
+
+If you call the legacy two-arg form on J6.1, `CMSPlugin` still accepts it but emits `E_USER_DEPRECATED`:
+
+> Passing an instance of `Joomla\Event\DispatcherInterface` to `Joomla\CMS\Plugin\CMSPlugin::__construct()` will not be supported in 7.0.
+
+(verified against [`libraries/src/Plugin/CMSPlugin.php` on `joomla-cms` `6.1-dev`](https://github.com/joomla/joomla-cms/blob/6.1-dev/libraries/src/Plugin/CMSPlugin.php))
+
+**If your plugin needs to dispatch its own events** (rare — the typical `SubscriberInterface` flow doesn't need this), implement `Joomla\Event\DispatcherAwareInterface` on the plugin class directly and inject the dispatcher with `$plugin->setDispatcher($container->get(DispatcherInterface::class))` from the service provider. Don't rely on `CMSPlugin` providing it; that wiring is being removed in 7.0.
+
+**Backward-compat with J5 / J6.0:** if your extension must support pre-6.1, keep the legacy two-arg form and accept the deprecation warning on J6.1. There is no single call form that works cleanly across 5.x, 6.0, and 6.1+. Pick the floor your extension targets.
+
 ---
 
 ## Plugin Class with SubscriberInterface
@@ -134,7 +155,6 @@ namespace Vendor\Plugin\Content\Example\Extension;
 \defined('_JEXEC') or die;
 
 use Joomla\CMS\Plugin\CMSPlugin;
-use Joomla\Event\DispatcherInterface;
 use Joomla\Event\SubscriberInterface;
 
 final class Example extends CMSPlugin implements SubscriberInterface

skills/joomla/references/service-provider.md

@@ -58,7 +58,7 @@ return new class () implements ServiceProviderInterface {
 |------|----------------|------------------|
 | Component | `ComponentInterface` | `MVCFactory`, `ComponentDispatcherFactory`, `RouterFactory`, `CategoryFactory` (when the component has categories) |
 | Module | `ModuleInterface` | `ModuleDispatcherFactory`, `HelperFactory` (newer modules) |
-| Plugin | `PluginInterface` | `PluginFactory` — wraps the plugin class so Joomla can instantiate it with its `$dispatcher`, `$config`, `$params` |
+| Plugin | `PluginInterface` | None of the `Service\Provider\*` factory shorthands — the provider just `new`s the plugin class with its `$config` array. **On Joomla 6.1+** the constructor takes only `$config` (the legacy `($dispatcher, $config)` two-arg form still works but emits a deprecation warning and will be removed in 7.0; see `references/plugin.md`). |
 
 For a complete worked example see the **Service Provider** section of the relevant reference (`references/component.md`, `references/module.md`, `references/plugin.md`).