{"id":19107775,"url":"https://github.com/alleyinteractive/wp-theme-migrator","last_synced_at":"2025-07-11T07:39:26.107Z","repository":{"id":145027939,"uuid":"602172427","full_name":"alleyinteractive/wp-theme-migrator","owner":"alleyinteractive","description":"A WordPress library to migrate to a new theme incrementally.","archived":false,"fork":false,"pushed_at":"2024-04-08T19:24:07.000Z","size":78,"stargazers_count":6,"open_issues_count":1,"forks_count":1,"subscribers_count":23,"default_branch":"develop","last_synced_at":"2024-10-12T22:40:24.080Z","etag":null,"topics":["wordpress-migration","wordpress-php-library"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alleyinteractive.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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,"dei":null}},"created_at":"2023-02-15T16:43:05.000Z","updated_at":"2024-06-07T08:37:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"b2def71e-cf43-4485-8cd7-fe86973d41c7","html_url":"https://github.com/alleyinteractive/wp-theme-migrator","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":"alleyinteractive/create-php-package","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-theme-migrator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-theme-migrator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-theme-migrator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-theme-migrator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alleyinteractive","download_url":"https://codeload.github.com/alleyinteractive/wp-theme-migrator/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223783042,"owners_count":17201915,"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","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":["wordpress-migration","wordpress-php-library"],"created_at":"2024-11-09T04:13:54.820Z","updated_at":"2024-11-09T04:13:55.464Z","avatar_url":"https://github.com/alleyinteractive.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WP Theme Migrator\n\n[![Coding Standards](https://github.com/alleyinteractive/wp-theme-migrator/actions/workflows/coding-standards.yml/badge.svg)](https://github.com/alleyinteractive/wp-theme-migrator/actions/workflows/coding-standards.yml)\n[![Testing Suite](https://github.com/alleyinteractive/wp-theme-migrator/actions/workflows/unit-test.yml/badge.svg)](https://github.com/alleyinteractive/wp-theme-migrator/actions/workflows/unit-test.yml)\n\nA library to support agile, incremental theme migrations in WordPress.\n\n## Background\n\nThis library facilitates an incremental approach to migrating a WordPress site to a new theme.\n\nThe conventional strategy for re-theming a site is to build an entire theme, then activate the new theme on the production environment when it's complete. This library enables you to use [a Strangler Fig pattern](https://martinfowler.com/bliki/StranglerFigApplication.html) to move gradually from an old theme to a new theme, with both themes installed on the production environment.\n\nThe parameters of the migration strategy are passed via callbacks to the Migrator during initialization. The Migrator parses the current request early and passes the query vars to each callback so you can base the migration strategy on post type, taxonomy, publish date, language, post meta or any public query var that is added before the Migrator is run.\n\nFurthermore, you can define your migration strategy on more than just what's available in the query. The Migrator is agnostic – it only needs to know whether the current request should be migrated to the new theme. So your strategy can draw on globals, constants, an API integration, the day of the week – or any value that's available when the Migrator is run – to determine migratability.\n\nWith thoughtfully structured callbacks, you can even A/B test redesigned pages during development. Individual content types can be built, tested, and released before the theme is complete, bringing a truly iterative cycle to your workflow.\n\n## Releases\n\nThis package follows semantic versioning conventions.\n\n## Roadmap\n\nThis package is in a pre-release status. Milestones to be completed before the first release include:\n\n- Adding feature testing.\n\n\n### Install\n\nRequires Composer and PHP \u003e= 8.0.\n\n\n### Use\n\nInstall a new valid theme. To be valid, it must exist in the `/wp-content/themes/` directory, be compatible with the local WordPress and PHP versions, and include at least a `style.css` file. Do not activate the new theme.\n\nInstall this package via Composer.\n\n```sh\ncomposer require alleyinteractive/wp-theme-migrator\n```\n\nEnsure that the Composer autoloader is loaded into your project.\n\n```php\nrequire_once __DIR__ . '/vendor/autoload.php';\n```\n\nInitialize the Migrator in your project. The Migrator performs its magic on the `setup_theme` hook so it must be initialized before that. Here, the Migrator object is created on the `plugins_loaded` hook:\n\n```php\n/**\n* Initialize WP Theme Migrator early.\n*/\nfunction init_migrator() {\n\ttry {\n\t\t$migrator = new \\Alley\\WP\\Theme_Migrator\\Migrator();\n\t\t$migrator-\u003einit();\n\t} catch( Exception  $e ) {\n\t\t// Do something. The Migrator will throw an Exception when it's\n\t\t// initialized with an invalid theme or callback. Be sure to catch\n\t\t// the Exception to fatal errors.\n\t}\n}\nadd_action( 'plugins_loaded', 'init_migrator' );\n```\n\nPass the name of the new theme and a list of one or more callbacks to the Migrator through filters. A callback must return `true` if a given request should be handled with the new theme. If more than one callback is provided, the Migrator will call each one once until one returns `true`. Then, the Migrator will load the new theme and no more callbacks will be called on that request. If none of the provided callbacks return `true`, the old theme will be loaded.\n\n```php\n/**\n * Pass the new theme to WP Theme Migrator.\n */\nadd_filter( 'wp_theme_migrator_theme', fn() =\u003e 'new-theme-slug' );\n\n/**\n* Add callbacks for WP Theme Migrator to determine migratability.\n*\n* @param callable[] $callbacks Array of callbacks.\n* @param Migrator   $migrator Migrator instance.\n*/\nfunction filter_wp_theme_migrator_callbacks( $context, $migrator) {\n\treturn [\n\t\t'a_callback', // This can be any callable.\n\t\t'another_callback',\n\t];\n}\nadd_filter( 'wp_theme_migrator_callbacks', 'filter_wp_theme_migrator_callbacks', 10, 2 );\n```\n\nDefine your migration strategy through your callbacks.\n```php\n/**\n* Callback to manage theme migration.\n*\n* @param array $query_vars Array of query vars for the current request.\n* @return bool Whether to load the new theme.\n*/\nfunction a_callback( $query_vars ): bool {\n\t// Do something to decide if the current request is migratable.\n}\n```\n\nOnce you've migrated the entire site, activate your new theme, remove this package from your project, and uninstall your old theme.\n\n### From Source\n\nTo work on this project locally, first add the repository to your project's\n`composer.json`:\n\n```json\n{\n\t\"repositories\": [\n\t\t{\n\t\t\t\"type\": \"path\",\n\t\t\t\"url\": \"../path/to/wp-theme-migrator\",\n\t\t\t\"options\": {\n\t\t\t\t\"symlink\": true\n\t\t\t}\n\t\t}\n\t]\n}\n```\n\nNext, add the local development files to the `require` section of\n`composer.json`:\n\n```json\n{\n\t\"require\": {\n\t\t\"alleyinteractive/wp-theme-migrator\": \"@dev\"\n\t}\n}\n```\n\nFinally, update composer to use the local copy of the package:\n\n```sh\ncomposer update alleyinteractive/wp-theme-migrator --prefer-source\n```\n\n### Changelog\n\nThis project keeps a [changelog](CHANGELOG.md).\n\n\n## Development Process\n\nSee instructions above on installing from source. Pull requests are welcome from the community and will be considered for inclusion. Releases follow semantic versioning and are shipped on an as-needed basis.\n\n\n### Contributing\n\nSee [our contributor guidelines](CONTRIBUTING.md) for instructions on how to contribute to this open source project.\n\n\n## Project Structure\n\nThis is a Composer package that is published to [Packagist](https://packagist.org/). Classes are autoloadable using `alleyinteractive/composer-wordpress-autoloader`. They live in the `src` directory and follow standard WordPress naming conventions for classes.\n\n\n## Third-Party Dependencies\n\nDependencies are managed by Composer, and include:\n\n- `alleyinteractive/composer-wordpress-autoloader`: Used for autoloading classes that follow the standard WordPress conventions for filenames.\n- `alleyinteractive/alley-coding-standards`: Used for running phpcs linting.\n- `mantle-framework/testkit`: Used for running unit tests.\n- `symfony/filesystem`: Used for copying files into the WordPress test installation for testing.\n\n\n## Maintainers\n\n- [Alley](https://github.com/alleyinteractive)\n\n![Alley logo](https://avatars.githubusercontent.com/u/1733454?s=200\u0026v=4)\n\n### Contributors\n\nThanks to all of the [contributors](../../contributors) to this project.\n\n\n## License\n\nThis project is licensed under the\n[GNU Public License (GPL) version 2](LICENSE) or later.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falleyinteractive%2Fwp-theme-migrator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falleyinteractive%2Fwp-theme-migrator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falleyinteractive%2Fwp-theme-migrator/lists"}