Download the PHP package sokil/php-mongo-migrator without Composer

Stand With Ukraine 🇺🇦

PHPMongo Migrator

Migrations for MongoDB based on PHPMongo ODM

Schema not required in MongoDb, so we dont need to create databases, collections or altering them. However there are some cases when migrations required in schemaless databases:

• Creating collections with special parameters, like capped collection;
• Renaming or deleting collections;
• Creating, renaming or deleting fields;
• Creating, changing or deleting indexes;

Requirements

• PHP 5
  • PHP 5.3 not supported starting from 2018-10-19
  • PHP 5.4 - PHP 5.6
  • PHP Mongo Extension 0.9 or above (Some features require >= 1.5)
• PHP 7
  • PHP MongoDB Extension 1.0 or above
  • Compatibility layer. Please, note some restrictions
• HHVM
  • HHVM Driver not supported.
    
    

Installation

Install locally through composer

After installation you will be able to run commands in console by running ./vendor/bin/mongo-migrator command.

Install using phive

Compatibility with PHP 7

PHPMongo currently based on old ext-mongo entension. To use this ODM with PHP 7, you need to add compatibility layer, which implement API of old extension over new ext-mongodb. To start using PHPMongo with PHP7, add requirement alcaeus/mongo-php-adapter to composer. Restrictions for using ODM with compatibility layer you can read in known issues of original adapter.

You need to require adapter:

Usage

Initialisation of migrations

Every command run in project root where composer.json and vendor dir placed. First we need to create new migration project. To do that go to project root and run:

This creates config file mongo-migrator.yaml and directory "./migrations", where migrations placed. Also you can use php config instead of yaml. Just initialise your project with php config format:

You may explicitly define path to conficuration file, and also to migration dir:

If migration dir defined relatively, it points to dir where configuration stored. In example above migrations dir will be confins/../migrations/mongo.

Configuration

Configuration format

YAML configuration file placed in file "./mongo-migrator.yaml". PHP has same structure.

Environment is set of configuration parameters, defined for concrete place, like development machine, test or production server.

• default_environment - some commands required to know environment, where they executed. This parameters defines which environment to use if environment not specified.

• path.migrations - path to migrations directory, where migration scripts placed.

• environments - section of environment configs.

Every environment has this parameters:

• environments.*.dsn - DSN which used to connect to mongo server

• environments.*.connectOptions - options of MongoClient, described in \MongoClient PHP manual

• environments.*.default_database - databse, used if no database specified id migration script

• environments.*.log_database - database, used to store migration log

• environments..log_collection - collection of database environments..log_database used to store migration log

Environment variables in configuration

Any value may be initialised from environment variable:

Creating new revision

Now you can create your migration script. Creating new revison:

Name of revision must be in camel case format. For example run . This creates migration script like 20151127093706_RevisionName.php, where "20151127093706" is revision id and "RevisionName" is revision name.

Class source is:

Method up() filled with commands executed on migrating process, and down() - on rollback.

Now you can write code for migration and rollback.

Status of migration

If you want to see list of existed revisions with status of migration, run:

If revision status is "up", revision is applied, otherwise status will be "down".

Option configuration allows specify path to project configuration, if it differ from default path. Option length allows to limit elements in list.

Migrating and rollback

You can migrate and rollback to any of available revisions. Commands to migrate:

If revision not specified, migration goes to latest revision.

Option configuration allows specify path to project configuration, if it differ from default path.

Command to rollback:

If revision not specified, rollback goes to previous revision.

Option configuration allows specify path to project configuration, if it differ from default path.

Writing migration scripts

Databases and collections accessable from migration script through methods AbstractMigration::getDatabase and AbstractMigration::getCollection. Method AbstractMigration::getCollection get's collection of default database, defined in
"environments.*.default_database" parameter of config.

Documentation on database and collection classes may be found in https://github.com/sokil/php-mongo.

Building Phar

1) Install box using manual at https://github.com/box-project/box2. It must be accessible as box

2) Check that composer installed and accessible in PATH

3) You may build phar in three modes: unsigned version, signed by OPENSSH (for self test on run) and signed by GPG (for installation through phive)

3.1) To build unsigned version just run make `

3.2) To build phar signed with OPENSSH, you need to have own private key. Copy it to ./keys/private.pem or generate new one:

Then build phar: `

3.3) To build phar sighen with GPG for phive, you need to place private key to ./keys/private.ask:

Then build GPG-signed phar: `

You may verify phar by public key:

You may build phars both for legacy and new driver by defining MONGO_DRIVER env variable:

If MONGO_DRIVER env variable not passed, then make will try to detect your driver automatically.

Development

To start development environment in docker run:

To use xdebug, configure your IDE to use port 9001.

There is sandbox to test commands:

Unit tests

Local tests:

Docker tests: