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 service is available via Craft::$app->projectConfig
.
View source (opens new window)
# Public Properties
# areConfigSchemaVersionsCompatible
- Type
- boolean (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)
# cacheDuration
- Type
- integer (opens new window), null (opens new window)
- Default value
null
- Since
- 4.5.0
The project config cache duration. If null, the config4:cacheDuration (opens new window) config setting will be used.
View source (opens new window)
# doesExternalConfigExist
- Type
- boolean (opens new window)
- Default value
null
- Access
- Read-only
- Since
- 4.0.0
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)
# isApplyingExternalChanges
- Type
- boolean (opens new window)
- Default value
null
View source (opens new window)
# isApplyingYamlChanges
- Type
- boolean (opens new window)
- Default value
null
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-deltas/
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 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 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. |
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() (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. |
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() (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 for this component. |
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. |
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() (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
$config
(array (opens new window)) – Name-value pairs that will be used to initialize the object properties
# applyConfigChanges()
Applies given changes to the project config.
View source (opens new window)
Arguments
$configData
(array (opens new window))
# applyExternalChanges()
- Since
- 4.0.0
Applies changes in external config to project config.
View source (opens new window)
Throws
- craft\errors\BusyResourceException
if a lock could not be acquired - craft\errors\StaleResourceException
if the loaded project config is out-of-date
# 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
$path
(string (opens new window), null (opens new window)) – A specific config path that should be checked for pending changes. If this is null, thentrue
will be returned if there are any pending changes in external config.$force
(boolean (opens new window)) – Whether to check for changes even if it doesn’t look like anything has changed since the last time ignorePendingChanges() has been called.
Returns
# defer()
- Since
- 3.1.13
Defers an event until all other project config changes have been processed.
View source (opens new window)
Arguments
$event
(craft\events\ConfigEvent)$handler
(callable (opens new window))
# get()
Returns a config item value by its path.
View source (opens new window)
Arguments
$path
(string (opens new window), null (opens new window)) – The config item path, ornull
if the entire config should be returned$getFromExternalConfig
(boolean (opens new window)) – Whether data should be fetched from the working config instead of the loaded config. Defaults tofalse
.
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
# 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)
# getDoesExternalConfigExist()
- Since
- 4.0.0
Returns whether external project config files appear to exist.
View source (opens new window)
Returns
# 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
# getIsApplyingExternalChanges()
- Since
- 4.0.0
Returns whether external changes are currently being applied
View source (opens new window)
Returns
# getPendingChangeSummary()
Returns a summary of all pending config changes.
View source (opens new window)
Returns
# handleChangeEvent()
- Since
- 3.4.0
Handles a config change event.
View source (opens new window)
Arguments
$event
(craft\events\ConfigEvent)
# 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
$path
(string (opens new window)) – The config path pattern. Can contain{uri}
tokens, which will be passed to the handler.$handler
(callable (opens new window)) – 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 (opens new window).
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
$path
(string (opens new window)) – The config path pattern. Can contain{uri}
tokens, which will be passed to the handler.$handler
(callable (opens new window)) – 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 (opens new window).
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
$path
(string (opens new window)) – The config path pattern. Can contain{uri}
tokens, which will be passed to the handler.$handler
(callable (opens new window)) – 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 (opens new window).
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 external project config changes are currently getting applied.
View source (opens new window)
Arguments
$path
(string (opens new window)) – The config item path$force
(boolean (opens new window)) – 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 (opens new window)
Throws
- craft\errors\BusyResourceException
if a lock could not be acquired - craft\errors\StaleResourceException
if the loaded project config is out-of-date - Throwable (opens new window)
if reasons
# regenerateExternalConfig()
- Since
- 4.0.0
Regenerates the external config 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
$event
(string (opens new window)) – The event name$path
(string (opens new window)) – The config path pattern. Can contain{uid}
tokens, which will be passed to the handler.$handler
(callable (opens new window)) – 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 (opens new window).
# 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 (opens new window)
Arguments
$path
(string (opens new window))$oldValue
(mixed
)$newValue
(mixed
)$message
(string (opens new window), null (opens new window)) – Message describing the changes made.
# remove()
Removes a config item at the given path.
View source (opens new window)
Arguments
$path
(string (opens new window)) – The config item path$message
(string (opens new window), null (opens new window)) – The message describing changes.
Example
Craft::$app->projectConfig->remove('foo.bar');
# removeNameMapping()
- Since
- 4.4.17
Removes a UUID/name mapping on the working config.
View source (opens new window)
Arguments
$uid
(string (opens new window))
# saveModifiedConfigData()
Saves all the config data that has been modified up to now.
View source (opens new window)
Arguments
$writeExternalConfig
(boolean (opens new window), null (opens new window)) – Whether to update the external config. Defaults to writeYamlAutomatically.
Throws
# set()
Sets a config item value at the given path.
View source (opens new window)
Arguments
$path
(string (opens new window)) – The config item path$value
(mixed
) – The config item value$message
(string (opens new window), null (opens new window)) – A message describing the changes$updateTimestamp
(boolean (opens new window)) – Whether thedateModified
value should be updated, if it hasn’t been updated yet for this request$force
(boolean (opens new window)) – Whether the update should be processed regardless of whether the value actually changed
Returns
boolean (opens new window) – Whether the project config was modified
Throws
- yii\base\ErrorException (opens new window)
- yii\base\Exception (opens new window)
- yii\base\NotSupportedException (opens new window)
if the service is set to read-only mode - yii\web\ServerErrorHttpException (opens new window)
- yii\base\InvalidConfigException (opens new window)
- craft\errors\BusyResourceException
if a lock could not be acquired - craft\errors\StaleResourceException
if the loaded project config is out-of-date
Example
Craft::$app->projectConfig->set('foo.bar', 'value');
# setNameMapping()
- Since
- 4.4.17
Sets a UUID/name mapping on the working config.
View source (opens new window)
Arguments
$uid
(string (opens new window))$name
(string (opens new window))
# updateParsedConfigTimes()
Updates cached config file modified times immediately.
View source (opens new window)
Returns
# 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 |
---|---|
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. |
updateYamlFiles() | Update the config Yaml files with the buffered changes. |
# getCurrentWorkingConfig()
Get the current working project config data.
View source (opens new window)
Returns
craft\models\ProjectConfigData
# getExternalConfig()
Get the external project config data.
View source (opens new window)
Returns
craft\models\ReadOnlyProjectConfigData
# getInternalConfig()
Get the internal project config data.
View source (opens new window)
Returns
craft\models\ReadOnlyProjectConfigData
# persistInternalConfigValues()
Persist an array of $path => $value
to the internal config.
View source (opens new window)
Arguments
$values
(array (opens new window))
Throws
# removeInternalConfigValuesByPaths()
Remove values from internal config by a list of paths.
View source (opens new window)
Arguments
$paths
(array (opens new window))
Throws
# storeYamlHistory()
Store yaml history
View source (opens new window)
Arguments
$configData
(array (opens new window)) – Config data to be saved as history
Throws
# updateConfigVersion()
Updates the config version used for cache invalidation.
View source (opens new window)
# updateYamlFiles()
Update the config Yaml files with the buffered changes.
View source (opens new window)
Throws
- yii\base\Exception (opens new window)
if something goes wrong
# Constants
Constant | Description |
---|---|
ASSOC_KEY | The array key to use for signaling ordered-to-associative array conversion. |
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_DELTA_FILENAME | Filename for base config delta files |
CONFIG_FILENAME | |
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. |
MUTEX_NAME | |
PATH_ADDRESSES | |
PATH_ADDRESS_FIELD_LAYOUTS | |
PATH_CATEGORY_GROUPS | |
PATH_DATE_MODIFIED | |
PATH_ELEMENT_SOURCES | |
PATH_ENTRY_TYPES | |
PATH_FIELDS | |
PATH_FIELD_GROUPS | |
PATH_FS | |
PATH_GLOBAL_SETS | |
PATH_GRAPHQL | |
PATH_GRAPHQL_PUBLIC_TOKEN | |
PATH_GRAPHQL_SCHEMAS | |
PATH_IMAGE_TRANSFORMS | |
PATH_MATRIX_BLOCK_TYPES | |
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_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
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
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
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...
});