Skip to content

Plugins ​

Type
Class
Namespace
craft\services
Inherits
craft\services\Plugins » yii\base\Component » yii\base\BaseObject
Implements
yii\base\Configurable
Since
3.0.0

The Plugins service provides APIs for managing plugins.

An instance of the service is available via Craft::$app->plugins.

View source

Public Properties ​

PropertyDescription
allPluginInfoarray
allPluginscraft\base\PluginInterface[]
behaviorsyii\base\Behavior – List of behaviors attached to this component.
composerPluginInfoarray, null – The plugin info, or null if an unknown handle was passed.
pluginConfigsarray[] – Custom plugin configurations.
pluginLicenseKeystring – The plugin’s handle
pluginLicenseKeyStatusstring – The plugin’s handle

allPluginInfo ​

Type
array
Default value
null
Access
Read-only

View source

allPlugins ​

Type
craft\base\PluginInterface[]
Default value
null
Access
Read-only

View source

composerPluginInfo ​

Type
array, null
Default value
null
Access
Read-only

The plugin info, or null if an unknown handle was passed.

View source

pluginConfigs ​

Type
array[]
Default value
null
Since
3.4.0

Custom plugin configurations.

View source

pluginLicenseKey ​

Type
string
Default value
null
Access
Write-only

The plugin’s handle

View source

pluginLicenseKeyStatus ​

Type
string
Default value
null
Access
Write-only

The plugin’s handle

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()Returns the value of a component property.
__isset()Checks if a property is set, i.e. defined and not null.
__set()Sets the value of a component property.
__unset()Sets a component property to be null.
arePluginsLoaded()Returns whether plugins have been loaded yet for this request.
attachBehavior()Attaches a behavior to this component.
attachBehaviors()Attaches a list of behaviors to the component.
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.
createPlugin()Creates and returns a new plugin instance based on its handle.
detachBehavior()Detaches a behavior from the component.
detachBehaviors()Detaches all behaviors from the component.
disablePlugin()Disables a plugin by its handle.
doesPluginRequireDatabaseUpdate()Returns whether the given plugin’s local schema version is greater than the record we have in the database.
enablePlugin()Enables a plugin by its handle.
ensureBehaviors()Makes sure that the behaviors declared in behaviors() are attached to this component.
getAllPluginInfo()Returns info about all of the plugins we can find, whether they’re installed or not.
getAllPlugins()Returns all the enabled plugins.
getBehavior()Returns the named behavior object.
getBehaviors()Returns all behaviors attached to this component.
getComposerPluginInfo()Returns the Composer-supplied info
getLicenseIssues()Returns any issues with a plugin license.
getPlugin()Returns an enabled plugin by its handle.
getPluginByPackageName()Returns an enabled plugin by its package name.
getPluginHandleByClass()Returns the plugin handle that contains the given class, if any.
getPluginIconSvg()Returns a plugin’s SVG icon.
getPluginInfo()Returns info about a plugin, whether it's installed or not.
getPluginLicenseKey()Returns the license key stored for a given plugin, if it was purchased through the Store.
getPluginLicenseKeyStatus()Returns the license key status of a given plugin.
getStoredPluginInfo()Returns the stored info for a given plugin.
hasEventHandlers()Returns a value indicating whether there is any handler attached to the named event.
hasIssues()Returns whether a plugin has licensing issues.
hasMethod()Returns a value indicating whether a method is defined.
hasPluginVersionNumberChanged()Returns whether the given plugin’s version number has changed from what we have recorded in the database.
hasProperty()Returns a value indicating whether a property is defined for this component.
init()Initializes the object.
installPlugin()Installs a plugin by its handle.
isPluginDisabled()Returns whether a given plugin is installed but disabled.
isPluginEnabled()Returns whether a given plugin is installed and enabled.
isPluginInstalled()Returns whether a given plugin is installed (even if it's disabled).
loadPlugins()Loads the enabled plugins.
normalizePluginLicenseKey()Normalizes a plugin license key.
off()Detaches an existing event handler from this component.
on()Attaches an event handler to an event.
savePluginSettings()Saves a plugin's settings.
setPluginLicenseKey()Sets a plugin’s license key.
setPluginLicenseKeyStatus()Sets the license key status for a given plugin.
switchEdition()Switches a plugin’s edition.
trigger()Triggers an event.
uninstallPlugin()Uninstalls a plugin by its handle.
updatePluginVersionInfo()Updates a plugin’s stored version & schema version to match what’s Composer-installed.

arePluginsLoaded() ​

Returns whether plugins have been loaded yet for this request.

View source

Returns ​

boolean

createPlugin() ​

Creates and returns a new plugin instance based on its handle.

View source

Arguments ​

  • $handle (string) – The plugin’s handle
  • $info (array, null) – The plugin’s stored info, if any

Returns ​

craft\base\PluginInterface, null

Throws ​

disablePlugin() ​

Disables a plugin by its handle.

View source

Arguments ​

  • $handle (string) – The plugin’s handle

Returns ​

boolean – Whether the plugin was disabled successfully

Throws ​

doesPluginRequireDatabaseUpdate() ​

Returns whether the given plugin’s local schema version is greater than the record we have in the database.

View source

Arguments ​

Returns ​

boolean – Whether the plugin’s local schema version is greater than the record we have in the database

enablePlugin() ​

Enables a plugin by its handle.

View source

Arguments ​

  • $handle (string) – The plugin’s handle

Returns ​

boolean – Whether the plugin was enabled successfully

Throws ​

getAllPluginInfo() ​

Returns info about all of the plugins we can find, whether they’re installed or not.

View source

Returns ​

array

getAllPlugins() ​

Returns all the enabled plugins.

View source

Returns ​

craft\base\PluginInterface[]

getComposerPluginInfo() ​

Returns the Composer-supplied info

View source

Arguments ​

  • $handle (string, null) – The plugin handle. If null is passed, info for all Composer-installed plugins will be returned.

Returns ​

array, null – The plugin info, or null if an unknown handle was passed.

getLicenseIssues() ​

Returns any issues with a plugin license.

The response will be an array containing a combination of these strings:

  • wrong_edition – if the current edition isn't the licensed one, and testing editions isn't allowed
  • mismatched – if the license key is tied to a different Craft license
  • astray – if the installed version is greater than the highest version the license is allowed to run
  • required – if no license key is present but one is required
  • invalid – if a license key is present but it’s invalid

View source

Arguments ​

Returns ​

string[]

getPlugin() ​

Returns an enabled plugin by its handle.

View source

Arguments ​

  • $handle (string) – The plugin’s handle

Returns ​

craft\base\PluginInterface, null – The plugin, or null if it doesn’t exist

getPluginByPackageName() ​

Returns an enabled plugin by its package name.

View source

Arguments ​

  • $packageName (string) – The plugin’s package name

Returns ​

craft\base\PluginInterface, null – The plugin, or null if it doesn’t exist

getPluginHandleByClass() ​

Returns the plugin handle that contains the given class, if any.

The plugin may not actually be installed.

View source

Arguments ​

Returns ​

string, null – The plugin handle, or null if it can’t be determined

getPluginIconSvg() ​

Returns a plugin’s SVG icon.

View source

Arguments ​

  • $handle (string) – The plugin’s handle

Returns ​

string – The given plugin’s SVG icon

getPluginInfo() ​

Returns info about a plugin, whether it's installed or not.

View source

Arguments ​

  • $handle (string) – The plugin’s handle

Returns ​

array

Throws ​

getPluginLicenseKey() ​

Returns the license key stored for a given plugin, if it was purchased through the Store.

View source

Arguments ​

  • $handle (string) – The plugin’s handle

Returns ​

string, null – The plugin’s license key, or null if it isn’t known

Throws ​

getPluginLicenseKeyStatus() ​

Returns the license key status of a given plugin.

View source

Arguments ​

  • $handle (string) – The plugin’s handle

Returns ​

string

getStoredPluginInfo() ​

Returns the stored info for a given plugin.

View source

Arguments ​

  • $handle (string) – The plugin handle

Returns ​

array, null – The stored info, if there is any

hasIssues() ​

Returns whether a plugin has licensing issues.

View source

Arguments ​

Returns ​

boolean

hasPluginVersionNumberChanged() ​

Returns whether the given plugin’s version number has changed from what we have recorded in the database.

View source

Arguments ​

Returns ​

boolean – Whether the plugin’s version number has changed from what we have recorded in the database

init() ​

Initializes the object.

This method is invoked at the end of the constructor after the object is initialized with the given configuration.

View source

installPlugin() ​

Installs a plugin by its handle.

View source

Arguments ​

  • $handle (string) – The plugin’s handle
  • $edition (string, null) – The plugin’s edition

Returns ​

boolean – Whether the plugin was installed successfully.

Throws ​

isPluginDisabled() ​

Returns whether a given plugin is installed but disabled.

View source

Arguments ​

  • $handle (string) – The plugin handle

Returns ​

boolean

isPluginEnabled() ​

Returns whether a given plugin is installed and enabled.

View source

Arguments ​

  • $handle (string) – The plugin handle

Returns ​

boolean

isPluginInstalled() ​

Returns whether a given plugin is installed (even if it's disabled).

View source

Arguments ​

  • $handle (string) – The plugin handle

Returns ​

boolean

loadPlugins() ​

Loads the enabled plugins.

View source

normalizePluginLicenseKey() ​

Normalizes a plugin license key.

View source

Arguments ​

Returns ​

string, null

Throws ​

savePluginSettings() ​

Saves a plugin's settings.

View source

Arguments ​

Returns ​

boolean – Whether the plugin’s settings were saved successfully

setPluginLicenseKey() ​

Sets a plugin’s license key.

Note this should not be used to store license keys generated by third party stores.

View source

Arguments ​

  • $handle (string) – The plugin’s handle
  • $licenseKey (string, null) – The plugin’s license key

Returns ​

boolean – Whether the license key was updated successfully

Throws ​

setPluginLicenseKeyStatus() ​

DEPRECATED

Deprecated in 3.8.0

Sets the license key status for a given plugin.

View source

Arguments ​

  • $handle (string) – The plugin’s handle
  • $licenseKeyStatus (string, null) – The plugin’s license key status
  • $licensedEdition (string, null) – The plugin's licensed edition, if the key is valid

switchEdition() ​

Switches a plugin’s edition.

View source

Arguments ​

  • $handle (string) – The plugin’s handle
  • $edition (string) – The plugin’s edition

Throws ​

uninstallPlugin() ​

Uninstalls a plugin by its handle.

View source

Arguments ​

  • $handle (string) – The plugin’s handle
  • $force (boolean) – Whether to force the plugin uninstallation, even if it is disabled, its uninstall() method returns false, or its files aren’t present

Returns ​

boolean – Whether the plugin was uninstalled successfully

Throws ​

updatePluginVersionInfo() ​

Since
3.7.13

Updates a plugin’s stored version & schema version to match what’s Composer-installed.

View source

Arguments ​

Constants ​

ConstantDescription
CONFIG_PLUGINS_KEY

Events ​

EVENT_AFTER_DISABLE_PLUGIN ​

Type
craft\events\PluginEvent

The event that is triggered after a plugin is disabled


EVENT_AFTER_ENABLE_PLUGIN ​

Type
craft\events\PluginEvent

The event that is triggered after a plugin is enabled


EVENT_AFTER_INSTALL_PLUGIN ​

Type
craft\events\PluginEvent

The event that is triggered after a plugin is installed


EVENT_AFTER_LOAD_PLUGINS ​

Type
yii\base\Event

The event that is triggered after all plugins have been loaded


EVENT_AFTER_SAVE_PLUGIN_SETTINGS ​

Type
craft\events\PluginEvent

The event that is triggered after a plugin's settings are saved


EVENT_AFTER_UNINSTALL_PLUGIN ​

Type
craft\events\PluginEvent

The event that is triggered after a plugin is uninstalled


EVENT_BEFORE_DISABLE_PLUGIN ​

Type
craft\events\PluginEvent

The event that is triggered before a plugin is disabled


EVENT_BEFORE_ENABLE_PLUGIN ​

Type
craft\events\PluginEvent

The event that is triggered before a plugin is enabled


EVENT_BEFORE_INSTALL_PLUGIN ​

Type
craft\events\PluginEvent

The event that is triggered before a plugin is installed


EVENT_BEFORE_LOAD_PLUGINS ​

Type
yii\base\Event

The event that is triggered before any plugins have been loaded


EVENT_BEFORE_SAVE_PLUGIN_SETTINGS ​

Type
craft\events\PluginEvent

The event that is triggered before a plugin's settings are saved


EVENT_BEFORE_UNINSTALL_PLUGIN ​

Type
craft\events\PluginEvent

The event that is triggered before a plugin is uninstalled