phpengine/specs/rules/add-plugin.md

Read this when adding or changing a discoverable PHP plugin, permission, or menu entry.

Add or Change a Plugin

1. Use the discovery convention. Create a directory below src/Modules/ with an initializer named after the directory. Its namespace must follow the path and the class must extend PluginStrategy.

   namespace Modules\Example;
   
   use Core\System\PluginStrategy;
   
   class Example extends PluginStrategy
   {
      public function __construct()
      {
      }
   }
   

2. Always define a constructor. The PluginStrategy base constructor throws an exception, so every plugin must declare its own __construct(), even if empty (see the example above).

3. Keep plugin construction safe at boot. ApplicationComposition instantiates every valid plugin after System; configuration, database, and framework globals are then available.

4. Use persistent numeric permission IDs. Use the existing catalog ID defined by the subsystem, such as permission ID 2 for Inventory Monitor. Permission ID 1 is reserved for administrator authorization.

5. Register menu entries through AddMenuItem(). Use a numeric permissionId for protected entries. The method publishes entries only when the restored user has the required permission.

   $this->AddMenuItem('Inventory Monitor', ['url' => 'inventory', 'permissionId' => 2]);
   

6. For API behavior, add routes in Core\Api\Api, not in the new plugin. Follow add-api-endpoint.md.

7. For an interactive page, add a matching React route and ensure the navigation URL resolves under the application base path. The implemented Inventory Monitor page uses /inventory; frontend route guards are not a substitute for API authorization.

8. Update documentation. Add the subsystem to module index; create a domain spec only if it introduces a non-obvious data model and business contracts.

See backend conventions and file structure.