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.

Public Properties

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

`areConfigSchemaVersionsCompatible`

Type: boolean, array
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

`doesYamlExist`

Type: boolean
Default value: null
Access: Read-only
Since: 3.5.13

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

`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

`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 \craft\services\_updateYamlFiles()

View source

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

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

$configData (array)

`applyYamlChanges()`

Applies changes in project.yaml to the project config.

View source

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

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

$event (craft\events\ConfigEvent)
$handler (callable)

`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
$getFromYaml (boolean) – Whether data should be fetched from the project config files instead of the loaded config. Defaults to false.

Returns

mixed – The config item value

Example

php

$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

Arguments

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

Returns

boolean, array

`getCacheDependency()`

Since: 3.5.8

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

View source

Returns

yii\caching\ExpressionDependency

`getDoesYamlExist()`

Since: 3.5.13

Returns whether project config YAML 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

`getIsApplyingYamlChanges()`

Returns whether project.yaml 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

$event (craft\events\ConfigEvent)

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

View source

Arguments

$path (string) – The config item path
$triggerUpdate (boolean) – Whether an update event should be triggered even if no changes are detected
$message (string, null) – The message describing changes, if changes are detected
$force (boolean) – Whether the config change should be processed regardless of previous records, or whether YAML changes are currently being applied

`rebuild()`

Since: 3.1.20

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

View source

Throws

craft\errors\BusyResourceException
if a lock could not be acquired
craft\errors\StaleResourceException
if the loaded project config is out-of-date
Throwable
if reasons

`regenerateYamlFromConfig()`

Regenerates project.yaml 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.

`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');

`saveModifiedConfigData()`

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

View source

Arguments

$writeYaml (boolean, null) – Whether to update the YAML files. Defaults to writeYamlAutomatically.

Throws

yii\base\ErrorException

`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) – The message describing changes.
$updateTimestamp (boolean) – Whether the dateModified value should be updated, if it hasn’t been updated yet for this request
$rebuilding (boolean) – Whether the change should always be processed. This should only used when rebuilding.

Throws

yii\base\ErrorException
yii\base\Exception
yii\base\NotSupportedException
if the service is set to read-only mode
yii\base\InvalidConfigException
craft\errors\BusyResourceException
if a lock could not be acquired
craft\errors\StaleResourceException
if the loaded project config is out-of-date

Example

php

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

`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

`updateStoredConfigAfterRequest()`

Updates the stored config after the request ends.

View source

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

Arguments

$value (mixed)

Returns

string

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_NAMES_KEY`	The project config key that Craft uses to store project config names.
`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.
`MUTEX_NAME`
`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

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

utils

elements

mutations

elements

elements

mutations

elements

generators

input

criteria

elements

arrayable

components

controllers

elements

gql

models

serializable

admintable

assetindexes

axios

clearcaches

cp

craftsupport

d3

dashboard

datepickeri18n

dbbackup

deprecationerrors

editentry

editsection

edittransform

edituser

elementresizedetector

fabric

feed

fields

fieldsettings

fileupload

findreplace

focusvisible

garnish

generalsettings

graphiql

iframeresizer

installer

jquerypayment

jquerytouchevents

jqueryui

login

matrix

matrixsettings

newusers

picturefill

plugins

pluginstore

positionselect

prismjs

queuemanager

quickpost

recententries

routes

selectize

sites

systemmessages

tablesettings

timepicker

updater

updates

updateswidget

upgrade

userpermissions

utilities

velocity

vue

xregexp

nodes

nodevisitors

tokenparsers

variables

ProjectConfig

Public Properties

`areConfigSchemaVersionsCompatible`

`cacheDependency`