Schematic allows you to synchronize your Craft setup over multiple environments. It does this by exporting information about assets, database (fields, sections, users), locales and plugins to a YAML file that can be imported in other environments.
This tool can be installed using Composer. Run the following command from the root of your project:
composer require nerds-and-company/schematic
This will add nerds-and-company/schematic
as a requirement to your project's composer.json
file and install the source-code into the vendor/nerds-and-company/schematic
directory. Composer will also create the executable vendor/bin/schematic
.
The most common usage pattern of this tool, to synchronize from a development to a production environment, would be:
- Create a Craft project locally
- Set up all of the desired plugins, sections, templates, etc.
- Run a Schematic export locally
- Optionally, if a revision control system is used, commit the schema file to the local repository
- Deploy the Craft application to a prodcution environment
- Run a Schematic import remotely
Or, to synchronize from a production to a development environment:
- Run a Schematic export remotely
- Pull the schema file locally
- Optionally, if a revision control system is used, commit the schema file to the local repository
- Run a Schematic import locally
An export can be created by running:
./vendor/bin/schematic export
To skip exporting a specific of data type, exclusions can be specified in the following form:
./vendor/bin/schematic export --exclude=assetSources
Multiple exclusions can also be specified:
./vendor/bin/schematic export --exclude=assetSources --exclude=categoryGroups
Here is a list of all of the data types and their corresponding exclude parameter values:
Data Type | Exlude Parameter |
---|---|
Asset Sources | assetSources |
Asset Transforms | assetTransforms |
Category Groups | categoryGroups |
Element Indexes | elementIndexSettings |
Fields | fields |
Global Sets | globalSets |
Locales | locales |
Plugins | plugins |
Plugin Data | pluginData |
Sections | sections |
Tag Groups | tagGroups |
Users | users |
User Groups | userGroups |
When craft is in a different directory than ./craft/app
, set the path with an environment variable.
For example:
export CRAFT_APP_PATH=./vendor/craft/app; ./bin/schematic export
This will generate a schema file at craft/config/schema.yml
. The file path can be changed using the --file
flag, for instance schematic export --file=path/to/my-schema.yml
If Craft is not installed yet, Schematic will run the installer for you. Make sure the following environment variables have been set:
- CRAFT_USERNAME
- CRAFT_EMAIL
- CRAFT_PASSWORD
- CRAFT_SITENAME
- CRAFT_SITEURL
- CRAFT_LOCALE
Optional environment variables (similar to the PHP constants):
- CRAFT_BASE_PATH
- CRAFT_APP_PATH
- CRAFT_VENDOR_PATH
- CRAFT_FRAMEWORK_PATH
- CRAFT_CONFIG_PATH
- CRAFT_PLUGINS_PATH
- CRAFT_STORAGE_PATH
- CRAFT_TEMPLATES_PATH
- CRAFT_TRANSLATIONS_PATH
- CRAFT_ENVIRONMENT
To run an import with schematic, a schema file needs to be present. An import can be created by running:
./vendor/bin/schematic import
By default schematic will look at ./craft/config/schema.yml
. To change the path where schematic will look for the schema file, use the --file
flag.
Optionally the --force
flag can be used to make the import delete any items which are not mentioned in the import file.
WARNING!! This will also delete any related content.
To skip importing a specific of data type, exclusions can be specified in the following form:
./vendor/bin/schematic import --exclude=assetSources
Multiple exclusions can also be specified:
./vendor/bin/schematic import --exclude=assetSources --exclude=categoryGroups
Here is a list of all of the data types and their corresponding exclude parameter values:
Data Type | Exlude Parameter |
---|---|
Asset Sources | assetSources |
Asset Transforms | assetTransforms |
Category Groups | categoryGroups |
Element Indexes | elementIndexSettings |
Fields | fields |
Global Sets | globalSets |
Locales | locales |
Plugins | plugins |
Plugin Data | pluginData |
Sections | sections |
Tag Groups | tagGroups |
Users | users |
User Groups | userGroups |
Keys in the schema file can be overridden by passing an override file to schematic using the --override_file
flag, for instance: vendor/bin/schematic import --override_file=craft/config/override.yml
.
Specific keys can be overriden by adding a key in craft/config/override.yml
and setting the corresponding environment variable. The key name in the override.yml
needs to be the same as the key you want to override from schema.yml
, including any parent key names. The value has to start and end with a %
(percentage sign). The correspending environment value will be SCHEMATIC_{value_without_percentage_signs}
.
If the following override.yml
is defined:
parent:
key_name: %key_value%
Then the environment variable SCHEMATIC_KEY_VALUE
needs to be set. The value of this environment variable will override the key key_name
. If the environment variable is not set Schematic will throw an error.
This tool has three hooks that extending code can plug in to. An example of a project using some of these hooks is the Schematic plugin for AmNav.
Called by | NerdsAndCompany\Schematic\Services\Schematic::importFromYaml() , NerdsAndCompany\Schematic\Services\Schematic::exportToYaml() |
Return | An array where the keys are a name and the values are a Migration Service. |
Gives plugins a chance to register their own Migration Services to Schematic in order to import or exports their own data.
public function registerMigrationService()
{
return [
'amnav' => craft()->schematic_amNav
];
}
Called by | NerdsAndCompany\Schematic\Services\Sources::getSource() |
Return | An array where the keys are mapped to a value depending on the indexFrom param of the source, id or handle. |
Gives plugins a chance to register their own Migration Services to Schematic in order to import or exports their own data.
public function registerSchematicSource($indexFrom)
{
$mapping = [
'createSomething:handle1' => 'createSomething:1'
];
return $indexFrom == 'handle' ? $mapping : array_flip($mapping);
}
Called by | NerdsAndCompany\Schematic\Models\FieldFactory::build() |
Return | An array where the keys are a the name of the fieldtype the mapping is for and the values are the fully qualified name of the custom field model class. |
Gives plugins a chance to add custom mappings to Schematic for custom field types.
public function registerSchematicFieldModels()
{
return [
'fieldType' => Plugin_CustomSchematicFieldModel
];
}
A plugin that want to make use of this functionality needs to extend NerdsAndCompany\Schematic\Models\Field
, for example
<?php
namespace Craft;
class Plugin_CustomSchematicFieldModel extends \NerdsAndCompany\Schematic\Models\Field
{
//…
}
For synchronizing Craft Commerce schema's, please see the Schematic Commerce package.
This project has been licensed under the MIT License (MIT). Please see License File for more information.
Inspired and based on the awesome ArtVandelay Plugin and built by these awesome individuals