Management of CakePHP plugins has changed significantly since Cake 2, largely due to the use of PHP Autoloading in Cake 4. The least bad way to handle this in a production environment is to install plugins via composer, though such procedures are not yet formalized for Registry PE. This document currently describes how to write plugins that will ship with Registry (either core or available).

In addition, Registry Plugins have been redesigned to address various long standing problems. All plugins are expected to be instantiated, with improved common libraries to simplify the design of new plugin types. Instantiations now refer to plugins via Plugin.Model notation, creating a generalized solution for polymorphic plugins (plugins that can implement more than one plugin type) as well as multiple entry points (so a single plugin can easily provide multiple functions).

Terminology

• Activation: The act of enabling an Available Plugin. Only a Platform Administrator can activate an Available Plugin.
• Available Plugin: A Registry Plugin that is shipped with the application but is not enabled by default.
• Cake Plugin: An application within an application.
• Core Plugin: A Registry Plugin that is shipped with the application and cannot be disabled.
• Entry Point Model: Within a Registry Plugin, a Model that implements a Plugin Type.
• Installation: The act of adding a Cake Plugin to the Registry application filesystem.
• Instantiation: The act of creating a new configuration with a CO that leverages a Registry Plugin.
• Local Plugin: A Registry Plugin added by a deployer.
• Pluggable Model: The core Registry model that understands Registry Plugins of a given type. Example include ExternalIdentitySource and Report.
• Plugin: The unqualified term "Plugin" generally means "Registry Plugin".
• Plugin Type: The type of a plugin, which is derivable from the Pluggable Model via "underscore" inflection. So ExternalIdentitySource plugins are of type external_identity_source. (underscore is used rather than dasherize so that the type can be easily converted back via classify or camelize.)
• Registry Plugin: A Cake Plugin with additional syntax or requirements.

Creating a New Plugin

Bake

The easiest way to create the structure for the new plugin is with Cake's bake command.

While there are no longer technical requirements around the construction of a plugin's name, it is still advisable for the plugin to be named in a way that describes its primary purpose, such as SqlSource or NightlyReport.

Pick an appropriate location for the plugin: Core Plugins should go in app/plugins, Available Plugins should go in app/availableplugins, and Local Plugins should go in local/plugins.

$ cd $SRC/app
$ ./bin/cake bake plugin MyPlugin
1. /src/comanage/git/registry-pe/app/plugins/
2. /src/comanage/git/registry-pe/app/availableplugins/
3. /src/comanage/git/registry-pe/app/../local//plugins/
Choose a plugin path from the paths above.
> 2

Allow composer.json to be overwritten, this is how the autoloader paths will be updated.

Modifying composer autoloader

File `/src/comanage/git/registry-pe/app/composer.json` exists
Do you want to overwrite? (y/n/a/q) y

It's not obvious from the command output, but app/src/Application.php will also be updated to load the plugin. This change is not needed  (Registry will automatically load activated plugins) and should be reverted.

plugin.json

Within the plugin directory, create the file src/config/plugin.json. This file contains a single JSON document, with the following top level members:

• schema: The database schema for this plugin. This uses the same format as the main schema.json file, and will inherit definitions from that file's columnLibrary.
  • In general, a plugin-type specific foreign key column (eg: reports_id) is defined for each plugin type to simplify schema definition.
  • For information on applying the database schema, see Activating Plugins, below.
• types: The Plugin Type(s) supported by this plugin. Within each Plugin Type, a list of Entry Point Models for that type implemented by the plugin.

Plugin Types

The following Plugin Types are supported:

{
   "types": {
      "report": [
         "PersonStatusReports"
      ]
   },
   "schema": {
      "tables": {
         "person_status_reports": {
            "columns": {
               "id": {},
               "report_id": { "type": "integer", "foreignkey": { "table": "reports", "column": "id" }, "notnull": true },
               "status": {}
            },
            "indexes": {
               "person_status_reports_i1": { "columns": [ "report_id" ] }
            }
         }
      }
   }
}

Entry Point Models

Plugins must implement at least one Entry Point Model for each supported Plugin Type. Entry Point Models belongTo the Pluggable Model. For example, PersonStatusReports belongsTo Reports. Plugins may implement additional models beyond the Entry Point Model, these do not need to be registered in plugin.json. There are no naming requirements for Entry Point Models, but it is recommended that the name references the Plugin Type (and in many cases may be the same as or similar to the plugin name).

Requirements for Entry Point Models vary by Plugin Type (see Additional Requirements By Plugin Type, below).

Plugin Instantiation

A Plugin is instantiated when an administrator creates a new instance of a Pluggable Model. As part of this process, a skeletal instance of the Entry Point Model is created, populated only with a foreign key to the Pluggable Model (AR-Plugin-9). Validation and Application Rules are not executed when this record is created. The administrator is then redirected to the edit view for the Entry Point Model (/plugin/controller/edit/#).

If the Pluggable Model is deleted, the Entry Point Model associated with it is also deleted (AR-Plugin-10).

Plugins do not need to (and generally should not) implement add or delete actions for their Entry Point Models.

Localizations

Registry PE uses the standard Cake localization mechanisms. Following convention, plugins should use the underscored version of their name as the domain for translation.

# In $PLUGIN/resources/locales/en_US/my_plugin.po
msgid "welcome"
msgstr "Welcome to My Plugin"

# In some code
print __d('my_plugin', 'welcome');

Standard Views

StandardController will automatically look for view templates columns.inc and fields.inc for index and add/edit/view operations, respectively.

Notes for Committing Plugins

For Core and Available Plugins, be sure to commit the changes to composer.json, vendor/composer/autoload_psr4.php, and vendor/composer/autoload_static.php, but not Application.php.

Installing Plugins

Procedures for local plugins have not yet been defined (CFM-243).

Moving Plugins

If a Plugin is moved between directories (eg: from availableplugins to plugins) several steps are required:

1. The autoload paths must be updated in composer.json (update both autoload and autoload-dev).
2. Tell composer to dump the new autoload paths.
   1. composer dumpautoload
3. Clear thecaches.
   1. ./bin/cake cache clear_all
4. Update the Plugin Registry, as described in Activating Plugins, below.

Activating Plugins

Plugins are activated by a Platform Administrator. Within the COmanage CO, go to Configuration > Plugins. Loading this page will refresh the Plugin Registry (AR-Plugin-11), the new Plugin should be available in the list of Plugins. Activate the Plugin via the Activate menu item. This will also apply the database schema defined in schema.json.  The database schema can manually be applied via the Apply Database Schema menu item.