Plugins

Type

Class

Namespace

craft\services

Inherits

craft\services\Plugins » yii\base\Component (opens new window) » yii\base\BaseObject (opens new window)

Implements

yii\base\Configurable (opens new window)

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

Public Properties

Property	Description
allPluginInfo	array (opens new window)
allPlugins	craft\base\PluginInterface[]
behaviors (opens new window)	yii\base\Behavior (opens new window) – List of behaviors attached to this component.
composerPluginInfo	array (opens new window), null (opens new window) – The plugin info, or null if an unknown handle was passed.
pluginConfigs	array (opens new window)[] – Custom plugin configurations.
pluginLicenseKey	string (opens new window) – The plugin’s handle
pluginLicenseKeyStatus	string (opens new window) – The plugin’s handle

allPluginInfo

Type

array (opens new window)

Default value

null

Access

Read-only

View source (opens new window)

allPlugins

Type

craft\base\PluginInterface[]

Default value

null

Access

Read-only

View source (opens new window)

composerPluginInfo

Type

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

Default value

null

Access

Read-only

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

View source (opens new window)

pluginConfigs

Type

array (opens new window)[]

Default value

null

Since

3.4.0

Custom plugin configurations.

View source (opens new window)

pluginLicenseKey

Type

string (opens new window)

Default value

null

Access

Write-only

The plugin’s handle

View source (opens new window)

pluginLicenseKeyStatus

Type

string (opens new window)

Default value

null

Access

Write-only

The plugin’s handle

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() (opens new window)	Constructor.
__get() (opens new window)	Returns the value of a component property.
__isset() (opens new window)	Checks if a property is set, i.e. defined and not null.
__set() (opens new window)	Sets the value of a component property.
__unset() (opens new window)	Sets a component property to be null.
arePluginsLoaded()	Returns whether plugins have been loaded yet for this request.
attachBehavior() (opens new window)	Attaches a behavior to this component.
attachBehaviors() (opens new window)	Attaches a list of behaviors to the component.
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.
createPlugin()	Creates and returns a new plugin instance based on its handle.
detachBehavior() (opens new window)	Detaches a behavior from the component.
detachBehaviors() (opens new window)	Detaches all behaviors from the component.
disablePlugin()	Disables a plugin by its handle.
enablePlugin()	Enables a plugin by its handle.
ensureBehaviors() (opens new window)	Makes sure that the behaviors declared in behaviors() (opens new window) 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() (opens new window)	Returns the named behavior object.
getBehaviors() (opens new window)	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() (opens new window)	Returns a value indicating whether there is any handler attached to the named event.
hasIssues()	Returns whether a plugin has licensing issues.
hasMethod() (opens new window)	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() (opens new window)	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).
isPluginUpdatePending()	Returns whether the given plugin’s local schema version is greater than the record we have in the database.
loadPlugins()	Loads the enabled plugins.
normalizePluginLicenseKey()	Normalizes a plugin license key.
off() (opens new window)	Detaches an existing event handler from this component.
on() (opens new window)	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() (opens new window)	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 (opens new window)

Returns

boolean (opens new window)

createPlugin()

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

View source (opens new window)

Arguments

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

Returns

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

Throws

• craft\errors\InvalidPluginException
  if $handle is invalid

disablePlugin()

Disables a plugin by its handle.

View source (opens new window)

Arguments

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

Returns

boolean (opens new window) – Whether the plugin was disabled successfully

Throws

• craft\errors\InvalidPluginException
  if the plugin isn’t installed

enablePlugin()

Enables a plugin by its handle.

View source (opens new window)

Arguments

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

Returns

boolean (opens new window) – Whether the plugin was enabled successfully

Throws

• craft\errors\InvalidPluginException
  if the plugin isn't installed

getAllPluginInfo()

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

View source (opens new window)

Returns

array (opens new window)

getAllPlugins()

Returns all the enabled plugins.

View source (opens new window)

Returns

craft\base\PluginInterface[]

getComposerPluginInfo()

Returns the Composer-supplied info

View source (opens new window)

Arguments

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

Returns

array (opens new window), null (opens new window) – 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 (opens new window)

Arguments

• $handle (string (opens new window))

Returns

string (opens new window)[]

getPlugin()

Returns an enabled plugin by its handle.

View source (opens new window)

Arguments

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

Returns

craft\base\PluginInterface, null (opens new window) – The plugin, or null if it doesn’t exist

getPluginByPackageName()

Returns an enabled plugin by its package name.

View source (opens new window)

Arguments

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

Returns

craft\base\PluginInterface, null (opens new window) – 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 (opens new window)

Arguments

• $class (string (opens new window))

Returns

string (opens new window), null (opens new window) – The plugin handle, or null if it can’t be determined

getPluginIconSvg()

Returns a plugin’s SVG icon.

View source (opens new window)

Arguments

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

Returns

string (opens new window) – The given plugin’s SVG icon

getPluginInfo()

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

View source (opens new window)

Arguments

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

Returns

array (opens new window)

Throws

• craft\errors\InvalidPluginException
  if the plugin isn't Composer-installed

getPluginLicenseKey()

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

View source (opens new window)

Arguments

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

Returns

string (opens new window), null (opens new window) – The plugin’s license key, or null if it isn’t known

Throws

• craft\errors\InvalidLicenseKeyException

getPluginLicenseKeyStatus()

Returns the license key status of a given plugin.

View source (opens new window)

Arguments

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

Returns

string (opens new window)

getStoredPluginInfo()

Returns the stored info for a given plugin.

View source (opens new window)

Arguments

• $handle (string (opens new window)) – The plugin handle

Returns

array (opens new window), null (opens new window) – The stored info, if there is any

hasIssues()

Returns whether a plugin has licensing issues.

View source (opens new window)

Arguments

• $handle (string (opens new window))

Returns

boolean (opens new window)

hasPluginVersionNumberChanged()

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

View source (opens new window)

Arguments

• $plugin (craft\base\PluginInterface) – The plugin

Returns

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

installPlugin()

Installs a plugin by its handle.

View source (opens new window)

Arguments

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

Returns

boolean (opens new window) – Whether the plugin was installed successfully.

Throws

• craft\errors\InvalidPluginException
  if the plugin doesn’t exist
• Throwable (opens new window)
  if reasons

isPluginDisabled()

Returns whether a given plugin is installed but disabled.

View source (opens new window)

Arguments

• $handle (string (opens new window)) – The plugin handle

Returns

boolean (opens new window)

isPluginEnabled()

Returns whether a given plugin is installed and enabled.

View source (opens new window)

Arguments

• $handle (string (opens new window)) – The plugin handle

Returns

boolean (opens new window)

isPluginInstalled()

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

View source (opens new window)

Arguments

• $handle (string (opens new window)) – The plugin handle

Returns

boolean (opens new window)

isPluginUpdatePending()

Since

4.0.0

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

View source (opens new window)

Arguments

• $plugin (craft\base\PluginInterface) – The plugin

Returns

boolean (opens new window) – Whether the plugin’s local schema version is greater than the record we have in the database

loadPlugins()

Loads the enabled plugins.

View source (opens new window)

normalizePluginLicenseKey()

Normalizes a plugin license key.

View source (opens new window)

Arguments

• $licenseKey (string (opens new window), null (opens new window))

Returns

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

Throws

• craft\errors\InvalidLicenseKeyException

savePluginSettings()

Saves a plugin’s settings.

View source (opens new window)

Arguments

• $plugin (craft\base\PluginInterface) – The plugin
• $settings (array (opens new window)) – The plugin’s new settings

Returns

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

Arguments

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

Returns

boolean (opens new window) – Whether the license key was updated successfully

Throws

• craft\errors\InvalidPluginException
  if the plugin isn't installed
• craft\errors\InvalidLicenseKeyException
  if $licenseKey is invalid

setPluginLicenseKeyStatus()

DEPRECATED

Deprecated in 4.4.0

Sets the license key status for a given plugin.

View source (opens new window)

Arguments

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

switchEdition()

Switches a plugin’s edition.

View source (opens new window)

Arguments

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

Throws

• craft\errors\InvalidPluginException
  if the plugin doesn’t exist
• yii\base\InvalidArgumentException (opens new window)
  if $edition is invalid
• Throwable (opens new window)
  if reasons

uninstallPlugin()

Uninstalls a plugin by its handle.

View source (opens new window)

Arguments

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

Returns

boolean (opens new window) – Whether the plugin was uninstalled successfully

Throws

• craft\errors\InvalidPluginException
  if the plugin doesn’t exist
• Throwable (opens new window)
  if reasons

updatePluginVersionInfo()

Since

3.7.13

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

View source (opens new window)

Arguments

• $plugin (craft\base\PluginInterface)

Returns

void

Throws

• craft\errors\InvalidPluginException
  if there’s no record of the plugin in the database

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

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

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