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

PHPMongo Migrator

Note: This is a fork of the original sokil/php-mongo-migrator project, updated for PHP 8.1+ compatibility. This fork replaces the deprecated sokil/php-mongo ODM with the official MongoDB PHP Library.

Migrations for MongoDB using the official MongoDB PHP Library.

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 8.1 or above
• PHP MongoDB Extension 1.0 or above
• MongoDB PHP Library (installed automatically via Composer)

Installation

Install locally through composer

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

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 are accessible from migration scripts through methods AbstractMigration::getDatabase() and AbstractMigration::getCollection(). The method AbstractMigration::getCollection() gets a collection from the default database, defined in
environments.*.default_database parameter of config.

This library now uses the official MongoDB PHP Library. Documentation on database and collection classes may be found in the MongoDB PHP Library documentation.

What's Changed in This Fork

This fork includes the following major changes from the original project:

• PHP 8.1+ Support: Requires PHP 8.1 or higher (original supported PHP 5.6-7.x)
• Modern MongoDB Library: Replaced sokil/php-mongo with the official mongodb/mongodb library
• Updated Dependencies:
  • Symfony components updated to 6.x/7.x
  • PHPUnit updated to 10.x/11.x
  • Modern PHP syntax with type declarations throughout
• Breaking Changes: Migration scripts using the old sokil/php-mongo API will need to be updated (see migration guide below)

Migration from older versions

If you're upgrading from a version that used sokil/php-mongo, you'll need to update your migration scripts:

For more examples, see the MongoDB PHP Library documentation.

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:

Note: The MONGO_DRIVER environment variable is no longer used in this fork, as it only supports the modern MongoDB PHP extension (ext-mongodb).

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: