PHPackages                             rhubarbphp/module-migrations - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. rhubarbphp/module-migrations

ActiveLibrary[Framework](/categories/framework)

rhubarbphp/module-migrations
============================

Provides scripted updates for managed transitions in application versions

1.0.2(6y ago)04.5k[1 issues](https://github.com/RhubarbPHP/Module.Migrations/issues)1Apache-2.0PHP

Since Sep 19Pushed 6y ago14 watchersCompare

[ Source](https://github.com/RhubarbPHP/Module.Migrations)[ Packagist](https://packagist.org/packages/rhubarbphp/module-migrations)[ Docs](http://www.rhubarbphp.com/)[ RSS](/packages/rhubarbphp-module-migrations/feed)WikiDiscussions master Synced 2mo ago

READMEChangelogDependencies (7)Versions (4)Used By (1)

Migrations Module
=================

[](#migrations-module)

Commonly, when applications are upgraded there are breaking changes that require a scripted solution. This module provides a framework to: quickly generate migration scripts; manage the local version of an instance of your application, and; run migration scripts in order to bring your local version up-to-date with the current project version.

Setting the application version
-------------------------------

[](#setting-the-application-version)

The current application version needs to be defined when your project is initialized. The version must be an integer.

```
class MyApplication extends Application
{
    public function initialise()
    {
        // ...
        $this->version = 12;
        // ...
    }
}
```

Creating a migration script
---------------------------

[](#creating-a-migration-script)

A migration script must implement the MigrationScriptInterface.

**execute()** is the logic of the migration.

**version()** must return an integer and defines on which application version this script should be executed. Migrations are executed in an order of version. Migrations on the same version are executed in the order they are registered.

```
class ImageDeletionScript extends MigrationScript
{
        public function execute()
        {
            foreach (Image::all(new Equals('active', false)) as $image) {
                unlink($image->filePath);
                $image->delete();
            }
        }

        public function version(): int
        {
            return 17;
        }
}
```

Registering your script
-----------------------

[](#registering-your-script)

Scripts will not be ran unless they are registered. Scripts are registered by calling `registerMigrationScripts($scriptsArray)` on MigrationsModule.

```
   MigrationsManager::getMigrationsManager()->registerMigrationScripts([
       SplitNameColumnScript::class,
       DeleteAllImagesScript::class,
       UpdatedGdprInfoScript::class
   ]);
```

Custard Commands
----------------

[](#custard-commands)

### migrations:migrate

[](#migrationsmigrate)

The primary migrate command. All registered migration scripts with a version of or between the current locally stored version and the application version defined in code will be loaded and executed.

##### Options

[](#options)

OptionshortcutDescriptionSkip Scripts-sIt is possible to skip certain scripts, for example if you are re-running a failed migration and do not want to include the failing script. To do so include the option -s followed by the full path of the script to skip. You can include multiple scripts with -s.##### Example

[](#example)

`custard migrations:migrate -s My\Project\Scripts\NewMigrationScript.php -s My\Project\Scripts\DestroyOldDataScript.php`

### migrations:run-script

[](#migrationsrun-script)

Takes the full path of a script and immediately executes it.

##### Example

[](#example-1)

`custard migrations:run-script My\Project\Scripts\NewMigrationScript.php`

MigrationsManager
-----------------

[](#migrationsmanager)

The MigrationsManager is used to register and retrieve Migration Scripts. It's core function is to provide a set of active, valid and ordered migration scripts within a range via the `getMigrationScripts()` function.

The MigrationsManager implemented the Singleton trait and can be accessed via `MigrationsManager::getMigrationsManager()`

MigrationsStateProvider
-----------------------

[](#migrationsstateprovider)

The `MigrationsStateProvider` handles the current local version of the application and which migration scripts have been run. It must implement the following methods:

`getLocalVersion()` retrieves the local version. Must return an integer.

`setLocalVersion(int $newLocalVersion)` updates the local version.

`markScriptCompleted(MigrationScriptInterface $migrationScript)` locally stores a script as having been successfully executed.

`isScriptComplete(string $className)` checks if a script has already been successfully executed.

`getCompletedScripts()`

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity20

Limited adoption so far

Community18

Small or concentrated contributor base

Maturity64

Established project with proven stability

 Bus Factor1

Top contributor holds 81.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~133 days

Total

3

Last Release

2532d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/8905301607df4f73893d5b665c97b959572bc9394a5ff3c9f5907de6531aad6d?d=identicon)[acuthbert](/maintainers/acuthbert)

---

Top Contributors

[![smcgarrity](https://avatars.githubusercontent.com/u/30289236?v=4)](https://github.com/smcgarrity "smcgarrity (39 commits)")[![acuthbert](https://avatars.githubusercontent.com/u/408400?v=4)](https://github.com/acuthbert "acuthbert (5 commits)")[![sean-mcgarrity](https://avatars.githubusercontent.com/u/4341435?v=4)](https://github.com/sean-mcgarrity "sean-mcgarrity (4 commits)")

---

Tags

phpframeworkmigrationscriptversionrhubarb

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/rhubarbphp-module-migrations/health.svg)

```
[![Health](https://phpackages.com/badges/rhubarbphp-module-migrations/health.svg)](https://phpackages.com/packages/rhubarbphp-module-migrations)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)