README

WordPress-aware CLI for running ordered, tracked PHP patches. When ruelluna/wpsage is installed in a Sage theme (via that theme’s composer.json), the default patch folder is database/patches at the theme root (next to composer.json). If the package is only installed at the WordPress root, the default is database/patches under the WordPress root instead. Patches can call WordPress APIs after bootstrap.

Install

Require the package in the same Composer project where you run the CLI (typically your Sage theme directory, or the WordPress root if you use a root composer.json). Then run composer install so vendor/autoload.php exists.

From your WordPress root (directory containing wp-load.php), if Composer lives there:

composer require ruelluna/wpsage

Or add a path / VCS repository while developing:

{
  "repositories": [
    { "type": "path", "url": "../wpsage" }
  ],
  "require": {
    "ruelluna/wpsage": "@dev"
  }
}

Usage

vendor/bin/wpsage patch:install
vendor/bin/wpsage patch:run
vendor/bin/wpsage patch:rollback
vendor/bin/wpsage patch:rollback --step=3

Configuration

Defaults:

Patches directory: database/patches, relative to the Sage theme root when the CLI is run from a theme install (style.css + composer.json or app/ is detected above vendor/), otherwise relative to the WordPress root
Tracking table: {wpdb_prefix}wpsage_patches

Override with a wpsage.php file at the WordPress root that returns an array. Paths are relative to the theme root when wpsage is installed in a theme (same base as the default); you can set an absolute patches_directory if patches live under the WordPress root instead.

<?php

return [
    'table_suffix' => 'wpsage_patches',
    'patches_directory' => 'database/patches',
];

Or use environment variables (override file values if set):

WPSAGE_TABLE_SUFFIX — suffix appended to $wpdb->prefix (letters, numbers, underscores only)
WPSAGE_PATCHES_DIR — relative to the same base as above, or an absolute path

To keep an existing gerbers_patches table when migrating from the old gerbers script, set table_suffix to gerbers_patches.

Patch file format

Each patch is a PHP file that returns an array with up and down callables:

<?php

return [
    'up' => static function (): void {
        // run migration
    },
    'down' => static function (): void {
        // reverse migration
    },
];

Files are executed in ascending filename order. Each file runs at most once until rolled back.

Source

https://github.com/ruelluna/wpsage

ruelluna / wpsage

Maintainers

Package info

Statistics

Security