ProjectConfig

Type
Class
Namespace
craft\services
Inherits
craft\services\ProjectConfig » yii\base\Component » yii\base\BaseObject
Implements
yii\base\Configurable
Since
3.1

Project config service.

An instance of the ProjectConfig service is globally accessible in Craft via craft\base\ApplicationTrait::ProjectConfig().

View source

Public Properties

PropertyDescription
$areConfigSchemaVersionsCompatibleboolean
$behaviorsyii\base\Behavior – List of behaviors attached to this component
$isApplyingYamlChangesboolean
$maxBackupsinteger – The maximum number of project.
$muteEventsboolean – Whether events generated by config changes should be muted.
$pendingChangeSummaryarray
$readOnlyboolean – Whether the project config is read-only.

$areConfigSchemaVersionsCompatible

Type
boolean
Access
Read-only

View source

Signature

public boolean getAreConfigSchemaVersionsCompatible ( )

$isApplyingYamlChanges

Type
boolean
Access
Read-only

View source

Signature

public boolean getIsApplyingYamlChanges ( )

$maxBackups

Type
integer

The maximum number of project.yaml backups to store in storage/config-backups/

View source

Signature

public integer $maxBackups = 50

$muteEvents

Type
boolean

Whether events generated by config changes should be muted.

View source

Signature

public boolean $muteEvents = false

$pendingChangeSummary

Type
array
Access
Read-only

View source

Signature

public array getPendingChangeSummary ( )

$readOnly

Type
boolean

Whether the project config is read-only.

View source

Signature

public boolean $readOnly = false

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 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.
applyConfigChanges()Applies given changes to the project config.
applyYamlChanges()Applies changes in project.yaml to the project config.
areChangesPending()Returns whether project.yaml has any pending changes that need to be applied to the project config.
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.
detachBehavior()Detaches a behavior from the component.
detachBehaviors()Detaches all behaviors from the component.
ensureBehaviors()Makes sure that the behaviors declared in behaviors() are attached to this component.
get()Returns a config item value value by its path.
getAreConfigSchemaVersionsCompatible()Returns whether all schema versions stored in the config are compatible with the actual codebase.
getBehavior()Returns the named behavior object.
getBehaviors()Returns all behaviors attached to this component.
getIsApplyingYamlChanges()Returns whether project.yaml changes are currently being applied
getPendingChangeSummary()Returns a summary of all pending config changes.
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.
hasProperty()Returns a value indicating whether a property is defined.
init()Initializes the object.
off()Detaches an existing event handler from this component.
on()Attaches an event handler to an event.
onAdd()Attaches an event handler for when an item is added to the config at a given path.
onRemove()Attaches an event handler for when an item is removed from the config at a given path.
onUpdate()Attaches an event handler for when an item is updated in the config at a given path.
preventSavingDataAfterRequest()Disable the event handler that would save modified data after request is over.
processConfigChanges()Processes changes in config/project.yaml for a given path.
regenerateYamlFromConfig()Regenerates project.yaml based on the loaded project config.
registerChangeEventHandler()Registers a config change event listener, for a specific config path pattern.
remove()Removes a config item at the given path.
reset()Resets the internal state.
saveDataAfterRequest()Set up an event handler to save modified data after request is over. This is called automatically when service is initialized.
saveModifiedConfigData()Saves all the config data that has been modified up to now.
set()Sets a config item value at the given path.
trigger()Triggers an event.
updateParsedConfigTimes()Updates cached config file modified times immediately.
updateParsedConfigTimesAfterRequest()Updates cached config file modified times after the request ends.
updateStoredConfigAfterRequest()Updates the stored config after the request ends.

applyConfigChanges()

Applies given changes to the project config.

View source

Arguments

Signature

public void applyConfigChanges ( array $configData )

applyYamlChanges()

Applies changes in project.yaml to the project config.

View source

Signature

public void applyYamlChanges ( )

areChangesPending()

Returns whether project.yaml has any pending changes that need to be applied to the project config.

View source

Arguments

  • $path (string, null) – A specific config path that should be checked for pending changes. If this is null, then true will be returned if there are any pending changes in project.yaml..

Returns

boolean

Signature

public boolean areChangesPending ( \craft\services\string $path = null )

get()

Returns a config item value value by its path.

View source

Arguments

  • $path (string) – The config item path
  • $getFromYaml (boolean) – Whether data should be fetched from config/project.yaml instead of the loaded config. Defaults to false.

Returns

mixed – The config item value

Signature

public mixed get ( \craft\services\string $path = null, $getFromYaml = false )

Example

getAreConfigSchemaVersionsCompatible()

Returns whether all schema versions stored in the config are compatible with the actual codebase. The schemas must match exactly to avoid unpredictable behavior that can occur when running migrations and applying project config changes at the same time.

View source

Returns

boolean

Signature

public boolean getAreConfigSchemaVersionsCompatible ( )

getIsApplyingYamlChanges()

Returns whether project.yaml changes are currently being applied

View source

Returns

boolean

Signature

public boolean getIsApplyingYamlChanges ( )

getPendingChangeSummary()

Returns a summary of all pending config changes.

View source

Returns

array

Signature

public array getPendingChangeSummary ( )

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 ( )

onAdd()

Attaches an event handler for when an item is added to the config at a given path.

View source

Arguments

  • $path (string) – The config path pattern. Can contain {uri} tokens, which will be passed to the handler.
  • $handler (callable) – The handler method.
  • $data (mixed) – The data to be passed to the event handler when the event is triggered. When the event handler is invoked, this data can be accessed via craft\events\ConfigEvent::$data.

Returns

static – Self reference

Signature

public static onAdd ( \craft\services\string $path, $handler, $data = null )

Example

onRemove()

Attaches an event handler for when an item is removed from the config at a given path.

View source

Arguments

  • $path (string) – The config path pattern. Can contain {uri} tokens, which will be passed to the handler.
  • $handler (callable) – The handler method.
  • $data (mixed) – The data to be passed to the event handler when the event is triggered. When the event handler is invoked, this data can be accessed via craft\events\ConfigEvent::$data.

Returns

static – Self reference

Signature

public static onRemove ( \craft\services\string $path, $handler, $data = null )

Example

onUpdate()

Attaches an event handler for when an item is updated in the config at a given path.

View source

Arguments

  • $path (string) – The config path pattern. Can contain {uri} tokens, which will be passed to the handler.
  • $handler (callable) – The handler method.
  • $data (mixed) – The data to be passed to the event handler when the event is triggered. When the event handler is invoked, this data can be accessed via craft\events\ConfigEvent::$data.

Returns

static – Self reference

Signature

public static onUpdate ( \craft\services\string $path, $handler, $data = null )

Example

preventSavingDataAfterRequest()

Disable the event handler that would save modified data after request is over.

View source

Returns

void

Signature

public void preventSavingDataAfterRequest ( )

processConfigChanges()

Processes changes in config/project.yaml for a given path.

View source

Arguments

  • $path (string) – The config item path
  • $triggerUpdate (boolean) – Is set to true and no changes are detected, an update event will be triggered, anyway.

Signature

public void processConfigChanges ( \craft\services\string $path, \craft\services\bool $triggerUpdate = false )

regenerateYamlFromConfig()

Regenerates project.yaml based on the loaded project config.

View source

Signature

public void regenerateYamlFromConfig ( )

registerChangeEventHandler()

Registers a config change event listener, for a specific config path pattern.

View source

Arguments

  • $event (string) – The event name
  • $path (string) – The config path pattern. Can contain {uid} tokens, which will be passed to the handler.
  • $handler (callable) – The handler method.
  • $data (mixed) – The data to be passed to the event handler when the event is triggered. When the event handler is invoked, this data can be accessed via craft\events\ConfigEvent::$data.

Signature

public void registerChangeEventHandler ( \craft\services\string $event, \craft\services\string $path, $handler, $data = null )

remove()

Removes a config item at the given path.

View source

Arguments

  • $path (string) – The config item path

Signature

public void remove ( \craft\services\string $path )

Example

reset()

Resets the internal state.

View source

Signature

public void reset ( )

saveDataAfterRequest()

Set up an event handler to save modified data after request is over. This is called automatically when service is initialized.

View source

Returns

void

Signature

public void saveDataAfterRequest ( )

saveModifiedConfigData()

Saves all the config data that has been modified up to now.

View source

Throws

Signature

public void saveModifiedConfigData ( )

set()

Sets a config item value at the given path.

View source

Arguments

  • $path (string) – The config item path
  • $value (mixed) – The config item value

Throws

Signature

public void set ( \craft\services\string $path, $value )

Example

updateParsedConfigTimes()

Updates cached config file modified times immediately.

View source

Returns

boolean

Signature

public boolean updateParsedConfigTimes ( )

updateParsedConfigTimesAfterRequest()

Updates cached config file modified times after the request ends.

View source

Signature

public void updateParsedConfigTimesAfterRequest ( )

updateStoredConfigAfterRequest()

Updates the stored config after the request ends.

View source

Signature

public void updateStoredConfigAfterRequest ( )

Constants

ConstantDescription
CACHE_DURATION
CACHE_KEY
CONFIG_FILENAME
CONFIG_KEY
CONFIG_SCHEMA_VERSION_KEY
UID_PATTERN

Events

EVENT_ADD_ITEM

Type
craft\events\ConfigEvent

The event that is triggered when an item is added to the config.

use craft\events\ParseConfigEvent;
use craft\services\ProjectConfig;
use yii\base\Event;

Event::on(ProjectConfig::class, ProjectConfig::EVENT_ADD_ITEM, function(ParseConfigEvent $e) {
    // Ensure the item is also added in the database...
});

EVENT_AFTER_APPLY_CHANGES

Type
yii\base\Event

The event that is triggered after pending changes in config/project.yaml have been applied.

EVENT_REMOVE_ITEM

Type
craft\events\ConfigEvent

The event that is triggered when an item is removed from the config.

use craft\events\ParseConfigEvent;
use craft\services\ProjectConfig;
use yii\base\Event;

Event::on(ProjectConfig::class, ProjectConfig::EVENT_REMOVE_ITEM, function(ParseConfigEvent $e) {
    // Ensure the item is also removed in the database...
});

EVENT_UPDATE_ITEM

Type
craft\events\ConfigEvent

The event that is triggered when an item is updated in the config.

use craft\events\ParseConfigEvent;
use craft\services\ProjectConfig;
use yii\base\Event;

Event::on(ProjectConfig::class, ProjectConfig::EVENT_UPDATE_ITEM, function(ParseConfigEvent $e) {
    // Ensure the item is also updated in the database...
});