{"id":13480770,"url":"https://github.com/sokil/php-mongo-migrator","last_synced_at":"2025-10-12T23:03:53.015Z","repository":{"id":17554788,"uuid":"20357685","full_name":"sokil/php-mongo-migrator","owner":"sokil","description":"Migrations of MongoDB. Part of @PHPMongoKit","archived":false,"fork":false,"pushed_at":"2024-01-03T09:42:38.000Z","size":455,"stargazers_count":29,"open_issues_count":4,"forks_count":16,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-29T10:41:38.201Z","etag":null,"topics":["migration","mongo","mongo-migrator","mongodb","odm","php","phpmongokit","schema-migrations"],"latest_commit_sha":null,"homepage":"http://phpmongokit.github.io/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sokil.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2014-05-31T14:46:13.000Z","updated_at":"2024-01-03T09:42:20.000Z","dependencies_parsed_at":"2024-01-09T23:10:20.984Z","dependency_job_id":"c47695da-eb9f-41cd-91a6-867ac66302fa","html_url":"https://github.com/sokil/php-mongo-migrator","commit_stats":{"total_commits":201,"total_committers":6,"mean_commits":33.5,"dds":0.1691542288557214,"last_synced_commit":"e045d3ab011b1bbae8783b4d68665d12fefb513e"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/sokil/php-mongo-migrator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sokil%2Fphp-mongo-migrator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sokil%2Fphp-mongo-migrator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sokil%2Fphp-mongo-migrator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sokil%2Fphp-mongo-migrator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sokil","download_url":"https://codeload.github.com/sokil/php-mongo-migrator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sokil%2Fphp-mongo-migrator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279013418,"owners_count":26085274,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["migration","mongo","mongo-migrator","mongodb","odm","php","phpmongokit","schema-migrations"],"created_at":"2024-07-31T17:00:44.799Z","updated_at":"2025-10-12T23:03:52.997Z","avatar_url":"https://github.com/sokil.png","language":"PHP","funding_links":[],"categories":["Libraries"],"sub_categories":["PHP"],"readme":"# Stand With Ukraine 🇺🇦\n\n[![SWUbanner](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner-direct.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md)\n\nPHPMongo Migrator\n==================\n\nMigrations for MongoDB based on [PHPMongo ODM](https://github.com/sokil/php-mongo)\n\n[![Daily Downloads](https://poser.pugx.org/sokil/php-mongo-migrator/d/daily)](https://packagist.org/packages/sokil/php-mongo-migrator)\n[![Latest Stable Version](https://poser.pugx.org/sokil/php-mongo-migrator/v/stable.png)](https://packagist.org/packages/sokil/php-mongo-migrator)\n[![Coverage Status](https://coveralls.io/repos/sokil/php-mongo-migrator/badge.png)](https://coveralls.io/r/sokil/php-mongo-migrator)\n[![Gitter](https://badges.gitter.im/Join_Chat.svg)](https://gitter.im/sokil/php-mongo-migrator?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\nSchema 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:\n* Creating collections with special parameters, like capped collection;\n* Renaming or deleting collections;\n* Creating, renaming or deleting fields;\n* Creating, changing or deleting indexes;\n\nRequirements\n------------\n\n* PHP 5\n  * PHP 5.3 not supported starting from 2018-10-19\n  * PHP 5.4 - PHP 5.6\n  * [PHP Mongo Extension](https://pecl.php.net/package/mongo) 0.9 or above (Some features require \u003e= 1.5)\n* PHP 7\n  * [PHP MongoDB Extension](https://pecl.php.net/package/mongodb) 1.0 or above\n  * [Compatibility layer](https://github.com/alcaeus/mongo-php-adapter). Please, note some [restrictions](#compatibility-with-php-7)\n* HHVM\n  * HHVM Driver [not supported](https://derickrethans.nl/mongodb-hhvm.html).\n\u003cbr/\u003e\n\u003cbr/\u003e\n\nInstallation\n------------\n\n#### Install locally through composer\n\n```\ncomposer require sokil/php-mongo-migrator\n```\n\nAfter installation you will be able to run commands in console by running ./vendor/bin/mongo-migrator command.\n\n#### Install using phive\n\n```\nphive install sokil/php-mongo-migrator\n```\n\n#### Compatibility with PHP 7\n\n\u003e PHPMongo currently based on old [ext-mongo](https://pecl.php.net/package/mongo) entension.\n\u003e To use this ODM with PHP 7, you need to add [compatibility layer](https://github.com/alcaeus/mongo-php-adapter), which implement API of old extension over new [ext-mongodb](https://pecl.php.net/package/mongodb).\n\u003e To start using PHPMongo with PHP7, add requirement [alcaeus/mongo-php-adapter](https://github.com/alcaeus/mongo-php-adapter) to composer.\n\u003e Restrictions for using ODM with compatibility layer you can read in [known issues](https://github.com/alcaeus/mongo-php-adapter#known-issues) of original adapter.\n\nYou need to require adapter:\n```\ncomposer require alcaeus/mongo-php-adapter\n```\n\nUsage\n------\n\n```\n$ ./mongo-migrator\nConsole Tool\n\nUsage:\n  command [options] [arguments]\n\nOptions:\n  -h, --help            Display this help message\n  -q, --quiet           Do not output any message\n  -V, --version         Display this application version\n      --ansi            Force ANSI output\n      --no-ansi         Disable ANSI output\n  -n, --no-interaction  Do not ask any interactive question\n  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug\n\nAvailable commands:\n  create    Create new migration\n  help      Displays help for a command\n  init      Initialize migrations project\n  list      Lists commands\n  migrate   Migrate to specific revision of database\n  rollback  Rollback to specific version of database\n  status    Show status of migrations\n```\n\nInitialisation of migrations\n----------------------------\n\nEvery command run in project root where composer.json and vendor dir placed. First we need to create \nnew migration project. To do that go to project root and run:\n```\nvendor/bin/mongo-migrator init\n```\n\nThis creates config file mongo-migrator.yaml and directory \"./migrations\", where migrations placed.\nAlso you can use php config instead of yaml. Just initialise your project with php config format:\n\n```\nvendor/bin/mongo-migrator init --configFormat=php\n```\n\nYou may explicitly define path to conficuration file, and also to migration dir:\n\n```\nvendor/bin/mongo-migrator init --configuration=confins/monfo-migrations.yaml --migrationDir=../migrations/mongo\n``` \n\nIf migration dir defined relatively, it points to dir where configuration stored. In example above migrations \ndir will be `confins/../migrations/mongo`. \n\nConfiguration\n-------------\n\n#### Configuration format\n\nYAML configuration file placed in file \"./mongo-migrator.yaml\". PHP has same structure.\n\n```yaml\ndefault_environment: development\n\npath:\n    migrations: migrations\n    \nenvironments:\n    development:\n        dsn: mongodb://localhost\n        \n        default_database: test\n        \n        log_database: test\n        log_collection: migrations\n    \n    staging:\n        dsn: mongodb://localhost\n        \n        default_database: test\n        \n        log_database: test\n        log_collection: migrations\n    \n    production:\n        dsn: mongodb://localhost\n        \n        default_database: test\n        \n        log_database: test\n        log_collection: migrations\n```\n\nEnvironment is set of configuration parameters, defined for concrete place, like \ndevelopment machine, test or production server. \n\n* default_environment - some commands required to know environment, where they executed.\nThis parameters defines which environment to use if environment not specified.\n\n* path.migrations - path to migrations directory, where migration scripts placed.\n\n* environments - section of environment configs. \n\nEvery environment has this parameters:\n\n* environments.*.dsn - DSN which used to connect to mongo server\n\n* environments.*.connectOptions - options of MongoClient, described in [\\MongoClient PHP manual](http://php.net/manual/ru/mongoclient.construct.php)\n\n* environments.*.default_database - databse, used if no database specified id migration script\n\n* environments.*.log_database - database, used to store migration log\n\n* environments.*.log_collection - collection of database environments.*.log_database used to store migration log\n\n#### Environment variables in configuration\n\nAny value may be initialised from environment variable:\n\n```yaml\n\ndefault_environment: common\n\npath:\n    migrations:  \"%env(MONGO_MIGRATIONS_PATH)%\"\n\nenvironments:\n    common:\n        dsn: \"%env(MONGO_DSN)%\"\n        default_database: \"%env(MONGO_DEFAULT_DB)%\"\n        log_database: \"%env(MONGO_LOG_DB)%\"\n        log_collection: \"%env(MONGO_LOG_COLLECTION)%\"\n```\n\nCreating new revision\n---------------------\nNow you can create your migration script. Creating new revison:\n```\nvendor/bin/mongo-migrator create revision_name\n```\n\nName of revision must be in camel case format. For example run ```vendor/bin/mongo-migrator create RevisionName```. \nThis creates migration script like 20151127093706_RevisionName.php, where \"20151127093706\"\nis revision id and \"RevisionName\" is revision name. \n\n```\npc:~/php-mongo-migrator$ ./bin/mongo-migrator create RevisionName\nNew migration created at ~/php-mongo-migrator/migrations/20151127093706_RevisionName.php\n```\n\nClass source is:\n\n```php\n\u003c?php\n\nclass RevisionName extends \\Sokil\\Mongo\\Migrator\\AbstractMigration\n{\n    public function up()\n    {\n        \n    }\n    \n    public function down()\n    {\n        \n    }\n}\n``` \n\nMethod up() filled with commands executed on migrating process, and down() - on rollback.\n\nNow you can write code for migration and rollback.\n\nStatus of migration\n-------------------\nIf you want to see list of existed revisions with status of migration, run:\n```\nvendor/bin/mongo-migrator status [-e|--environment environment=ENVIRONMENT] [-c|--configuration=CONFIGURATION] [-l|--length=LENGTH]\n```\n\nIf revision status is \"up\", revision is applied, otherwise status will be \"down\".\n```\n Revision        Status  Name            \n-----------------------------------       \n 20140607165612  down    Test2           \n 20140607141237  up      Test1           \n 20140607132630  up      RevisionName\n```\n\nOption `configuration` allows specify path to project configuration, if it differ from default path. \nOption `length` allows to limit elements in list.\n\nMigrating and rollback\n----------------------\n\nYou can migrate and rollback to any of available revisions. Commands to migrate:\n\n```\nvendor/bin/mongo-migrator migrate  [-r|--revision revision] [-e|--environment environment] [-c|--configuration configuration]\n```\nIf revision not specified, migration goes to latest revision.\n\nOption `configuration` allows specify path to project configuration, if it differ from default path.\n \nCommand to rollback:\n```\nvendor/bin/mongo-migrator rollback [-r|--revision revision] [-e|--environment environment] [-c|--configuration configuration]\n```\nIf revision not specified, rollback goes to previous revision.\n\nOption `configuration` allows specify path to project configuration, if it differ from default path.\n\nWriting migration scripts\n--------------------------\n\nDatabases and collections accessable from migration script through methods \nAbstractMigration::getDatabase and AbstractMigration::getCollection. Method\nAbstractMigration::getCollection get's collection of default database, defined in  \n\"environments.*.default_database\" parameter of config.\n\nDocumentation on database and collection classes may be \nfound in https://github.com/sokil/php-mongo.\n\n```php\n\u003c?php\n\nclass RevisionName extends \\Sokil\\Mongo\\Migrator\\AbstractMigration\n{\n    protected function init() \n    {\n        // some common code\n    }\n    \n    public function up()\n    {\n        $collection = $this\n            -\u003egetDatabase('some_database')\n            -\u003egetCollection('come_collection');\n\n        // create new field in all documents of collection\n        $collection-\u003eupdateAll(function($operator) {\n            $operator-\u003eset('newField', 'defaultValue')\n        });\n    }\n    \n    public function down()\n    {\n        $collection = $this\n            -\u003egetDatabase('some_database')\n            -\u003egetCollection('come_collection');\n\n        // create new field in all documents of collection\n        $collection-\u003eupdateAll(function($operator) {\n            $operator-\u003eunsetField('newField')\n        });\n    }\n}\n```\n\nBuilding Phar\n-------------\n\n1) Install box using manual at https://github.com/box-project/box2. It must be accessible as `box`\n\n2) Check that `composer` installed and accessible in PATH\n\n3) 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)\n \n3.1) To build unsigned version just run make\n```\nmake\n````\n\n3.2) To build phar signed with OPENSSH, you need to have own private key. \nCopy it to `./keys/private.pem` or generate new one:\n```\n# Generate new one:\nopenssl genrsa -des3 -out private.pem 4096\n# If you want to remove passphrase\nopenssl rsa -in private.pem -out private.pem\n# generate public\nopenssl rsa -in private.pem -outform PEM -pubout -out public.pem\n```\nThen build phar:\n```\nmake openssh-signed\n````\n\n3.3) To build phar sighen with GPG for phive, you need to place private key to `./keys/private.ask`:\n```\ngpg --gen-key\ngpg --export-secret-keys your@mail.com \u003e keys/private.asc\n```\nThen build GPG-signed phar:\n```\nmake gpg-signed\n````\n\nYou may verify phar by public key:\n```\n$ gpg --verify mongo-migrator.phar.asc mongo-migrator.phar\ngpg: Signature made чт, 22-лис-2018 23:27:46 +0200 EET\ngpg:                using RSA key F530929F7ED528F0\ngpg:                issuer \"dmytro.sokil@gmail.com\"\ngpg: Good signature from \"Dmytro Sokil \u003cdmytro.sokil@gmail.com\u003e\" [ultimate]\n\n```\n\nYou may build phars both for legacy and new driver by defining `MONGO_DRIVER` env variable:\n\n```\nmake gpg-signed MONGO_DRIVER=new\nmake gpg-signed MONGO_DRIVER=legacy\n```\n\nIf `MONGO_DRIVER` env variable not passed, then `make` will try to detect your driver automatically.\n\nDevelopment\n-----------\n\nTo start development environment in docker run:\n```\n./run-docker-cli.sh\n```\n\nTo use `xdebug`, configure your IDE to use port 9001.\n\nThere is sandbox to test commands:\n\n```\ncd /phpmongo/tests/\nexport PHPMONGO_DSN=\"mongodb://mongodb32\"; ../bin/mongo-migrator -vvv status -l 4 -e docker\n``` \n\nUnit tests\n----------\n\nLocal tests:\n\n```\ncomposer.phar test\n```\n\nDocker tests:\n\n```\n./run-docker-tests.sh\n```\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsokil%2Fphp-mongo-migrator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsokil%2Fphp-mongo-migrator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsokil%2Fphp-mongo-migrator/lists"}