Skip to content

Plugin ​

Type
Class
Namespace
craft\base
Inherits
craft\base\Plugin » yii\base\Module » yii\di\ServiceLocator » yii\base\Component » yii\base\BaseObject
Implements
craft\base\PluginInterface, yii\base\Configurable
Uses traits
craft\base\PluginTrait
Since
3.0.0

Plugin is the base class for classes representing plugins in terms of objects.

View source

Public Properties ​

PropertyDescription
aliasesarray – List of path aliases to be defined.
basePathstring – The root directory of the module.
behaviorsyii\base\Behavior – List of behaviors attached to this component.
changelogUrlstring, null – The plugin’s changelog URL.
componentsarray – The list of the component definitions or the loaded component instances (ID => definition or instance).
controllerMaparray – Mapping from controller ID to controller configurations.
controllerNamespacestring, null – The namespace that controller classes are in.
controllerPathstring – The directory that contains the controller classes.
cpNavItemarray, null
defaultRoutestring – The default route of this module.
descriptionstring, null – The plugin’s description
developerstring, null – The plugin developer’s name
developerEmailstring, null – The plugin developer’s support email
developerUrlstring, null – The plugin developer’s website URL
documentationUrlstring, null – The plugin’s documentation URL
downloadUrlstring, null – The plugin’s download URL
editionstring – The active edition.
handlestring – The plugin’s handle (alias of id)
hasCpSectionboolean – Whether the plugin has its own section in the control panel
hasCpSettingsboolean – Whether the plugin has a settings page in the control panel
idstring – An ID that uniquely identifies this module among other modules which have the same parent.
isInstalledboolean – Whether the plugin is currently installed.
layoutstring, boolean, null – The layout that should be applied for views within this module.
layoutPathstring – The root directory of layout files.
migratorcraft\db\MigrationManager – The plugin’s migration manager
minCmsEdition\craft\enums\CmsEdition – The minimum required Craft CMS edition.
minVersionRequiredstring – The minimum required version the plugin has to be so it can be updated.
moduleyii\base\Module, null – The parent module of this module.
modulesarray – The modules (indexed by their IDs).
namestring, null – The plugin’s display name
packageNamestring, null – The plugin’s package name
paramsarray – Custom module parameters (name => value).
schemaVersionstring – The plugin’s schema version number
settingscraft\base\Model, null – The model that the plugin’s settings should be stored on, if the plugin has settings
settingsResponsemixed – The result that should be returned from craft\controllers\PluginsController::actionEditPluginSettings()
sourceLanguagestring – The language that the plugin’s messages were written in
t9nCategorystring, null – The translation category that this plugin’s translation messages should use.
uniqueIdstring – The unique ID of the module.
versionstring – The version of this module.
viewPathstring – The root directory of view files.

cpNavItem ​

Type
array, null
Default value
null
Access
Read-only

View source

handle ​

Type
string
Default value
null

The plugin’s handle (alias of id)

View source

migrator ​

Type
craft\db\MigrationManager
Default value
null

The plugin’s migration manager

View source

settings ​

Type
craft\base\Model, null
Default value
null

The model that the plugin’s settings should be stored on, if the plugin has settings

View source

settingsResponse ​

Type
mixed
Default value
null
Access
Read-only

The result that should be returned from craft\controllers\PluginsController::actionEditPluginSettings()

View source

Public Methods ​

MethodDescription
__call()Calls the named method which is not a class method.
__clone()This method is called after the object is created by cloning an existing one.
__construct()Constructor.
__get()Getter magic method.
__isset()Checks if a property value is null.
__set()Sets the value of a component property.
__unset()Sets a component property to be null.
afterAction()This method is invoked right after an action within this module is executed.
afterSaveSettings()Performs actions after the plugin’s settings are saved.
attachBehavior()Attaches a behavior to this component.
attachBehaviors()Attaches a list of behaviors to the component.
beforeAction()This method is invoked right before an action within this module is executed.
beforeSaveSettings()Performs actions before the plugin’s settings are saved.
behaviors()Returns a list of behaviors that this component should behave as.
canGetProperty()Returns a value indicating whether a property can be read.
canSetProperty()Returns a value indicating whether a property can be set.
className()Returns the fully qualified name of this class.
clear()Removes the component from the locator.
config()Returns the base config that the plugin should be instantiated with.
createController()Creates a controller instance based on the given route.
createControllerByID()Creates a controller based on the given controller ID.
detachBehavior()Detaches a behavior from the component.
detachBehaviors()Detaches all behaviors from the component.
editions()Returns supported plugin editions (lowest to highest).
ensureBehaviors()Makes sure that the behaviors declared in behaviors() are attached to this component.
get()Returns the component instance with the specified ID.
getBasePath()Returns the root directory of the module.
getBehavior()Returns the named behavior object.
getBehaviors()Returns all behaviors attached to this component.
getComponents()Returns the list of the component definitions or the loaded component instances.
getControllerPath()Returns the directory that contains the controller classes according to controllerNamespace.
getCpNavItem()Returns the control panel nav item definition for this plugin, if it has a section in the control panel.
getHandle()Returns the plugin’s handle (really just an alias of yii\base\Module::$id).
getInstance()Returns the currently requested instance of this module class.
getLayoutPath()Returns the directory that contains layout view files for this module.
getMigrator()Returns the plugin’s migration manager
getModule()Retrieves the child module of the specified ID.
getModules()Returns the sub-modules in this module.
getSettings()Returns the model that the plugin’s settings should be stored on, if the plugin has settings.
getSettingsResponse()Returns the settings page response.
getUniqueId()Returns an ID that uniquely identifies this module among all modules within the current application.
getVersion()Returns current module version.
getViewPath()Returns the directory that contains the view files for this module.
has()Returns a value indicating whether the locator has the specified component definition or has instantiated the component.
hasEventHandlers()Returns a value indicating whether there is any handler attached to the named event.
hasMethod()Returns a value indicating whether a method is defined.
hasModule()Checks whether the child module of the specified ID exists.
hasProperty()Returns a value indicating whether a property is defined for this component.
init()Initializes the module.
install()Installs the plugin.
is()Compares the active edition with the given edition.
off()Detaches an existing event handler from this component.
on()Attaches an event handler to an event.
runAction()Runs a controller action specified by a route.
set()Registers a component definition with this locator.
setAliases()Defines path aliases.
setBasePath()Sets the root directory of the module.
setComponents()Registers a set of component definitions in this locator.
setControllerPath()Sets the directory that contains the controller classes.
setInstance()Sets the currently requested instance of this module class.
setLayoutPath()Sets the directory that contains the layout files.
setModule()Adds a sub-module to this module.
setModules()Registers sub-modules in the current module.
setSettings()Sets the plugin settings
setVersion()Sets current module version.
setViewPath()Sets the directory that contains the view files.
trigger()Triggers an event.
uninstall()Uninstalls the plugin.

__construct() ​

Constructor.

View source

Arguments ​

  • $id (string) – The ID of this module.
  • $parent (yii\base\Module, null) – The parent module (if any).
  • $config (array) – Name-value pairs that will be used to initialize the object properties.

afterSaveSettings() ​

Since
3.0.16

Performs actions after the plugin’s settings are saved.

View source

beforeSaveSettings() ​

Since
3.0.16

Performs actions before the plugin’s settings are saved.

View source

Returns ​

boolean – Whether the plugin’s settings should be saved.

config() ​

Since
4.0.0

Returns the base config that the plugin should be instantiated with.

It is recommended that plugins define their internal components from here:

php
public static function config(): array
{
    return [
        'components' => [
            'myComponent' => ['class' => MyComponent::class],
            // ...
        ],
    ];
}

Doing that enables projects to customize the components as needed, by overriding \craft\services\Plugins::$pluginConfigs in config/app.php:

php
return [
    'components' => [
        'plugins' => [
            'pluginConfigs' => [
                'my-plugin' => [
                    'components' => [
                        'myComponent' => [
                            'myProperty' => 'foo',
                            // ...
                        ],
                    ],
                ],
            ],
        ],
    ],
];

The resulting config will be passed to \Craft::createObject() to instantiate the plugin.

View source

Returns ​

array

editions() ​

Since
3.1.0

Returns supported plugin editions (lowest to highest).

View source

Returns ​

string[]

getCpNavItem() ​

Returns the control panel nav item definition for this plugin, if it has a section in the control panel.

The returned array should contain the following keys:

  • label – The human-facing nav item label
  • url – The URL the nav item should link to
  • id – The HTML id attribute the nav item should have (optional)
  • icon – The path to an SVG file that should be used as the nav item icon (optional)
  • fontIcon – A character/ligature from Craft’s font icon set (optional)
  • badgeCount – A number that should be displayed beside the nav item when unselected
  • subnav – A sub-array of subnav items

The subnav array should be associative, with identifiable keys set to sub-arrays with the following keys:

  • label – The human-facing subnav item label
  • url – The URL the subnav item should link to

For example:

php
return [
    'label' => 'Commerce',
    'url' => 'commerce',
    'subnav' => [
        'orders' => ['label' => 'Orders', 'url' => 'commerce/orders',
        'discounts' => ['label' => 'Discounts', 'url' => 'commerce/discounts',
    ],
];

Control panel templates can specify which subnav item is selected by defining a selectedSubnavItem variable.

twig
{% set selectedSubnavItem = 'orders' %}

View source

Returns ​

array, null

getHandle() ​

Returns the plugin’s handle (really just an alias of yii\base\Module::$id).

View source

Returns ​

string – The plugin’s handle

getMigrator() ​

Returns the plugin’s migration manager

View source

Returns ​

craft\db\MigrationManager – The plugin’s migration manager

getSettings() ​

Returns the model that the plugin’s settings should be stored on, if the plugin has settings.

View source

Returns ​

craft\base\Model, null – The model that the plugin’s settings should be stored on, if the plugin has settings

getSettingsResponse() ​

Returns the settings page response.

View source

Returns ​

mixed – The result that should be returned from craft\controllers\PluginsController::actionEditPluginSettings()

install() ​

Installs the plugin.

View source

is() ​

Since
3.1.0

Compares the active edition with the given edition.

View source

Arguments ​

  • $edition (string) – The edition to compare the active edition against
  • $operator (string) – The comparison operator to use. = by default, meaning the method will return true if the active edition is equal to the passed-in edition.

Returns ​

boolean

Throws ​

setSettings() ​

Sets the plugin settings

View source

Arguments ​

  • $settings (array) – The plugin settings that should be set on the settings model

uninstall() ​

Uninstalls the plugin.

View source

Protected Methods ​

MethodDescription
afterInstall()Performs actions after the plugin is installed.
afterUninstall()Performs actions after the plugin is uninstalled.
beforeInstall()Performs actions before the plugin is installed.
beforeUninstall()Performs actions before the plugin is uninstalled.
cpNavIconPath()Returns the path to the SVG icon that should be used in the plugin’s nav item in the control panel.
createInstallMigration()Instantiates and returns the plugin’s installation migration, if it has one.
createSettingsModel()Creates and returns the model used to store the plugin’s settings.
defaultVersion()Returns default module version.
settingsHtml()Returns the rendered settings HTML, which will be inserted into the content block on the settings page.

afterInstall() ​

Performs actions after the plugin is installed.

View source

afterUninstall() ​

Performs actions after the plugin is uninstalled.

View source

beforeInstall() ​

Performs actions before the plugin is installed.

View source

beforeUninstall() ​

Performs actions before the plugin is uninstalled.

View source

cpNavIconPath() ​

Returns the path to the SVG icon that should be used in the plugin’s nav item in the control panel.

See also getCpNavItem()View source

Returns ​

string, null

createInstallMigration() ​

Instantiates and returns the plugin’s installation migration, if it has one.

View source

Returns ​

craft\db\Migration, null – The plugin’s installation migration

createSettingsModel() ​

Creates and returns the model used to store the plugin’s settings.

View source

Returns ​

craft\base\Model, null

settingsHtml() ​

Returns the rendered settings HTML, which will be inserted into the content block on the settings page.

View source

Returns ​

string, null – The rendered settings HTML

Events ​

EVENT_AFTER_SAVE_SETTINGS ​

Type
yii\base\Event
Since
3.0.16

The event that is triggered after the plugin’s settings are saved.


EVENT_BEFORE_SAVE_SETTINGS ​

Type
craft\events\ModelEvent
Since
3.0.16

The event that is triggered before the plugin’s settings are saved.

You may set yii\base\ModelEvent::$isValid to false to prevent the plugin’s settings from saving.