Configuration Management

Configuration Management Overview

Concrete CMS stores configuration data for blocks, themes, packages, and the core in configuration values. These values, used for saving user preferences, are accessible through interfaces for reading and writing to the filesystem and database.

ConfigRepository

A "ConfigRepository" handles configuration values, offering standard interfaces for file and database interaction. Filesystem configs are saved as PHP arrays in application\config\generated_overrides, while database configs go into the Config table using key-value pairs.

Key Methods

Key methods include get(), save(), set(), has(), and clear(), allowing for various operations on configuration values.

Reading and Writing Config Values

Config values can be manipulated using:

• A Package object
• A service provider
• The Config facade

Package Object

Utilizing a "Repository\Liaison" class, Package objects set the default configNamespace for configuration methods. The liaison automatically adds the package handle as the configNamespace.

Database Interaction

// Save to database
use Package;
$packageObject = Package::getByHandle('my_package');
$packageObject->getConfig()->save('front_end.show_header', $show_header);

// Get from database
$showHeader = $packageObject->getConfig()->get('front_end.show_header');

Filesystem Interaction

// Save to filesystem
use Package;
$packageObject = Package::getByHandle('my_package');
$packageObject->getFileConfig()->save('email.update_schedule', 'daily');

// Get from filesystem
$updateSchedule = $packageObject->getFileConfig()->get('email.update_schedule');

Service Provider

Service providers (Core::make('config') for filesystem and Core::make('config/database') for database) are used without a package object and require an explicit namespace and group.

Config Facade

The Config facade functions similarly to Core::make('config').

Storing Multiple Values

Multiple values can be stored to a configItem using arrays. Database storage appends an index, while filesystem storage uses array keys.

Filesystem-Only Configurations

The filesystem allows more segments in a key compared to the database, enabling more nested configurations.

Retrieving Child Config Items

Child configItems of a configGroup or a specific configItem can be retrieved, returning an array of children and their values.

Associative Arrays in Database

Associative arrays for the database require serialization or JSON encoding/decoding. Filesystem storage does not need additional steps.

Manual Configuration

Setting configuration variables can also be done via configuration files instead of code.

Before proceeding, familiarize yourself with configuration values by reading Configuration and Key/Value Storage.

Consider this configuration item: concrete.security.session.invalidate_on_user_agent_mismatch. It's structured as follows:

To manually configure this, create a file named <configNamespace>.php in the directory <root>/config/application/config, resulting in concrete.php.

In concrete.php, set the value using nested arrays, reflecting the configGroup structure:

<?php
return [
    'security' => [
        'session' => [
            'invalidate_on_user_agent_mismatch' => false,
        ]
    ]
];

Environment Specific Configuration

Store environment-level information (production/development) using variables. This is useful for integrating third-party systems like Stripe with different test and live keys.

Reference the tutorial: Loading Configuration Based On Host and Environment for creating different site environments.

Configure via vhost file:

<VirtualHost *:80>
    ServerName your.local.addr
    DocumentRoot "/www/concrete5_installation"

    # Define c5 environment
    SetEnv CONCRETE5_ENV development/local
</VirtualHost>

Or modify .htaccess file:

# At the top of the .htaccess file
SetEnv CONCRETE5_ENV development/local

The hierarchical structure development/local groups manual overrides, automatically adding a period between environment name and override file, e.g., development/local.concrete.php.

Four potential config files include:

1. /application/config/development/local.concrete.php
2. /application/config/concrete.php
3. /application/config/generated_overrides/concrete.php
4. /concrete/config/concrete.php

The system preference order is:

• environment-level
• root-level
• generated overrides
• default concrete config.

For Stripe integration, store test keys in /application/config/development/local.concrete.php:

<?php
return array(
    'stripe' => [
        'public' => 'pk_test_1234567890abcdefghijklmn',
        'secret' => 'sk_test_1234567890abcdefghijklmn'
    ],
);

Store live keys in /application/config/concrete.php for production:

<?php
return array(
    'stripe' => [
        'public' => 'pk_live_0987654321qwertyuiopasdf',
        'secret' => 'sk_live_0987654321qwertyuiopasdf'
    ],
);

Development sites use /application/config/development/local.concrete.php, while live sites use /application/config/concrete.php. Avoid modifying these with Config::save as it affects the generated_overrides file and should be reserved for constants.