Sword Bundle Laravel Package

Getting Started

First, an honest framing: phpsword/sword-bundle is a Symfony bundle, not a Composer package you can composer require into a Laravel app and expect to work. There's no service provider, no facades, no artisan. As a Laravel developer, you'll get the most value treating it as (a) reference architecture for how to cleanly bridge WordPress and a modern PHP framework, or (b) a tool for a standalone Symfony sidecar that runs WP admin/theme code while your Laravel app consumes the result over HTTP (headless WP).

Minimum setup:

composer require phpsword/sword-bundle

1. Register the bundle in config/bundles.php:

   return [
       Sword\Bundle\SwordBundle::class => ['all' => true],
   ];
   

2. Point your Symfony kernel's bootstrapping at a wp-load.php file inside public/ so WordPress is initialized before the container resolves WP-dependent services.
3. Add a config/packages/sword.yaml with your WP paths and any Twig/hook options.
4. Look first at the bundle's DependencyInjection/ folder (for service tags and configuration keys) and Resources/config/ (for the default service definitions). That tells you the actual extension surface more reliably than the README.

First use case: register a small service that hooks into init and registers a custom REST route, then hit it from your Laravel app via Http::get(...). This validates the whole stack — WP loaded, container wired, routing works — before you commit to a larger port.

Implementation Patterns

Hooks as services (DI-first WP): instead of add_action('init', 'my_function') sprinkled across functions.php, register a service and tag it for a given hook. The bundle's compiler passes assemble these into real WP callbacks at boot. This mirrors how you'd use Laravel's event/subscriber pattern — the mental model is nearly identical.

Console commands as your "artisan". A huge selling point over vanilla WP. Custom commands for migrations, data imports, cache clears, and one-off jobs run through the Symfony console binary instead of wp eval-file. If you're used to php artisan, budget time to re-learn the argument/option DSL — it's close but not identical.

Twig/Timber-style views. The bundle swaps PHP templates for Twig, often via Timber. Controllers become plain services injected into the theme layer. If your team already writes Blade, the Twig syntax will be familiar enough to move fast; keep a small shim for WP functions (wp_head, the_post, get_permalink) so template authors don't need to know the bridge.

Headless pattern (recommended for Laravel devs): stand up a light Symfony+WP app exposing REST or GraphQL endpoints, then consume them from Laravel with your normal HTTP client, Sanctum-authenticated where appropriate. You get WordPress's editor and plugin ecosystem for content authoring, Laravel for everything else, and a very clean boundary.

Doctrine for custom tables. Rather than $wpdb->prepare scattered around, define entities mapped to plugin-owned wp_* tables. Read-only access to core tables is possible but fragile — prefer a separate schema prefixed to avoid migrations clashing with WP core upgrades.

Compiler passes for plugin integration. If you register a service per WP plugin, use a compiler pass to only load ones whose plugin is active. This keeps cold boot times sane.

Gotchas and Tips

• Framework mismatch is the #1 pitfall. No Eloquent, no config('...') helper, no Artisan. Every use Illuminate\Support\Facades\... in your head needs a Symfony equivalent ($this->getParameter, EventDispatcherInterface, console commands). Don't half-migrate; commit to Symfony idioms inside the WP app.
• Boot order matters. The kernel must boot after plugins_loaded but before template rendering. Booting too early means add_action registrations silently no-op; too late and controllers can't find taxonomies. If hooks "just don't fire," confirm wp-load.php is being included from the right directory — WP's ABSPATH constant must be correct.
• Autoloading collisions. WP plugin code is often not PSR-4 and sometimes ships its own Composer autoloader. Set exclude-from-classmap and files autoload entries carefully; a duplicate autoloader will cause "class not found" errors that only appear in prod after composer dump-autoload --optimize.
• Cache warmup in WP context fails quietly. bin/console cache:warmup outside WP works, but services that depend on WP functions will error. Use --no-warmup in CI, or mark WP-dependent services lazy.
• Twig/WordPress function bridging. Without a Twig extension, {{ get_the_title() }} won't work. Either add twig/extra-bundle helpers or write thin Twig functions. Budget an afternoon.
• Debugging. Use the Symfony profiler in a dev WP environment, but disable it in wp-config.php's production branch — the profiler will leak through REST responses otherwise. Keep WP_DEBUG and APP_DEBUG independent; conflating them causes surprising 500s on the WP side.
• Extension points to remember: tagged services (per-hook), compiler passes (conditional plugin loading), Twig extensions (WP helpers), EventSubscriber (for lifecycle), and configuration via config/packages/sword.yaml. If you're missing a hook point in the bundle's docs, grep -r "add_action" vendor/phpsword/ will usually reveal the injection seam.
• Version note: last release was May 2024, so pin exact minor versions and check Symfony compatibility before upgrading a major. The package has modest stars (≈138), so treat upstream as reference rather than guaranteed support — be prepared to vendor a fork if a critical fix is needed.
• If your real goal is "Laravel + WordPress," look at corcel/corcel (Eloquent-backed WP models) or treat WP as a headless CMS. sword-bundle will be more friction than value unless you're specifically running a Symfony app that embeds WordPress.