Wp Steroids Laravel Package

Getting Started

metabolism/wp-steroids is a configuration layer for WordPress: instead of scattering register_post_type(), register_taxonomy(), register_nav_menus() and register_sidebar() calls across functions.php and plugin files, you declare them in YAML and the package registers them on init. For a Laravel developer the mental model is immediate — it is config/*.php plus a service provider, except the provider is the package and the config is YAML.

Minimal steps:

1. Install via Composer. The repo is not on Packagist under a well-known name, so expect to add a vcs repository entry or a path repository if you are vendoring it:

   "repositories": [{ "type": "vcs", "url": "[email protected]:metabolism/wp-steroids.git" }],
   "require": { "metabolism/wp-steroids": "dev-master" }
   

   Then composer dump-autoload -o. Confirm the package's autoloader actually runs — in a classic (non-Bedrock) WordPress install, the root vendor/autoload.php is often not required by default, so add require_once __DIR__ . '/vendor/autoload.php'; to wp-config.php or your mu-plugin loader.

2. Read the source before the README. Start with composer.json (namespace + autoload map), then the class that parses the YAML (grep for yaml, Symfony\Component\Yaml, or parse). The README will show a sample config, but the parser is the source of truth for which keys are supported and what the defaults are. Look for the filename convention the package searches for — it will be something like steroids.yml, wp-steroids.yml, or a config/ directory relative to the theme.

3. First use case: a custom post type. Replace a 40-line register_post_type() block with the equivalent YAML node (labels, public, supports, has_archive, rewrite). Load the site, hit Settings → Permalinks → Save to flush rewrite rules, and verify the CPT appears in the admin menu. That single loop — edit YAML, flush, observe — teaches you the package's load timing and caching behaviour faster than any docs.

Implementation Patterns

Declarative registration as the default. Move every CPT, taxonomy, nav menu, sidebar, and shortcode definition into YAML and keep functions.php down to bootstrapping. This is the highest-leverage use: configuration becomes reviewable in a diff, and non-PHP colleagues can add a CPT without touching code.

Environment layering. Treat it exactly like Laravel's config/{env} convention. Keep a base YAML committed for all environments and an environment-specific override (local dev enabling debug, a staging domain in rewrite, or a show_in_rest toggle) that is not committed or is generated at deploy time. If the package does not support merge/override natively, do it yourself: concatenate files in a small loader and pass the merged array in, or use a build step that renders the final YAML.

Split config by domain, not by type. A single 600-line YAML file rots. Prefer config/post-types/*.yml, config/taxonomies/*.yml, config/menus.yml, and glob them in. If the package only reads one file, check for an imports/includes key in the parser; if absent, write a tiny mu-plugin that merges files and writes a cached artefact rather than fighting the package.

Commit the config, regenerate on deploy. YAML belongs in the theme or a site-specific plugin repo. In CI, run composer install --no-dev -o, then wp rewrite flush --hard as part of the release task so CPT slugs and archive permalinks match the new config. Skipping this is the single most common cause of "works locally, 404s in production."

Treat it as a service-provider boundary. Anything declarative goes in YAML; anything with logic (custom meta boxes with conditional rendering, REST controllers, cron jobs) goes in a normal PHP class hooked the usual way. Do not try to encode business rules in YAML — you will end up with an untyped, untestable config DSL.

Pair with WP-CLI for verification. wp post-type list, wp taxonomy list, wp menu list give you a fast assertion that the YAML actually produced registered objects, which is far better than clicking through wp-admin. Wrap that in a smoke test in CI.

Use filters as the escape hatch. Even when a property is declarative, WordPress filters (register_post_type_args, register_taxonomy_args) still run. Hook them to tweak behaviour per-request (e.g. hide a CPT from search on the front end) without editing the YAML — keeps config stable and intent local.

Gotchas and Tips

YAML is a footgun in PHP land. Tabs are illegal for indentation (spaces only), unquoted yes/no/on/off become booleans under YAML 1.1 parsers — which will silently turn has_archive: no into false or, worse, a string into true. Always quote boolean-looking strings: 'yes', 'no'. Quote version strings ('8.1') so they do not become floats. Quote anything containing : followed by a space.

Load-order and timing. Registration must happen on init (priority 10 or earlier) but after the package has parsed its config. If you see "post type not found" intermittently, something is registering at after_setup_theme or a plugin is calling register_post_type too late/early. Grep the package for add_action( 'init' to confirm the priority and adjust your own hooks around it.

Rewrite rules do not flush themselves. Changing a CPT rewrite.slug, has_archive, or a taxonomy's with_front requires a permalink flush. The package will not do this for you (and shouldn't — flushing on every request is a performance killer). Add wp rewrite flush --hard to your deploy, or a one-time flush_rewrite_rules() behind an option flag.

Caching layers. If the parsed YAML is cached (transient, object cache, or a compiled PHP file), editing the YAML on a site with a persistent object cache (Redis/Memcached) may appear to do nothing. Find the cache key in the source and either flush it explicitly or disable the cache in WP_DEBUG environments.

Silent failure is the default. A malformed YAML file typically yields a PHP warning buried in debug.log and an empty config array — the site loads fine, the CPT just isn't there. Turn on WP_DEBUG/WP_DEBUG_LOG, and during onboarding dump the parsed array with error_log( print_r( $config, true ) ) to see exactly what the parser produced versus what you wrote.

i18n stops at the YAML boundary. Label strings declared in YAML are not automatically run through the theme/plugin text domain. If the site is multilingual, either pass already-translated strings at runtime via a filter, or keep labels in PHP where __() is available, using YAML only for structural properties.

Autoloading in classic WordPress installs. Bedrock/Roots setups are painless. A stock wp-content install needs the Composer autoloader loaded manually, and if the package expects to live inside a theme's vendor/, composer require at the site root and confirm the path the package resolves config from is the one you think it is (use get_template_directory() vs WP_CONTENT_DIR — they differ in multisite).

Multisite. Config is per-site by file location but often shared by code deploy. If CPTs should differ per site in a network, you need per-site YAML paths or filters — verify the package resolves paths via get_current_blog_id() before relying on it.

Extension points worth knowing. Look for a filter or action the package fires after parsing, before registration. That hook is where you inject computed values (e.g. label prefixes from an ACF options page) and is far cleaner than post-processing the registry with register_post_type_args. If no such hook exists, the parser class is usually protected-method-heavy and can be subclassed — but prefer the filter; subclassing a third-party parser is a maintenance tax.

Release cadence caveat. Twenty-three stars and a 2026 release date mean a small user base — expect thinner docs and less Stack Overflow coverage than register_post_type() itself. Pin a version in composer.json, read the diff before upgrading, and keep a fallback path: because everything the package does is ultimately register_* calls, a migration back to plain PHP is mechanical, not a rewrite.