PHPackages                             wpdesk/wp-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. [Database & ORM](/categories/database)
4. /
5. wpdesk/wp-migrations

ActiveLibrary[Database & ORM](/categories/database)

wpdesk/wp-migrations
====================

Doctrine Migrations clone suited for WordPress purposes.

1.2.0(3mo ago)03.1kMITPHPPHP ^7.4|^8CI failing

Since Jun 14Pushed 1mo agoCompare

[ Source](https://github.com/WP-Desk/wp-migrations)[ Packagist](https://packagist.org/packages/wpdesk/wp-migrations)[ RSS](/packages/wpdesk-wp-migrations/feed)WikiDiscussions main Synced 2w ago

READMEChangelogDependencies (8)Versions (9)Used By (0)

WP Migrations
=============

[](#wp-migrations)

WP Migrations is a simple database migration library for WordPress projects, inspired by Doctrine Migrations. It allows developers to manage database schema updates incrementally using versioned PHP classes, ensuring that schema changes are applied safely, in order, and without race conditions in concurrent environments.

Unlike traditional migration systems, WP Migrations is tailored specifically for the WordPress runtime environment. It utilizes WordPress features such as the `\wpdb` database connection, options table storage for schema versions, post-based mutex locking, and WordPress admin notice UI for logging errors.

Key Features
------------

[](#key-features)

- **WordPress Integration**: Built natively to interact with `\wpdb` and use the WordPress database abstraction layer (including automatic availability of `dbDelta()`).
- **Multiple Repository Drivers**: Supports loading migration classes directly from static lists via ArrayMigrationsRepository or dynamically from folders via FilesystemMigrationsRepository.
- **Concurrency Protection**: Leverages a robust locking mechanism using a mutex implementation (such as `WordpressPostMutex`) to prevent concurrent migration executions that could corrupt database schemas.
- **Fail-safe Logic and Verification**: Includes an `is_needed()` check inside migrations, allowing double-verification of DB state (e.g., column existence checks) before attempting modifications.
- **Admin Notice Notifications**: Persists migration failures and displays native WordPress admin notices using MigrationErrorNotice to warn administrators of database update issues.
- **Robust Database Logging**: Built-in WpdbLogger that logs migration lifecycle stages directly to a dedicated database option, keeping the last 30 log records.

Requirements
------------

[](#requirements)

The library requires the following system dependencies, as defined in composer.json:

- **PHP**: `^7.4` or `^8`
- **JSON Extension**: Ext-JSON enabled (`*`)
- **PSR Log**: `psr/log` version `^1`
- **WP Desk Mutex**: `wpdesk/wp-mutex` version `^1.1` (used for transaction-like locking)
- **WP Desk Notice**: `wpdesk/wp-notice` version `^3.3` (used for admin-facing error notices)
- **WordPress**: A standard WordPress environment (providing `\wpdb`, database options APIs, and admin functions)

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require wpdesk/wp-migrations
```

Ensure that your project includes the Composer autoloader:

```
require_once __DIR__ . '/vendor/autoload.php';
```

Usage
-----

[](#usage)

### Creating a Migration Class

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

To define a database migration, you must create a class that extends AbstractMigration.

Your migration class should implement the `up()` method and, optionally, override the `is_needed()` method. File names and class names must start with the `Version` prefix (e.g., `Version_20260619_CreateTable.php`).

```