Plugins

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

The Plugins service provides APIs for managing plugins.

An instance of the Plugins service is globally accessible in Craft via Craft::$app->plugins.

Public Properties

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

`$allPluginInfo`

Type: array
Access: Read-only

View source

Signature

public array getAllPluginInfo ( )

`$allPlugins`

Type: craft\base\PluginInterface[]
Access: Read-only

View source

Signature

public craft\base\PluginInterface[] getAllPlugins ( )

`$composerPluginInfo`

Type: array, null
Access: Read-only

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

View source

Signature

public array, null getComposerPluginInfo ( \craft\services\string $handle = null )

`$pluginLicenseKey`

Type: string
Access: Write-only

The plugin’s handle

View source

Signature

public boolean setPluginLicenseKey ( \craft\services\string $handle, \craft\services\string $licenseKey = null )

`$pluginLicenseKeyStatus`

Type: string
Access: Write-only

The plugin’s handle

View source

Signature

public void setPluginLicenseKeyStatus ( \craft\services\string $handle, \craft\services\string $licenseKeyStatus = null, \craft\services\string $licensedEdition = null )

Public Methods

Method	Description
__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 an object property.
__isset()	Checks if a property is set, i.e. defined and not null.
__set()	Sets value of an object property.
__unset()	Sets an object property to 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.
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.
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.

`arePluginsLoaded()`

Returns whether plugins have been loaded yet for this request.

View source

Returns

boolean

Signature

public boolean arePluginsLoaded ( )

`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

Throws

craft\errors\InvalidPluginException
if $handle is invalid

Signature

public craft\base\PluginInterface createPlugin ( \craft\services\string $handle, array $info = null )

`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

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

Signature

public boolean disablePlugin ( \craft\services\string $handle )

`doesPluginRequireDatabaseUpdate()`

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

View source

Arguments

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

Returns

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

Signature

public boolean doesPluginRequireDatabaseUpdate ( craft\base\PluginInterface $plugin )

`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

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

Signature

public boolean enablePlugin ( \craft\services\string $handle )

`getAllPluginInfo()`

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

View source

Returns

array

Signature

public array getAllPluginInfo ( )

`getAllPlugins()`

Returns all the enabled plugins.

View source

Returns

craft\base\PluginInterface[]

Signature

public craft\base\PluginInterface[] getAllPlugins ( )

`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.

Signature

public array, null getComposerPluginInfo ( \craft\services\string $handle = null )

`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

$handle (string)

Returns

string[]

Signature

public string[] getLicenseIssues ( \craft\services\string $handle )

`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

Signature

public craft\base\PluginInterface, null getPlugin ( \craft\services\string $handle )

`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

Signature

public craft\base\PluginInterface, null getPluginByPackageName ( \craft\services\string $packageName )

`getPluginHandleByClass()`

Returns the plugin handle that contains the given class, if any. The plugin may not actually be installed.

View source

Arguments

$class (string)

Returns

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

Signature

public string, null getPluginHandleByClass ( \craft\services\string $class )

`getPluginIconSvg()`

Returns a plugin’s SVG icon.

View source

Arguments

$handle (string) – The plugin’s handle

Returns

string – The given plugin’s SVG icon

Signature

public string getPluginIconSvg ( \craft\services\string $handle )

`getPluginInfo()`

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

View source

Arguments

$handle (string) – The plugin’s handle

Returns

array

Throws

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

Signature

public array getPluginInfo ( \craft\services\string $handle )

`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

Signature

public string, null getPluginLicenseKey ( \craft\services\string $handle )

`getPluginLicenseKeyStatus()`

Returns the license key status of a given plugin.

View source

Arguments

$handle (string) – The plugin’s handle

Returns

string

Signature

public string getPluginLicenseKeyStatus ( \craft\services\string $handle )

`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

Signature

public array, null getStoredPluginInfo ( \craft\services\string $handle )

`hasIssues()`

Returns whether a plugin has licensing issues.

View source

Arguments

$handle (string)

Returns

boolean

Signature

public boolean hasIssues ( \craft\services\string $handle )

`hasPluginVersionNumberChanged()`

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

View source

Arguments

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

Returns

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

Signature

public boolean hasPluginVersionNumberChanged ( craft\base\PluginInterface $plugin )

`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

Signature

public void init ( )

`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

craft\errors\InvalidPluginException
if the plugin doesn’t exist
Throwable
if reasons

Signature

public boolean installPlugin ( \craft\services\string $handle, \craft\services\string $edition = null )

`isPluginDisabled()`

Returns whether a given plugin is installed but disabled.

View source

Arguments

$handle (string) – The plugin handle

Returns

boolean

Signature

public boolean isPluginDisabled ( \craft\services\string $handle )

`isPluginEnabled()`

Returns whether a given plugin is installed and enabled.

View source

Arguments

$handle (string) – The plugin handle

Returns

boolean

Signature

public boolean isPluginEnabled ( \craft\services\string $handle )

`isPluginInstalled()`

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

View source

Arguments

$handle (string) – The plugin handle

Returns

boolean

Signature

public boolean isPluginInstalled ( \craft\services\string $handle )

`loadPlugins()`

Loads the enabled plugins.

View source

Signature

public void loadPlugins ( )

`savePluginSettings()`

Saves a plugin's settings.

View source

Arguments

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

Returns

boolean – Whether the plugin’s settings were saved successfully

Signature

public boolean savePluginSettings ( craft\base\PluginInterface $plugin, array $settings )

`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

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

Signature

public boolean setPluginLicenseKey ( \craft\services\string $handle, \craft\services\string $licenseKey = null )

`setPluginLicenseKeyStatus()`

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

Throws

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

Signature

public void setPluginLicenseKeyStatus ( \craft\services\string $handle, \craft\services\string $licenseKeyStatus = null, \craft\services\string $licensedEdition = null )

`switchEdition()`

Switches a plugin’s edition.

View source

Arguments

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

Throws

craft\errors\InvalidPluginException
if the plugin doesn’t exist
yii\base\InvalidArgumentException
if $edition is invalid
Throwable
if reasons

Signature

public void switchEdition ( \craft\services\string $handle, \craft\services\string $edition )

`uninstallPlugin()`

Uninstalls a plugin by its handle.

View source

Arguments

$handle (string) – The plugin’s handle

Returns

boolean – Whether the plugin was uninstalled successfully

Throws

craft\errors\InvalidPluginException
if the plugin doesn’t exist
Throwable
if reasons

Signature

public boolean uninstallPlugin ( \craft\services\string $handle )

Constants

Constant	Description
`CONFIG_PLUGINS_KEY`

Events

EVENT_AFTER_DISABLE_PLUGIN

Type: craft\events\PluginEvent

The event that is triggered before a plugin is disabled

EVENT_AFTER_ENABLE_PLUGIN

Type: craft\events\PluginEvent

The event that is triggered before a plugin is enabled

EVENT_AFTER_INSTALL_PLUGIN

Type: craft\events\PluginEvent

The event that is triggered before 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 before a plugin's settings are saved

EVENT_AFTER_UNINSTALL_PLUGIN

Type: craft\events\PluginEvent

The event that is triggered before 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

Plugins

# Public Properties

#$allPluginInfo

Signature

#$allPlugins

Signature

#$composerPluginInfo

Signature

#$pluginLicenseKey

Signature

#$pluginLicenseKeyStatus

Signature

# Public Methods

#arePluginsLoaded()

Returns

Signature

#createPlugin()

Arguments

Returns

Throws

Signature

#disablePlugin()

Arguments

Returns

Throws

Signature

#doesPluginRequireDatabaseUpdate()

Arguments

Returns

Signature

#enablePlugin()

Arguments

Returns

Throws

Signature

#getAllPluginInfo()

Returns

Signature

#getAllPlugins()

Returns

Signature

#getComposerPluginInfo()

Arguments

Returns

Signature

#getLicenseIssues()

Arguments

Returns

Signature

#getPlugin()

Arguments

Returns

Signature

#getPluginByPackageName()

Arguments

Returns

Signature

#getPluginHandleByClass()

Arguments

Returns

Signature

#getPluginIconSvg()

Arguments

Returns

Signature

#getPluginInfo()

Arguments

Returns

Throws

Signature

#getPluginLicenseKey()

Arguments

Returns

Signature

#getPluginLicenseKeyStatus()

Arguments

Returns

Signature

#getStoredPluginInfo()

Arguments

Public Properties

`$allPluginInfo`

`$allPlugins`

`$composerPluginInfo`

`$pluginLicenseKey`

`$pluginLicenseKeyStatus`

Public Methods

`arePluginsLoaded()`

`createPlugin()`

`disablePlugin()`

`doesPluginRequireDatabaseUpdate()`

`enablePlugin()`

`getAllPluginInfo()`

`getAllPlugins()`

`getComposerPluginInfo()`

`getLicenseIssues()`

`getPlugin()`

`getPluginByPackageName()`

`getPluginHandleByClass()`

`getPluginIconSvg()`

`getPluginInfo()`

`getPluginLicenseKey()`

`getPluginLicenseKeyStatus()`

`getStoredPluginInfo()`

`hasIssues()`

`hasPluginVersionNumberChanged()`

`init()`

`installPlugin()`

`isPluginDisabled()`

`isPluginEnabled()`

`isPluginInstalled()`

`loadPlugins()`

`savePluginSettings()`

`setPluginLicenseKey()`

`setPluginLicenseKeyStatus()`

`switchEdition()`

`uninstallPlugin()`

Constants

Events

EVENT_AFTER_DISABLE_PLUGIN

EVENT_AFTER_ENABLE_PLUGIN

EVENT_AFTER_INSTALL_PLUGIN

EVENT_AFTER_LOAD_PLUGINS

EVENT_AFTER_SAVE_PLUGIN_SETTINGS

EVENT_AFTER_UNINSTALL_PLUGIN

EVENT_BEFORE_DISABLE_PLUGIN

EVENT_BEFORE_ENABLE_PLUGIN

EVENT_BEFORE_INSTALL_PLUGIN

EVENT_BEFORE_LOAD_PLUGINS

EVENT_BEFORE_SAVE_PLUGIN_SETTINGS

EVENT_BEFORE_UNINSTALL_PLUGIN