This project aims to import/export resources and elements from one MODX instance to another. Working with workflows from local > dev > staging > production(master). Also attempting to be similar to what Migrate is for Laravel.
This is a CLI tool. Most code references are for SSH/command line/terminal. To create custom Migrations you should be knowledgeable of PHP and MODX. A good IDE like PHPStorm will help you auto complete available methods for custom migrations.
- IDE driven, build out a blank migration file and then be able to use an IDE like PHPStorm to help you out. And provide convenience methods to speed up the process and make it consistent.
- To make VCS(git) workflows easily between local, remote, dev, staging and production
- Abstracting IDs from xPDO relationships for storage. Allow passing of MODX resources(site content) and TVs independent of IDs but becoming dependant on alias, the alias must then be unique across environments.
- Build a MODX dev box/branch that will load in all essential data and create as many users and user groups as needed for testing.
- Allowing smooth rollbacks, if dev to prod failed, roll it back to the latest know working version
Example 1: You have a local or dev Modx environment set up and you make some new resources, snippets, chunks, ect. But there is a constant creation of resources on the production site from the content creation team. You cannot ask the content production team to stop for days or weeks while you code up the next new feature. Now with Blend it is easy to add in your new feature independent of the resource IDs.
Example 2: You are going to do a complete new version of you site and you want to keep a few things from the old site. So you export what is needed and then torch the rest. Now you can modify the exported seeds and import into a new MODX install.
-
What are Migrations?
Think of migrations as creating instructions for data to be imported or modified. Migrations can be used like version control for the MODX database, allowing your team to easily modify and share the changes to elements (chunks, plugins, snippets, templates and template variables), resource(pages) and system settings as well as your custom tables. If you manually migrate a MODX element from dev to production, then migrations will help you track and ensure consistent results. -
What are Seeds?
Currently seeds are generated files that contain the selected elements (chunks, plugins, snippets, templates and template variables), resource(pages) and/or system settings as data exports of your system that can be used in another. For example moving from development server to production.
Via composer, just run: composer require lci/blend
OR
Via git
- CD into the directory that you want the project to live in. Can be anywhere PHP runs, one place could be outside of your public or www directory. Or if you prefer the traditional MODX extras path then in MODX/core/components/blend/
git clone [email protected]:LippertComponents/Blend.git .
Go the bin directory, you may need to copy the sample.config.php file to just config.php and then set the correct path to MODX.
CD to the bin directory and try
If you used git: php BlenderCli.php
or php BlenderCli.php --help
If you used composer php blend
or php blend --help
You should see a help menu, then do php blend --install
to install.
Migration help & usage info php blend --help --migrate
or using the short command
php blend -m -h
and for seeds php blend --help --seed
or with the short command php blend -s -h
See the tests/database/migrations directory for basic examples.
Create a Migration and seeds for all elements, resources and system settings:
php blend --seed --object site --name InitSite
Same as above, but in short command
php blend -s -o a -n InitSite
- Generate an empty migration file:
php blend --migrate --generate --name MyChunks
Same as above but in short formatphp blend -m -g -n MyChunks
- There will now be a file:
MODX~core/components/blend/database/migrations/MyChunks.php
open in your IDE - You will want to something like the below example for the up method. The up method creates or updates:
<?php
// Manual set up of a chunk:
/** @var \LCI\Blend\Chunk $myChunk */
$myChunk = $this->blender->blendOneRawChunk('myChunk');
$myChunk
->setSeedsDir($this->getTimestamp())// This is needed to set the down() data
->setDescription('This is my test chunk, note this is limited to 255 or something')
->setCategoryFromNames('My Site=>Chunks')
->setCode('[[+testPlaceholder]]')// could do file_get_contents()
//need the relative to the MODX root path here, or whatever lines up with media source ID: 1
->setAsStatic('core/components/mysite/elements/chunks/myChunk.tpl');
// The blend() method will create a back/down data before saving to allow for easy revert with the revertBlend method
if ($myChunk->blend(true)) {
$this->blender->out($myChunk->getName().' was saved correctly');
} else {
//error
$this->blender->out($myChunk->getName().' did not save correctly ', true);
$this->blender->out(print_r($myChunk->getErrorMessages(), true), true);
}
- To allow for a rollback you will need to code the exact opposite in the down method. The down method is for remove or downgrade.
<?php
// Allow Blend to retrieve the data exactly how it was before the up() method did a blend()
$name = 'myChunk';
$blendChunk = new \LCI\Blend\Chunk($this->modx, $this->blender);
$blendChunk
->setName($name)
->setSeedsDir($this->getTimestamp());// This is needed to retrieve the down data
if ( $blendChunk->revertBlend() ) {
$this->blender->out($blendChunk->getName().' setting has been reverted to '.$this->getTimestamp());
} else {
$this->blender->out($blendChunk->getName().' setting was not reverted', true);
}
- Now save your file and you can test it out by running all migrations:
php blend --migrate
Same as above but in short formatphp blend -m
And then roll it back:
php blend --migrate --method down
or in short formatphp blend -m -x down
In this example you want to export some templates and the related TVs.
-
Run
php blend --seed --object template
or short commandphp blend -s -o t
you will then be prompted to enter in a comma separated list of template IDs or names that you wish to seed. Note you can also use the--name MyName
option if you don't want the timestamped names and directories. -
Something like
MODX~core/components/blend/database/migrations/m2017_11_14_160105_Template.php
will be created along with the a new directory containing the seed data:
MODX~core/components/blend/database/seeds/2017_11_14_160105/elements
This directory holds both the Template and the dependant TV seeds. You could run the migration, but not much should happen since you just exported the data. If you moved the directories to another MODX install and ran the migration they should now show there. -
If you want to customize the content on export before the seeds are created you can write a plugin, these events are available:
- OnBlendSeedElement
- OnBlendELementBeforeSave
- OnBlendElementAfterSave
Select Resources, for prompt to ask for comma separated list of IDs
php blend --seed --object resource
Only do resource with ID 2
php blend --seed --object resource --id 2
Only do resources that have been created or modified since 2018-01-01
php blend --seed --object resource --date 2018-01-01
Name your seeds to a version or bug number:
php blend --seed --object resource --date 2018-01-01 --name Issue1234
In this example export some resources
-
Run
php blend --seed
you will then be prompted for enter in a comma separated list of resource IDs to include. -
Something like
MODX~core/components/blend/database/migrations/m2017_11_14_162358_Resource.php
will be created along with the a new directory:
MODX~core/components/blend/database/seeds/2017_11_14_162358/resources
This directory holds both the resource seeds. You could run the migration but not much should happen since you just exported the data. If you moved the directories to another MODX install and ran the migration they should show up there.
-
If you want to customize the content on export write a plugin, these event are available:
- OnBlendResourceBeforeSave
- OnBlendResourceAfterSave
- OnBlendSeedResource
- v1.0
- Update/Install MODX
- Add TV convenience methods for building custom migrations
- Media Sources, seed and migrate
- Convert all System Setting to have values that are name key vs int key, templates, resources, ect.
- v1.1
- Extras
- List Migrations in Table, newest to oldest
- v1.2
- Resource Groups
- Seed ACL, user groups & permissions
- Form customizations (via template relations?)
From the command line, assuming you have cloned this repo from git and you are in the project root directory.
All Test
vendor\bin\phpunit
Select Test
vendor\bin\phpunit --bootstrap tests\bootstrap.php tests\BlendTest.php
vendor\bin\phpunit --bootstrap tests\bootstrap.php tests\ChunkTest.php
vendor\bin\phpunit --bootstrap tests\bootstrap.php tests\PluginTest.php
vendor\bin\phpunit --bootstrap tests\bootstrap.php tests\ResourceTest.php
vendor\bin\phpunit --bootstrap tests\bootstrap.php tests\SnippetTest.php
vendor\bin\phpunit --bootstrap tests\bootstrap.php tests\SystemSettingsTest.php
vendor\bin\phpunit --bootstrap tests\bootstrap.php tests\TemplateTest.php