Plugins

CakePHP allows you to set up a combination of controllers, models,and views and release them as a pre-packaged application plugin thatothers can use in their CakePHP applications. If you’ve createdgreat user management, a simple blog, or web service adapters in one ofyour applications, why not package it as a CakePHP plugin? This way youcan reuse it in your other applications, and share with the community!

A CakePHP plugin is separate from the host application itself and generallyprovides some well-defined functionality that can be packaged up neatly, andreused with little effort in other applications. The application and the pluginoperate in their own respective spaces, but share the application’sconfiguration data (e.g. database connections, email transports)

In CakePHP 3.0 each plugin defines its own top-level namespace. For example:DebugKit. By convention, plugins use their package name as their namespace.If you’d like to use a different namespace, you can configure the pluginnamespace, when plugins are loaded.

Installing a Plugin With Composer

Many plugins are available on Packagistand can be installed with Composer. To install DebugKit, youwould do the following:

php composer.phar require cakephp/debug_kit

This would install the latest version of DebugKit and update yourcomposer.json, composer.lock file, updatevendor/cakephp-plugins.php, and update your autoloader.

Manually Installing a Plugin

If the plugin you want to install is not available onpackagist.org, you can clone or copy the plugin code into your pluginsdirectory. Assuming you want to install a plugin named ‘ContactManager’, youshould have a folder in plugins named ‘ContactManager’. In this directoryare the plugin’s src, tests and any other directories.

Manually Autoloading Plugin Classes

If you install your plugins via composer or bake you shouldn’t need toconfigure class autoloading for your plugins.

If we were installing a plugin named MyPlugin manually you would need tomodify your application’s composer.json file to contain the followinginformation:

{
    "autoload": {
        "psr-4": {
            "MyPlugin\\": "plugins/MyPlugin/src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "MyPlugin\\Test\\": "plugins/MyPlugin/tests/"
        }
    }
}

If you are using vendor namespaces for your plugins, the namespace to path mappingshould resemble the following:

{
    "autoload": {
        "psr-4": {
            "AcmeCorp\\Users\\": "plugins/AcmeCorp/Users/src/",
            "AcmeCorp\\Users\\Test\\": "plugins/AcmeCorp/Users/tests/"
        }
    }
}

Additionally, you will need to tell Composer to refresh its autoloading cache:

php composer.phar dumpautoload

If you are unable to use Composer for any reason, you can also configureautoloading with Plugin:

Plugin::load('ContactManager', ['autoload' => true]);

Deprecated since version 3.7.0: Plugin::load() and autoload option are deprecated.

Note

IMPORTANT: autoload option is not available on addPlugin(), you should use composer dumpautoload instead.

Loading a Plugin

If you want to use a plugin’s routes, console commands, middleware, or eventlisteners you will need to load the plugin. Plugins are loaded in yourapplication’s bootstrap() function:

// In src/Application.php. Requires at least 3.6.0
use Cake\Http\BaseApplication;
use ContactManager\Plugin as ContactManagerPlugin;
 
class Application extends BaseApplication {
    public function bootstrap()
    {
        parent::bootstrap();
        // Load the contact manager plugin by class name
        $this->addPlugin(ContactManagerPlugin::class);
 
        // Load a plugin with a vendor namespace by 'short name'
        $this->addPlugin('AcmeCorp/ContactManager');
    }
}

If you just want to use helpers, behaviors or components from a plugin you donot need to load a plugin.

Prior to 3.6.0, you should use Plugin::load():

// In config/bootstrap.php
 
// Loads a single plugin
Plugin::load('ContactManager');
 
// Loads a plugin with a vendor namespace at top level.
Plugin::load('AcmeCorp/ContactManager');

There is also a handy shell command to enable the plugin. Execute the followingline:

bin/cake plugin load ContactManager

This would update your application’s bootstrap method, or put the$this->addPlugin('ContactManager'); snippet in the bootstrap for you.

New in version 3.6.0: addPlugin() was added.

Plugin Hook Configuration

Plugins offer several hooks that allow a plugin to inject itself into theappropriate parts of your application. The hooks are:

• bootstrap Used to load plugin default configuration files, defineconstants and other global functions.
• routes Used to load routes for a plugin. Fired after application routesare loaded.
• middleware Used to add plugin middleware to an application’s middlewarequeue.
• console Used to add console commands to an application’s commandcollection.
  When loading plugins you can configure which hooks are enabled. By defaultplugins without a Plugin Objects have all hooks disabled. New style pluginsallow plugin authors to set defaults, which can be configured by you in yourappliation:

// In Application::bootstrap()
use ContactManager\Plugin as ContactManagerPlugin;
 
// Disable routes for the ContactManager plugin
$this->addPlugin(ContactManagerPlugin::class, ['routes' => false]);

You can configure hooks with array options, or the methods provided by pluginclasses:

// In Application::bootstrap()
use ContactManager\Plugin as ContactManagerPlugin;
 
// Use the disable/enable to configure hooks.
$plugin = new ContactManagerPlugin();
 
$plugin->disable('bootstrap');
$plugin->enable('routes');
$this->addPlugin($plugin);

Plugin objects also know their names and path information:

$plugin = new ContactManagerPlugin();
 
// Get the plugin name.
$name = $plugin->getName();
 
// Path to the plugin root, and other paths.
$path = $plugin->getPath();
$path = $plugin->getConfigPath();
$path = $plugin->getClassPath();

Old Style Plugins

Prior to 3.6.0, you will need to enable the bootstrap and routes hooks.Old style plugins do not support middleware and console hooks:

// In config/bootstrap.php,
// or in Application::bootstrap()
 
// Using loadAll()
Plugin::loadAll([
    'Blog' => ['routes' => true],
    'ContactManager' => ['bootstrap' => true],
    'WebmasterTools' => ['bootstrap' => true, 'routes' => true],
]);

Or you can load the plugins individually:

// Loading just the blog and include routes
Plugin::load('Blog', ['routes' => true]);
 
// Include bootstrap configuration/initializer file.
Plugin::load('ContactManager', ['bootstrap' => true]);

With either approach you no longer need to manually include() orrequire() a plugin’s configuration or routes file – it happensautomatically at the right time and place.

You can specify a set of defaults for loadAll() which willapply to every plugin that doesn’t have a more specific configuration.

The following example will load the bootstrap file from all plugins, andadditionally the routes from the Blog plugin:

Plugin::loadAll([
    ['bootstrap' => true],
    'Blog' => ['routes' => true]
]);

Note that all files specified should actually exist in the configuredplugin(s) or PHP will give warnings for each file it cannot load. You can avoidpotential warnings by using the ignoreMissing option:

Plugin::loadAll([
    ['ignoreMissing' => true, 'bootstrap' => true],
    'Blog' => ['routes' => true]
]);

When loading plugins, the plugin name used should match the namespace. Forexample, if you have a plugin with top level namespace Users you would loadit using:

Plugin::load('User');

If you prefer to have your vendor name as top level and have a namespace likeAcmeCorp/Users, then you would load the plugin as:

Plugin::load('AcmeCorp/Users');

This will ensure that classnames are resolved properly when usingplugin syntax.

Most plugins will indicate the proper procedure for configuring them and settingup the database in their documentation.

Deprecated since version 3.7.0: Plugin::load() and Plugin::loadAll() are deprecated.

Using Plugin Classes

You can reference a plugin’s controllers, models, components, behaviors, andhelpers by prefixing the name of the plugin.

For example, say you wanted to use the ContactManager plugin’sContactInfoHelper to output formatted contact information inone of your views. In your controller, your $helpers arraycould look like this:

public $helpers = ['ContactManager.ContactInfo'];

Note

This dot separated class name is referred to as plugin syntax.

You would then be able to access the ContactInfoHelper just likeany other helper in your view, such as:

echo $this->ContactInfo->address($contact);

Plugins can use the models, components, behaviors and helpers provided by theapplication, or other plugins if necessary:

// Use an application component
$this->loadComponent('AppFlash');
 
// Use another plugin's behavior
$this->addBehavior('OtherPlugin.AuditLog');

Creating Your Own Plugins

As a working example, let’s begin to create the ContactManagerplugin referenced above. To start out, we’ll set up our plugin’sbasic directory structure. It should look like this:

/src
/plugins
    /ContactManager
        /config
        /src
            /Plugin.php
            /Controller
                /Component
            /Model
                /Table
                /Entity
                /Behavior
            /View
                /Helper
            /Template
                /Layout
        /tests
            /TestCase
            /Fixture
        /webroot

Note the name of the plugin folder, ‘ContactManager’. It is importantthat this folder has the same name as the plugin.

Inside the plugin folder, you’ll notice it looks a lot like a CakePHPapplication, and that’s basically what it is. You don’t have toinclude any of the folders you are not using. Some plugins mightonly define a Component and a Behavior, and in that case they can completelyomit the ‘Template’ directory.

A plugin can also have basically any of the other directories that yourapplication can, such as Config, Console, webroot, etc.

Creating a Plugin Using Bake

The process of creating plugins can be greatly simplified by using bake.

In order to bake a plugin, use the following command:

bin/cake bake plugin ContactManager

Bake can be used to create classes in your plugin. For example to generatea plugin controller you could run:

bin/cake bake controller --plugin ContactManager Contacts

Please refer to the chapterCode Generation with Bake if youhave any problems with using the command line. Be sure to re-generate yourautoloader once you’ve created your plugin:

php composer.phar dumpautoload

Plugin Objects

Plugin Objects allow a plugin author to define set-up logic, define defaulthooks, load routes, middleware and console commands. Plugin objects live insrc/Plugin.php. For our ContactManager plugin, our plugin class could looklike:

namespace ContactManager;
 
use Cake\Core\BasePlugin;
use Cake\Core\PluginApplicationInterface;
 
class Plugin extends BasePlugin
{
    public function middleware($middleware)
    {
        // Add middleware here.
        return $middleware;
    }
 
    public function console($commands)
    {
        // Add console commands here.
        return $commands;
    }
 
    public function bootstrap(PluginApplicationInterface $app)
    {
        // Add constants, load configuration defaults.
        // By default will load `config/bootstrap.php` in the plugin.
        parent::bootstrap($app);
    }
 
    public function routes($routes)
    {
        // Add routes.
        // By default will load `config/routes.php` in the plugin.
        parent::routes($routes);
    }
}

New in version 3.6.0: Plugin Objects were added in 3.6.0

Plugin Routes

Plugins can provide routes files containing their routes. Each plugin cancontain a config/routes.php file. This routes file can be loaded when theplugin is added, or in the application’s routes file. To create theContactManager plugin routes, put the following intoplugins/ContactManager/config/routes.php:

<?php
use Cake\Routing\Route\DashedRoute;
use Cake\Routing\Router;
 
Router::plugin(
    'ContactManager',
    ['path' => '/contact-manager'],
    function ($routes) {
        $routes->get('/contacts', ['controller' => 'Contacts']);
        $routes->get('/contacts/:id', ['controller' => 'Contacts', 'action' => 'view']);
        $routes->put('/contacts/:id', ['controller' => 'Contacts', 'action' => 'update']);
    }
);

The above will connect default routes for your plugin. You can customize thisfile with more specific routes later on.

Before you can access your controllers, you’ll need to ensure the plugin isloaded and the plugin routes are loaded. In your src/Application.php addthe following:

$this->addPlugin('ContactManager', ['routes' => true]);

You can also load plugin routes in your application’s routes list. Doing thisprovides you more control on how plugin routes are loaded and allows you to wrapplugin routes in additional scopes or prefixes:

Router::scope('/', function ($routes) {
    // Connect other routes.
    $routes->scope('/backend', function ($routes) {
        $routes->loadPlugin('ContactManager');
    });
});

The above would result in URLs like /backend/contact-manager/contacts.

New in version 3.5.0: RouteBuilder::loadPlugin() was added in 3.5.0

Plugin Controllers

Controllers for our ContactManager plugin will be stored inplugins/ContactManager/src/Controller/. Since the main thing we’llbe doing is managing contacts, we’ll need a ContactsController forthis plugin.

So, we place our new ContactsController inplugins/ContactManager/src/Controller and it looks like so:

// plugins/ContactManager/src/Controller/ContactsController.php
namespace ContactManager\Controller;
 
use ContactManager\Controller\AppController;
 
class ContactsController extends AppController
{
    public function index()
    {
        //...
    }
}

Also make the AppController if you don’t have one already:

// plugins/ContactManager/src/Controller/AppController.php
namespace ContactManager\Controller;
 
use App\Controller\AppController as BaseController;
 
class AppController extends BaseController
{
}

A plugin’s AppController can hold controller logic common to all controllersin a plugin but is not required if you don’t want to use one.

If you want to access what we’ve got going thus far, visit/contact-manager/contacts. You should get a “Missing Model” errorbecause we don’t have a Contact model defined yet.

If your application includes the default routing CakePHP provides you will beable to access your plugin controllers using URLs like:

// Access the index route of a plugin controller.
/contact-manager/contacts
 
// Any action on a plugin controller.
/contact-manager/contacts/view/1

If your application defines routing prefixes, CakePHP’s default routing willalso connect routes that use the following pattern:

/:prefix/:plugin/:controller
/:prefix/:plugin/:controller/:action

See the section on Plugin Hook Configuration for information on how to loadplugin specific route files.

For plugins you did not create with bake, you will also need to edit thecomposer.json file to add your plugin to the autoload classes, this can bedone as per the documentation Manually Autoloading Plugin Classes.

Plugin Models

Models for the plugin are stored in plugins/ContactManager/src/Model.We’ve already defined a ContactsController for this plugin, so let’screate the table and entity for that controller:

// plugins/ContactManager/src/Model/Entity/Contact.php:
namespace ContactManager\Model\Entity;
 
use Cake\ORM\Entity;
 
class Contact extends Entity
{
}
 
// plugins/ContactManager/src/Model/Table/ContactsTable.php:
namespace ContactManager\Model\Table;
 
use Cake\ORM\Table;
 
class ContactsTable extends Table
{
}

If you need to reference a model within your plugin when building associationsor defining entity classes, you need to include the plugin name with the classname, separated with a dot. For example:

// plugins/ContactManager/src/Model/Table/ContactsTable.php:
namespace ContactManager\Model\Table;
 
use Cake\ORM\Table;
 
class ContactsTable extends Table
{
    public function initialize(array $config)
    {
        $this->hasMany('ContactManager.AltName');
    }
}

If you would prefer that the array keys for the association not have the pluginprefix on them, use the alternative syntax:

// plugins/ContactManager/src/Model/Table/ContactsTable.php:
namespace ContactManager\Model\Table;
 
use Cake\ORM\Table;
 
class ContactsTable extends Table
{
    public function initialize(array $config)
    {
        $this->hasMany('AltName', [
            'className' => 'ContactManager.AltName',
        ]);
    }
}

You can use TableRegistry to load your plugin tables using the familiarplugin syntax:

use Cake\ORM\TableRegistry;
 
$contacts = TableRegistry::get('ContactManager.Contacts');

Alternatively, from a controller context, you can use:

$this->loadModel('ContactsMangager.Contacts');

Plugin Templates

Views behave exactly as they do in normal applications. Just place them in theright folder inside of the plugins/[PluginName]/src/Template/ folder. For ourContactManager plugin, we’ll need a view for our ContactsController::index()action, so let’s include that as well:

// plugins/ContactManager/src/Template/Contacts/index.ctp:
<h1>Contacts</h1>
<p>Following is a sortable list of your contacts</p>
<!-- A sortable list of contacts would go here....-->

Plugins can provide their own layouts. To add plugin layouts, place your template files insideplugins/[PluginName]/src/Template/Layout. To use a plugin layout in your controlleryou can do the following:

public $layout = 'ContactManager.admin';

If the plugin prefix is omitted, the layout/view file will be located normally.

Note

For information on how to use elements from a plugin, look upElements

Overriding Plugin Templates from Inside Your Application

You can override any plugin views from inside your app using special paths. Ifyou have a plugin called ‘ContactManager’ you can override the template files of theplugin with application specific view logic by creating files using thefollowing template src/Template/Plugin/[Plugin]/[Controller]/[view].ctp. For theContacts controller you could make the following file:

src/Template/Plugin/ContactManager/Contacts/index.ctp

Creating this file would allow you to overrideplugins/ContactManager/src/Template/Contacts/index.ctp.

If your plugin is in a composer dependency (i.e. ‘Company/ContactManager’), thepath to the ‘index’ view of the Contacts controller will be:

src/Template/Plugin/Company/ContactManager/Contacts/index.ctp

Creating this file would allow you to overridevendor/Company/ContactManager/src/Template/Contacts/index.ctp.

If the plugin implements a routing prefix, you must include the routing prefixin your application template overrides. For example, if the ‘ContactManager’plugin implemented an ‘admin’ prefix the overridng path would be:

src/Template/Plugin/Company/ContactManager/Admin/Contact/index.ctp

Plugin Assets

A plugin’s web assets (but not PHP files) can be served through the plugin’swebroot directory, just like the main application’s assets:

/plugins/ContactManager/webroot/
                               css/
                               js/
                               img/
                               flash/
                               pdf/

You may put any type of file in any directory, just like a regular webroot.

Warning

Handling static assets (such as images, JavaScript and CSS files)through the Dispatcher is very inefficient. See Improve Your Application’s Performancefor more information.

Linking to Assets in Plugins

You can use the plugin syntax when linking to plugin assets using theView\Helper\HtmlHelper’s script, image, or css methods:

// Generates a URL of /contact_manager/css/styles.css
echo $this->Html->css('ContactManager.styles');
 
// Generates a URL of /contact_manager/js/widget.js
echo $this->Html->script('ContactManager.widget');
 
// Generates a URL of /contact_manager/img/logo.jpg
echo $this->Html->image('ContactManager.logo');

Plugin assets are served using the AssetMiddleware middleware by default.This is only recommended for development. In production you shouldsymlink plugin assets to improve performance.

If you are not using the helpers, you can prepend /plugin_name/ to the beginningof the URL for an asset within that plugin to serve it. Linking to‘/contact_manager/js/some_file.js’ would serve the assetplugins/ContactManager/webroot/js/some_file.js.

Components, Helpers and Behaviors

A plugin can have Components, Helpers and Behaviors just like a CakePHPapplication. You can even create plugins that consist only of Components,Helpers or Behaviors which can be a great way to build reusable components thatcan be dropped into any project.

Building these components is exactly the same as building it within a regularapplication, with no special naming convention.

Referring to your component from inside or outside of your plugin requires onlythat you prefix the plugin name before the name of the component. For example:

// Component defined in 'ContactManager' plugin
namespace ContactManager\Controller\Component;
 
use Cake\Controller\Component;
 
class ExampleComponent extends Component
{
}
 
// Within your controllers
public function initialize()
{
    parent::initialize();
    $this->loadComponent('ContactManager.Example');
}

The same technique applies to Helpers and Behaviors.

Commands

Plugins can register their commands inside the console() hook. By defaultall shells and commands in the plugin are auto-discovered and added to theapplication’s command list. Plugin commands are prefixed with the plugin name.For example, the UserCommand provided by the ContactManager plugin wouldbe registered as both contact_manager.user and user. The un-prefixedname will only be taken by a plugin if it is not used by the application, oranother plugin.

You can customize the command names by defining each command in your plugin:

public function console($commands)
{
    // Create nested commands
    $commands->add('bake model', ModelCommand::class);
    $commands->add('bake controller', ControllerCommand::class);
 
    return $commands;
}

Testing your Plugin

If you are testing controllers or generating URLs, make sure yourplugin connects routes tests/bootstrap.php.

For more information see testing plugins page.

Publishing your Plugin

CakePHP plugins should be published to the packagist. This way other people can use it as composerdependency. You can also propose your plugin to the awesome-cakephp list.

Choose a semantically meaningful name for the package name. This should ideallybe prefixed with the dependency, in this case “cakephp” as the framework.The vendor name will usually be your GitHub username.Do not use the CakePHP namespace (cakephp) as this is reserved to CakePHPowned plugins. The convention is to use lowercase letters and dashes as separator.

So if you created a plugin “Logging” with your GitHub account “FooBar”, a goodname would be foo-bar/cakephp-logging.And the CakePHP owned “Localized” plugin can be found under _cakephp/localized_respectively.

Plugin Map File

When installing plugins via Composer, you may notice thatvendor/cakephp-plugins.php is created. This configuration file containsa map of plugin names and their paths on the filesystem. It makes it possiblefor plugins to be installed into the standard vendor directory which is outsideof the normal search paths. The Plugin class will use this file to locateplugins when they are loaded with load() or loadAll(). You generallywon’t need to edit this file by hand, as Composer and the plugin-installerpackage will manage it for you.

Manage Your Plugins using Mixer

Another way to discover and manage plugins into your CakePHP application isMixer. It is a CakePHP plugin which helpsyou to install plugins from Packagist. It also helps you to manage your existingplugins.

Note

IMPORTANT: Do not use this in production environment.