# Get started with Configuration

todo

Showcase Platform can be highly customized to your needs. Nearly everything can be adapted / renamed / configured what of course increases complexity of the product.

To keep configuration as developer friendly as possible, SCP loads configuration from a Git (opens new window) Repository and offers a powerful PHP based Code-Configuration.

PHP and JavaScript knowledge required

SCP requires Configurations to be written in PHP Code, so it will be beneficial to know what PHP is and how it works.

There are also parts where we will dive into simple JavaScript instructions.

Getting started fast with Modules

Modules offers pretty fast configuration by enabling default configuration combinations without touching all necessary building blocks.

There is a dedicated Configuration Reference

# Git-based Configuration

SCP pulls configuration on its own from a defined configuration repository. If you not have received access to this repository, just contact us so we can provide credentials to you.

# Clients

Every configuration repository (also called CLIENT_CONFIG) contains all necessary configuration for the client (the tenant) to function.

The clients are derived from the URL – hello.showcase-app.io refers to the the client hello and uses the configured repository for the hello client to pull its configuration.

master branch

The client always uses the master branch for getting the working configuration.

To enable you to test your configuration before bringing it to the live-system we have a concept called volatile clients which basically create clients dynamically for your and destroys them once the changes are pushed to the master branch.

# The Client Name

For some services and endpoints the CLIENT_NAME is required as these services might not use a subdomain to get the tenant name from. In this case you need to specify the CLIENT_NAME on your own.

# Volatile Clients

Testing your configuration is crucial as faulty configs may break the whole system – a circumstance customers might not really appreciate.

To make developer life's easier, SCP will automatically create a new client automatically whenever you create a new pull request from a branch. These clients are volatile and will be destroyed automatically:

when the lifetime of the volatile client ends
or when the pull requests got merged

Potential Data Loss

Volatile clients are only for testing - They will be destroyed with the underlying database and all created files.

Do not use this for any kind of productive content.

# File Structure

.
├── bitbucket-pipelines.yml
├── config
│   ├── _constants.php
│   └── [...]
├── docs
│   └── whats-new.md
├── migrations
├── services
└── storage
    ├── mails
    └── material-types

This is a typical file structure for a configuration repository. You might find some additional folders or even less – but not all items will be required.

bitbucket-pipelines.yml

This file contains the continuous integration scripts which are responsible for creating volatile clients or pushing a configuration to master once it is merged.

config/\_constants.php

This file can be used to define PHP constants which can be used throughout the whole configuration. The file is not required but helpful.

`_` prefixed files

If you prefix Files with an underscore they won't be handled as configuration files.

They are reserved for special uses and must not be used for any kind of configuration.

config/*.php

Every file inside the config directory which is not prefixed by an _ is loaded and handled as configuration. The configuration name is derived from the file name – config/service_options/service_a.php will be mapped to service_options.service_a. This is a important technique as it will help to keep your configuration as lean as possible.

docs/whats-new.md

This file should contain information about the latest changes within your configuration – users may open the "whats-new" box within SCP to see your changes. So this information will be potentially publicly available.

Deprecated since v6

migrations/*.php

This is a folder where you can create migrations to change your content structure. Every time SCP pulls in new configuration it will also check for new migrations to execute. This is helpful if you e.g. want to update specific material Meta Data due to a field change or something similar.

services/*.php

PHP Classes within this directory are used to overwrite or extend given functionality in Showcase Platform. As this is an advanced feature within SCP, we recommend to read the dedicated guide for creating services in SCP.

storage/mails/*.blade.php

This directory should contain localized or generic email templates which SCP might use. Checkout our dedicated email notifications guide on this topic.

storage/material-types/

Within this directory you can store Content Apps to get them hosted by SCP directly, this is a feature which is deprecated and will be removed in future versions of SCP – you should consider to host your Content App on some dedicated space.

# Working with configuration

SCPs configuration is based on associative PHP array which define a dot-notated configuration key. Think about the following sample PHP array:

<?php

return [
    'my_configuration' => [
        'with_values' => [
            'active' => true,
        ]
    ]
];

We refer to specific configuration elements by using their configuration keys which is nothing more than the array path of a particular configuration written in dot-notation.

my_configuration.with_values.active will refer to the value true as it just tells us which path we need to inspect.

Every file inside the config folder of your CLIENT_CONFIG repository is the starting point of a configuration – having this in mind, the configuration key material_types refers to the file material_types.php inside the config directory of your CLIENT_CONFIG.

Structuring Configuration

Inside the config folder every directory acts as a part of your configuration key – the file named foo.php inside of a folder called renditions will export the configuration for renditions.foo.

# Configuration Overloading

As also core functionalities are driven by the powerful configuration SCP offers, we have a set of configuration files which are loaded by the system by default. As we are using the associative structure of array, you are highly welcome to override each section of the configuration by creating your own configuration files.

Check out the full default configuration for further information.

# Defining Constants

Constants are helpful when you have to refer to specific values multiple times. Here is an example of good usage of the _constants.php file:

<?php

// CLIENT_CONFIG/config/_constants.php

if (!defined('GERMAN_COUNTRIES')) {
    define('GERMAN_COUNTRIES', [
        'germany',
        'switzerland',
        'austria'
    ]);
}

if (!defined('ALLOWED_COUNTRIES')) {
    define('ALLOWED_COUNTRIES', array_merge(
        [
            'united-kingdom',
            'italy',
            // ...
        ],
        GERMAN_COUNTRIES
    ));
}

The if (!defined(...)) check is important as unit-testing loads the _constants.php file multiple times which would cause a PHP error as constants cannot be defined multiple times.

Use constants

Don't refer to constants by using the helper function constant(name) – just use the name directly as it works pretty well and cannot be overseen by your team.

← Graphical User Interface Authorization →