ProjectConfig

Type
Class
Namespace
craft\services
Inherits
craft\services\ProjectConfig » yii\base\Component (opens new window) » yii\base\BaseObject (opens new window)
Implements
yii\base\Configurable (opens new window)
Since
3.1.0

Project config service.

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

View source (opens new window)

# Public Properties

Property Description
areConfigSchemaVersionsCompatible boolean (opens new window), array (opens new window)
behaviors (opens new window) yii\base\Behavior (opens new window) – List of behaviors attached to this component
cacheDependency yii\caching\ExpressionDependency (opens new window)
doesYamlExist boolean (opens new window)
folderName string (opens new window) – The folder name to save the project config files in, within the config/ folder.
forceUpdate boolean (opens new window) – Whether project config should force updates on entries that aren't new or being removed.
hadFileWriteIssues boolean (opens new window)
isApplyingYamlChanges boolean (opens new window)
maxDefers integer (opens new window) – The maximum number of times deferred events can be re-deferred before we give up on them
maxDeltas integer (opens new window) – The maximum number of project.
muteEvents boolean (opens new window) – Whether events generated by config changes should be muted.
pendingChangeSummary array (opens new window)
readOnly boolean (opens new window) – Whether the project config is read-only.
writeYamlAutomatically boolean (opens new window) – Whether project config changes should be written to YAML files automatically.

# areConfigSchemaVersionsCompatible

Type
boolean (opens new window), array (opens new window)
Default value
null
Access
Read-only

View source (opens new window)

# cacheDependency

Type
yii\caching\ExpressionDependency (opens new window)
Default value
null
Access
Read-only
Since
3.5.8

View source (opens new window)

# doesYamlExist

Type
boolean (opens new window)
Default value
null
Access
Read-only
Since
3.5.13

View source (opens new window)

# folderName

Type
string (opens new window)
Default value
'project'
Since
3.5.0

The folder name to save the project config files in, within the config/ folder.

View source (opens new window)

# forceUpdate

Type
boolean (opens new window)
Default value
false

Whether project config should force updates on entries that aren't new or being removed.

View source (opens new window)

# hadFileWriteIssues

Type
boolean (opens new window)
Default value
null
Access
Read-only
Since
3.5.0

View source (opens new window)

# isApplyingYamlChanges

Type
boolean (opens new window)
Default value
null
Access
Read-only

View source (opens new window)

# maxDefers

Type
integer (opens new window)
Default value
500

The maximum number of times deferred events can be re-deferred before we give up on them

See also:

  • defer()
  • \craft\services\_applyChanges()

View source (opens new window)

# maxDeltas

Type
integer (opens new window)
Default value
50
Since
3.4.0

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

View source (opens new window)

# muteEvents

Type
boolean (opens new window)
Default value
false
Since
3.1.2

Whether events generated by config changes should be muted.

View source (opens new window)

# pendingChangeSummary

Type
array (opens new window)
Default value
null
Access
Read-only

View source (opens new window)

# readOnly

Type
boolean (opens new window)
Default value
false

Whether the project config is read-only.

View source (opens new window)

# writeYamlAutomatically

Type
boolean (opens new window)
Default value
true
Since
3.5.13

Whether project config changes should be written to YAML files automatically.

If set to false, you can manually write out project config YAML files using the project-config/write command.

WARNING

If this is set to false, Craft won’t have a strong grasp of whether the YAML files or database contain the most relevant project config data, so there’s a chance that the Project Config utility will be a bit misleading.

See also \craft\services\_updateYamlFiles()

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) Returns the value of an object property.
__isset() (opens new window) Checks if a property is set, i.e. defined and not null.
__set() (opens new window) Sets value of an object property.
__unset() (opens new window) 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 a given path has pending changes that need to be applied to the loaded project config.
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.
defer() Defers an event until all other project config changes have been processed.
detachBehavior() (opens new window) Detaches a behavior from the component.
detachBehaviors() (opens new window) Detaches all behaviors from the component.
ensureBehaviors() (opens new window) Makes sure that the behaviors declared in behaviors() (opens new window) are attached to this component.
get() Returns a config item value by its path.
getAreConfigSchemaVersionsCompatible() Returns whether all schema versions stored in the config are compatible with the actual codebase.
getBehavior() (opens new window) Returns the named behavior object.
getBehaviors() (opens new window) Returns all behaviors attached to this component.
getCacheDependency() Returns the cache dependency that should be used for project config caches.
getDoesYamlExist() Returns whether project config YAML files appear to exist.
getHadFileWriteIssues() Returns whether we have a record of issues writing out files to the project config folder.
getIsApplyingYamlChanges() Returns whether project.yaml changes are currently being applied
getPendingChangeSummary() Returns a summary of all pending config changes.
handleChangeEvent() Handles a config change event.
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.
hasProperty() (opens new window) Returns a value indicating whether a property is defined.
ignorePendingChanges() Ignores any pending changes in the project config files.
init() Initializes the object.
off() (opens new window) Detaches an existing event handler from this component.
on() (opens new window) 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.
processConfigChanges() Processes changes in the project config files for a given config item path.
rebuild() Rebuilds the project config from the current state in the database.
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.
saveModifiedConfigData() Saves all the config data that has been modified up to now.
set() Sets a config item value at the given path.
trigger() (opens new window) 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.

# __construct()

Constructor.

The default implementation does two things:

  • Initializes the object with the given configuration $config.
  • Call init().

If this method is overridden in a child class, it is recommended that

  • the last parameter of the constructor is a configuration array, like $config here.
  • call the parent implementation at the end of the constructor.

View source (opens new window)

Arguments

# applyConfigChanges()

Applies given changes to the project config.

View source (opens new window)

Arguments

# applyYamlChanges()

Applies changes in project.yaml to the project config.

View source (opens new window)

# areChangesPending()

Returns whether a given path has pending changes that need to be applied to the loaded project config.

View source (opens new window)

Arguments

Returns

boolean (opens new window)

# defer()

Since
3.1.13

Defers an event until all other project config changes have been processed.

View source (opens new window)

Arguments

# get()

Returns a config item value by its path.

View source (opens new window)

Arguments

Returns

mixed – The config item value

Example

$value = Craft::$app->projectConfig->get('foo.bar');

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

Arguments

  • $issues (array (opens new window)) – Passed by reference and populated with issues on error in the following format: [$pluginName, $existingSchema, $incomingSchema]

Returns

boolean (opens new window), array (opens new window)

# getCacheDependency()

Since
3.5.8

Returns the cache dependency that should be used for project config caches.

View source (opens new window)

Returns

yii\caching\ExpressionDependency (opens new window)

# getDoesYamlExist()

Since
3.5.13

Returns whether project config YAML files appear to exist.

View source (opens new window)

Returns

boolean (opens new window)

# getHadFileWriteIssues()

Since
3.5.0

Returns whether we have a record of issues writing out files to the project config folder.

View source (opens new window)

Returns

boolean (opens new window)

# getIsApplyingYamlChanges()

Returns whether project.yaml changes are currently being applied

View source (opens new window)

Returns

boolean (opens new window)

# getPendingChangeSummary()

Returns a summary of all pending config changes.

View source (opens new window)

Returns

array (opens new window)

# handleChangeEvent()

Since
3.4.0

Handles a config change event.

View source (opens new window)

Arguments

# ignorePendingChanges()

Since
3.5.0

Ignores any pending changes in the project config files.

View source (opens new window)

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

# onAdd()

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

View source (opens new window)

Arguments

Returns

static – Self reference

Example

use craft\events\ConfigEvent;
use craft\helpers\Db;

Craft::$app->projectConfig->onAdd('foo.{uid}', function(ConfigEvent $event) {
    // Get the UID from the item path
    $uid = $event->tokenMatches[0];

    // Prep the row data
    $data = array_merge($event->newValue);

    // See if the row already exists (maybe it was soft-deleted)
    $id = Db::idByUid('{{%tablename}}', $uid);

    if ($id) {
        $data['dateDeleted'] = null;
        Craft::$app->db->createCommand()->update('{{%tablename}}', $data, [
            'id' => $id,
        ]);
    } else {
        $data['uid'] = $uid;
        Craft::$app->db->createCommand()->insert('{{%tablename}}', $data);
    }
});

# onRemove()

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

View source (opens new window)

Arguments

Returns

static – Self reference

Example

use craft\events\ConfigEvent;

Craft::$app->projectConfig->onRemove('foo.{uid}', function(ConfigEvent $event) {
    // Get the UID from the item path
    $uid = $event->tokenMatches[0];

    // Soft-delete the item from the database
    Craft::$app->db->createCommand()->softDelete('{{%tablename}}', [
        'uid' => $uid,
    ]);
});

# onUpdate()

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

View source (opens new window)

Arguments

Returns

static – Self reference

Example

use craft\events\ConfigEvent;

Craft::$app->projectConfig->onUpdate('foo.{uid}', function(ConfigEvent $event) {
    // Get the UID from the item path
    $uid = $event->tokenMatches[0];

    // Update the item in the database
    $data = array_merge($event->newValue);
    Craft::$app->db->createCommand()->update('{{%tablename}}', $data, [
        'uid' => $uid,
    ]);
});

# processConfigChanges()

Processes changes in the project config files for a given config item path.

Note that this will only have an effect if project config YAML changes are currently getting applied.

View source (opens new window)

Arguments

# rebuild()

Since
3.1.20

Rebuilds the project config from the current state in the database.

View source (opens new window)

Throws

# regenerateYamlFromConfig()

Regenerates project.yaml based on the loaded project config.

View source (opens new window)

# registerChangeEventHandler()

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

View source (opens new window)

Arguments

# remove()

Removes a config item at the given path.

View source (opens new window)

Arguments

Example

Craft::$app->projectConfig->remove('foo.bar');

# saveModifiedConfigData()

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

View source (opens new window)

Arguments

Throws

# set()

Sets a config item value at the given path.

View source (opens new window)

Arguments

Throws

Example

Craft::$app->projectConfig->set('foo.bar', 'value');

# updateParsedConfigTimes()

Updates cached config file modified times immediately.

View source (opens new window)

Returns

boolean (opens new window)

# updateParsedConfigTimesAfterRequest()

Updates cached config file modified times after the request ends.

View source (opens new window)

# updateStoredConfigAfterRequest()

Updates the stored config after the request ends.

View source (opens new window)

# Protected Methods

Method Description
encodeValueAsString() Returns a project config compatible value encoded for storage.

# encodeValueAsString()

Returns a project config compatible value encoded for storage.

View source (opens new window)

Arguments

  • $value

Returns

string (opens new window)

# Constants

Constant Description
CACHE_DURATION The duration that project config caches should be cached.
CACHE_KEY The cache key that is used to store the modified time of the project config files, at the time they were last applied.
CONFIG_ALL_KEY
CONFIG_ASSOC_KEY The array key to use for signaling ordered-to-associative array conversion.
CONFIG_DELTA_FILENAME Filename for base config delta files
CONFIG_FILENAME
CONFIG_KEY
CONFIG_SCHEMA_VERSION_KEY The project config key that the Craft schema version is stored at.
CONFIG_SYSTEM The project config key that Craft system info is stored at.
DIFF_CACHE_KEY The cache key that is used to store the current project config diff
FILE_ISSUES_CACHE_KEY The cache key that is used to store whether there were any issues writing the project config files out.
IGNORE_CACHE_KEY The cache key that is used to store the modified time of the project config files, at the time they were last applied or ignored.
STORED_CACHE_KEY The cache key that is used to store the loaded project config data.
UID_PATTERN Regexp pattern to determine a string that could be used as an UID.

# Events

# EVENT_ADD_ITEM

Type
craft\events\ConfigEvent

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

Example

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
\craft\services\Event

The event that is triggered after pending project config file changes have been applied.

# EVENT_REBUILD

Type
craft\events\RebuildConfigEvent
Since
3.1.20

The event that is triggered when the project config is being rebuilt.

Example

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

Event::on(ProjectConfig::class, ProjectConfig::EVENT_REBUILD, function(RebuildConfigEvent $e) {
    // Add plugin's project config data...
   $e->config['myPlugin']['key'] = $value;
});

# EVENT_REMOVE_ITEM

Type
craft\events\ConfigEvent

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

Example

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.

Example

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...
});