Skip to content

ProjectConfig ​

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

Project Config service.

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

View source

Public Properties ​

PropertyDescription
appliedChangesarray
areConfigSchemaVersionsCompatibleboolean
behaviorsyii\base\Behavior – List of behaviors attached to this component.
cacheDependencyyii\caching\ExpressionDependency
cacheDurationinteger, null – The project config cache duration.
doesExternalConfigExistboolean
folderNamestring – The folder name to save the project config files in, within the config/ folder.
forceUpdateboolean – Whether project config should force updates on entries that aren't new or being removed.
hadFileWriteIssuesboolean
isApplyingExternalChangesboolean
isApplyingYamlChangesboolean
maxDefersinteger – The maximum number of times deferred events can be re-deferred before we give up on them
maxDeltasinteger – The maximum number of project.yaml deltas to store in storage/config-deltas/
muteEventsboolean – Whether events generated by config changes should be muted.
pendingChangeSummaryarray
readOnlyboolean – Whether the project config is read-only.
writeYamlAutomaticallyboolean – Whether project config changes should be written to YAML files automatically.

appliedChanges ​

Type
array
Default value
null
Access
Read-only
Since
5.1.0

View source

areConfigSchemaVersionsCompatible ​

Type
boolean
Default value
null
Access
Read-only

View source

cacheDependency ​

Type
yii\caching\ExpressionDependency
Default value
null
Access
Read-only
Since
3.5.8

View source

cacheDuration ​

Type
integer, null
Default value
null
Since
4.5.0

The project config cache duration. If null, the config5:cacheDuration config setting will be used.

View source

doesExternalConfigExist ​

Type
boolean
Default value
null
Access
Read-only
Since
4.0.0

View source

folderName ​

Type
string
Default value
'project'
Since
3.5.0

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

View source

forceUpdate ​

Type
boolean
Default value
false

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

View source

hadFileWriteIssues ​

Type
boolean
Default value
null
Access
Read-only
Since
3.5.0

View source

isApplyingExternalChanges ​

Type
boolean
Default value
null

View source

isApplyingYamlChanges ​

Type
boolean
Default value
null

View source

maxDefers ​

Type
integer
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

maxDeltas ​

Type
integer
Default value
50
Since
3.4.0

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

View source

muteEvents ​

Type
boolean
Default value
false
Since
3.1.2

Whether events generated by config changes should be muted.

View source

pendingChangeSummary ​

Type
array
Default value
null
Access
Read-only

View source

readOnly ​

Type
boolean
Default value
false

Whether the project config is read-only.

View source

writeYamlAutomatically ​

Type
boolean
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 flush()

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.
applyConfigChanges()Applies given changes to the project config.
applyExternalChanges()Applies changes in external config to project config.
areChangesPending()Returns whether a given path has pending changes that need to be applied to the loaded 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.
defer()Defers an event until all other project config changes have been processed.
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.
find()Finds all config items that pass a condition, and returns their paths and configs as key/value pairs.
flush()Saves the modified project confgi state and writes out updated YAML files, if needed.
get()Returns a config item value by its path.
getAppliedChanges()Get the list of applied changes
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.
getCacheDependency()Returns the cache dependency that should be used for project config caches.
getDoesExternalConfigExist()Returns whether external project config files appear to exist.
getHadFileWriteIssues()Returns whether we have a record of issues writing out files to the project config folder.
getIsApplyingExternalChanges()Returns whether external changes are currently being applied
getPendingChangeSummary()Returns a summary of all pending config changes.
handleChangeEvent()Handles a config change event.
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 for this component.
ignorePendingChanges()Ignores any pending changes in the project config files.
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.
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.
regenerateExternalConfig()Regenerates the external config based on the loaded project config.
registerChangeEventHandler()Registers a config change event listener, for a specific config path pattern.
rememberAppliedChanges()Update Craft's internal config store for a path with the new value. If the value is null, it will be removed instead.
remove()Removes a config item at the given path.
removeNameMapping()Removes a UUID/name mapping on the working config.
saveModifiedConfigData()Saves all the config data that has been modified up to now.
set()Sets a config item value at the given path.
setNameMapping()Sets a UUID/name mapping on the working config.
trigger()Triggers an event.
updateParsedConfigTimes()Updates cached config file modified times immediately.
updateParsedConfigTimesAfterRequest()Updates cached config file modified times after the request ends.
writeYamlFiles()Update the config YAML files with the buffered changes.

__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

Arguments ​

  • $config (array) – Name-value pairs that will be used to initialize the object properties

applyConfigChanges() ​

Applies given changes to the project config.

View source

Arguments ​

applyExternalChanges() ​

Since
4.0.0

Applies changes in external config to project config.

View source

Throws ​

areChangesPending() ​

Returns whether a given path has pending changes that need to be applied to the loaded 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 external config.
  • $force (boolean) – Whether to check for changes even if it doesn’t look like anything has changed since the last time ignorePendingChanges() has been called.

Returns ​

boolean

defer() ​

Since
3.1.13

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

View source

Arguments ​

find() ​

Since
5.0.0

Finds all config items that pass a condition, and returns their paths and configs as key/value pairs.

View source

Arguments ​

  • $callback (callable)
  • $fromExternalConfig (boolean) – Whether to find config items in the external config

Returns ​

array

flush() ​

Since
5.0.0

Saves the modified project confgi state and writes out updated YAML files, if needed.

View source

get() ​

Returns a config item value by its path.

View source

Arguments ​

  • $path (string, null) – The config item path, or null if the entire config should be returned
  • $getFromExternalConfig (boolean) – Whether data should be fetched from the working config instead of the loaded config. Defaults to false.

Returns ​

mixed – The config item value


Example ​

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

getAppliedChanges() ​

Since
5.1.0

Get the list of applied changes

View source

Returns ​

array

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

Arguments ​

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

Returns ​

boolean

getCacheDependency() ​

Since
3.5.8

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

View source

Returns ​

yii\caching\ExpressionDependency

getDoesExternalConfigExist() ​

Since
4.0.0

Returns whether external project config files appear to exist.

View source

Returns ​

boolean

getHadFileWriteIssues() ​

Since
3.5.0

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

View source

Returns ​

boolean

getIsApplyingExternalChanges() ​

Since
4.0.0

Returns whether external changes are currently being applied

View source

Returns ​

boolean

getPendingChangeSummary() ​

Returns a summary of all pending config changes.

View source

Returns ​

array

handleChangeEvent() ​

Since
3.4.0

Handles a config change event.

View source

Arguments ​

ignorePendingChanges() ​

Since
3.5.0

Ignores any pending changes in the project config files.

View source

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

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


Example ​

php
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

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


Example ​

php
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

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


Example ​

php
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 external project config changes are currently getting applied.

View source

Arguments ​

  • $path (string) – The config item path
  • $force (boolean) – Whether the config change should be processed regardless of previous records, or whether external changes are currently being applied

rebuild() ​

Since
3.1.20

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

View source

Throws ​

regenerateExternalConfig() ​

Since
4.0.0

Regenerates the external config based on the loaded project config.

View source

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.

rememberAppliedChanges() ​

Since
4.0.0

Update Craft's internal config store for a path with the new value. If the value is null, it will be removed instead.

View source

Arguments ​

  • $path (string)
  • $oldValue (mixed)
  • $newValue (mixed)
  • $message (string, null) – Message describing the changes made.

remove() ​

Removes a config item at the given path.

View source

Arguments ​

  • $path (string) – The config item path
  • $message (string, null) – The message describing changes.

Example ​

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

removeNameMapping() ​

Since
4.4.17

Removes a UUID/name mapping on the working config.

View source

Arguments ​

saveModifiedConfigData() ​

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

View source

Throws ​

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
  • $message (string, null) – A message describing the changes
  • $updateTimestamp (boolean) – Whether the dateModified value should be updated, if it hasn’t been updated yet for this request
  • $force (boolean) – Whether the update should be processed regardless of whether the value actually changed

Returns ​

boolean – Whether the project config was modified

Throws ​


Example ​

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

setNameMapping() ​

Since
4.4.17

Sets a UUID/name mapping on the working config.

View source

Arguments ​

updateParsedConfigTimes() ​

Updates cached config file modified times immediately.

View source

Returns ​

boolean

updateParsedConfigTimesAfterRequest() ​

Updates cached config file modified times after the request ends.

View source

writeYamlFiles() ​

Since
5.0.0

Update the config YAML files with the buffered changes.

View source

Arguments ​

  • $force (boolean) – Whether to write out the YAML even if there aren’t any new changes

Throws ​

Protected Methods ​

MethodDescription
getCurrentWorkingConfig()Get the current working project config data.
getExternalConfig()Get the external project config data.
getInternalConfig()Get the internal project config data.
persistInternalConfigValues()Persist an array of $path => $value to the internal config.
removeInternalConfigValuesByPaths()Remove values from internal config by a list of paths.
storeYamlHistory()Store yaml history
updateConfigVersion()Updates the config version used for cache invalidation.

getCurrentWorkingConfig() ​

Get the current working project config data.

View source

Returns ​

craft\models\ProjectConfigData

getExternalConfig() ​

Get the external project config data.

View source

Returns ​

craft\models\ReadOnlyProjectConfigData

getInternalConfig() ​

Get the internal project config data.

View source

Returns ​

craft\models\ReadOnlyProjectConfigData

persistInternalConfigValues() ​

Persist an array of $path => $value to the internal config.

View source

Arguments ​

Throws ​

removeInternalConfigValuesByPaths() ​

Remove values from internal config by a list of paths.

View source

Arguments ​

storeYamlHistory() ​

Store yaml history

View source

Arguments ​

  • $configData (array) – Config data to be saved as history

Throws ​

updateConfigVersion() ​

Updates the config version used for cache invalidation.

View source

Constants ​

ConstantDescription
ASSOC_KEYThe array key to use for signaling ordered-to-associative array conversion.
CACHE_DURATIONThe duration that project config caches should be cached.
CACHE_KEYThe cache key that is used to store the modified time of the project config files, at the time they were last applied.
CONFIG_DELTA_FILENAMEFilename for base config delta files
CONFIG_FILENAME
DIFF_CACHE_KEYThe cache key that is used to store the current project config diff
FILE_ISSUES_CACHE_KEYThe cache key that is used to store whether there were any issues writing the project config files out.
IGNORE_CACHE_KEYThe cache key that is used to store the modified time of the project config files, at the time they were last applied or ignored.
MUTEX_NAME
PATH_ADDRESSES
PATH_ADDRESS_FIELD_LAYOUTS
PATH_CATEGORY_GROUPS
PATH_DATE_MODIFIED
PATH_ELEMENT_SOURCES
PATH_ENTRY_TYPES
PATH_FIELDS
PATH_FS
PATH_GLOBAL_SETS
PATH_GRAPHQL
PATH_GRAPHQL_PUBLIC_TOKEN
PATH_GRAPHQL_SCHEMAS
PATH_IMAGE_TRANSFORMS
PATH_META
PATH_META_NAMES
PATH_PLUGINS
PATH_ROUTES
PATH_SCHEMA_VERSION
PATH_SECTIONS
PATH_SITES
PATH_SITE_GROUPS
PATH_SYSTEM
PATH_TAG_GROUPS
PATH_USERS
PATH_USER_FIELD_LAYOUTS
PATH_USER_GROUPS
PATH_VOLUMES
STORED_CACHE_KEYThe cache key that is used to store the loaded project config data.
UID_PATTERNRegexp 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 ​

php
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_AFTER_WRITE_YAML_FILES ​

Type
craft\services\Event
Since
4.8.0

The event that is triggered after the YAML files have been written out.


EVENT_REBUILD ​

Type
craft\events\RebuildConfigEvent
Since
3.1.20

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


Example ​

php
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 ​

php
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 ​

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