Plugin

Type

Class

Namespace

craft\base

Inherits

craft\base\Plugin » yii\base\Module (opens new window) » yii\di\ServiceLocator (opens new window) » yii\base\Component (opens new window) » yii\base\BaseObject (opens new window)

Implements

craft\base\PluginInterface, yii\base\Configurable (opens new window)

Uses traits

craft\base\PluginTrait

Since

3.0.0

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

View source (opens new window)

Public Properties

Property	Description
aliases (opens new window)	array (opens new window) – List of path aliases to be defined.
basePath (opens new window)	string (opens new window) – The root directory of the module.
behaviors (opens new window)	yii\base\Behavior (opens new window) – List of behaviors attached to this component.
changelogUrl	string (opens new window), null (opens new window) – The plugin’s changelog URL.
components (opens new window)	array (opens new window) – The list of the component definitions or the loaded component instances (ID => definition or instance).
controllerMap (opens new window)	array (opens new window) – Mapping from controller ID to controller configurations.
controllerNamespace (opens new window)	string (opens new window), null (opens new window) – The namespace that controller classes are in.
controllerPath (opens new window)	string (opens new window) – The directory that contains the controller classes.
cpNavItem	array (opens new window), null (opens new window)
defaultRoute (opens new window)	string (opens new window) – The default route of this module.
description	string (opens new window), null (opens new window) – The plugin’s description
developer	string (opens new window), null (opens new window) – The plugin developer’s name
developerEmail	string (opens new window), null (opens new window) – The plugin developer’s support email
developerUrl	string (opens new window), null (opens new window) – The plugin developer’s website URL
documentationUrl	string (opens new window), null (opens new window) – The plugin’s documentation URL
downloadUrl	string (opens new window), null (opens new window) – The plugin’s download URL
edition	string (opens new window) – The active edition.
handle	string (opens new window) – The plugin’s handle (alias of id (opens new window))
hasCpSection	boolean (opens new window) – Whether the plugin has its own section in the control panel
hasCpSettings	boolean (opens new window) – Whether the plugin has a settings page in the control panel
id (opens new window)	string (opens new window) – An ID that uniquely identifies this module among other modules which have the same parent (opens new window).
isInstalled	boolean (opens new window) – Whether the plugin is currently installed.
layout (opens new window)	string (opens new window), boolean (opens new window), null (opens new window) – The layout that should be applied for views within this module.
layoutPath (opens new window)	string (opens new window) – The root directory of layout files.
migrator	craft\db\MigrationManager – The plugin’s migration manager
minVersionRequired	string (opens new window) – The minimum required version the plugin has to be so it can be updated.
module (opens new window)	yii\base\Module (opens new window), null (opens new window) – The parent module of this module.
modules (opens new window)	array (opens new window) – The modules (indexed by their IDs).
name	string (opens new window), null (opens new window) – The plugin’s display name
packageName	string (opens new window), null (opens new window) – The plugin’s package name
params (opens new window)	array (opens new window) – Custom module parameters (name => value).
schemaVersion	string (opens new window), null (opens new window) – The plugin’s schema version number
settings	craft\base\Model, null (opens new window) – The model that the plugin’s settings should be stored on, if the plugin has settings
settingsResponse	mixed – The result that should be returned from craft\controllers\PluginsController::actionEditPluginSettings()
sourceLanguage	string (opens new window) – The language that the plugin’s messages were written in
t9nCategory	string (opens new window), null (opens new window) – The translation category that this plugin’s translation messages should use.
uniqueId (opens new window)	string (opens new window) – The unique ID of the module.
version (opens new window)	string (opens new window) – The version of this module.
viewPath (opens new window)	string (opens new window) – The root directory of view files.

cpNavItem

Type

array (opens new window), null (opens new window)

Default value

null

Access

Read-only

View source (opens new window)

handle

Type

string (opens new window)

Default value

null

The plugin’s handle (alias of id (opens new window))

View source (opens new window)

migrator

Type

craft\db\MigrationManager

Default value

null

The plugin’s migration manager

View source (opens new window)

settings

Type

craft\base\Model, null (opens new window)

Default value

null

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

View source (opens new window)

settingsResponse

Type

mixed

Default value

null

Access

Read-only

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

View source (opens new window)

Public Methods

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

__construct()

Constructor.

View source (opens new window)

Arguments

• $id (string (opens new window)) – The ID of this module.
• $parent (yii\base\Module (opens new window)) – The parent module (if any).
• $config (array (opens new window)) – 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 (opens new window)

beforeSaveSettings()

Since

3.0.16

Performs actions before the plugin’s settings are saved.

View source (opens new window)

Returns

boolean (opens new window) – Whether the plugin’s settings should be saved.

editions()

Since

3.1.0

Returns supported plugin editions (lowest to highest).

View source (opens new window)

Returns

string (opens new window)[]

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:

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.

{% set selectedSubnavItem = 'orders' %}

View source (opens new window)

Returns

array (opens new window), null (opens new window)

getHandle()

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

View source (opens new window)

Returns

string (opens new window) – The plugin’s handle

getMigrator()

Returns the plugin’s migration manager

View source (opens new window)

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 (opens new window)

Returns

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

getSettingsResponse()

Returns the settings page response.

View source (opens new window)

Returns

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

install()

Installs the plugin.

View source (opens new window)

Returns

null (opens new window), false (opens new window) – Return false to indicate the installation failed. All other return values mean the installation was successful.

is()

Since

3.1.0

Compares the active edition with the given edition.

View source (opens new window)

Arguments

• $edition (string (opens new window)) – The edition to compare the active edition against
• $operator (string (opens new window)) – 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 (opens new window)

Throws

• yii\base\InvalidArgumentException (opens new window)
  if $edition is an unsupported edition, or if $operator is an invalid operator.

setSettings()

Sets the plugin settings

View source (opens new window)

Arguments

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

uninstall()

Uninstalls the plugin.

View source (opens new window)

Returns

null (opens new window), false (opens new window) – Return false to indicate the uninstallation failed. All other return values mean the uninstallation was successful.

Protected Methods

Method	Description
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() (opens new window)	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 (opens new window)

afterUninstall()

Performs actions after the plugin is uninstalled.

View source (opens new window)

beforeInstall()

Performs actions before the plugin is installed.

View source (opens new window)

Returns

boolean (opens new window) – Whether the plugin should be installed

beforeUninstall()

Performs actions before the plugin is uninstalled.

View source (opens new window)

Returns

boolean (opens new window) – Whether the plugin should be uninstalled

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 (opens new window)

Returns

string (opens new window), null (opens new window)

createInstallMigration()

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

View source (opens new window)

Returns

craft\db\Migration, null (opens new window) – The plugin’s installation migration

createSettingsModel()

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

View source (opens new window)

Returns

craft\base\Model, null (opens new window)

settingsHtml()

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

View source (opens new window)

Returns

string (opens new window), null (opens new window) – The rendered settings HTML

Events

EVENT_AFTER_SAVE_SETTINGS

Type

yii\base\Event (opens new window)

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 (opens new window) to false to prevent the plugin’s settings from saving.