Weave Code
Api Components Bundle Laravel Package
components-web-app/api-components-bundle
A Symfony bundle for building a flexible API around a website's structure, reusable components, and shared functionality. Requires PHP 8.2+ and Symfony 7.4+, with Symfony 8.x-compatible code. Still a work in progress, with full documentation available online.
API Components Bundle is a Symfony bundle that builds a flexible, headless API for your website's structure, reusable components, and shared functionality. It lets you model pages and content as composable API resources, so front ends can consume a consistent, well-typed contract instead of bespoke endpoints.
Built for modern stacks, it requires PHP 8.2+ and Symfony 7.4+ (bundle code is Symfony 8.x-ready), and ships with a thoroughly tested suite covering unit, mutation, and Behat/behavioral tests.
- Composable component API for reusable, structured content
- Configurable website/page structure exposed over HTTP
- Symfony-native bundle integration and service wiring
- Strong quality gates: CI, Codecov, Scrutinizer, and Stryker mutation testing
- Full documentation at docs.api.cwa.rocks
Frequently asked questions about Api Components Bundle
- What does the API Components Bundle actually do?
- It is a Symfony bundle that exposes a flexible API for a website's structure, its reusable components, and shared common functionality, so front ends and services can fetch page/site structure instead of hardcoding it. It also ships operational surfaces such as an HTTP cache purge endpoint and optional cache warming. The package is published as components-web-app/api-components-bundle and requires PHP 8.2+ and Symfony 7.4+.
- Can I use this API Components Bundle in a Laravel application?
- Not as a drop-in Laravel package. It is built on Symfony components (HTTP Kernel, Serializer, Messenger, HTTP Cache) and is registered as a Symfony bundle, so a Laravel integration needs adaptation for routing, dependency wiring, and persistence. The architecture is modular enough to be usable alongside a Laravel app, but expect to write glue code rather than just composer require and go. If you need a native Laravel solution today, Laravel API Resources or Fractal are the safer starting points.
- How do I install the bundle and which PHP and Symfony versions are required?
- Install it with composer require components-web-app/api-components-bundle and register the bundle in your Symfony bundle configuration. The requirements are PHP 8.2 or newer and Symfony 7.4 or newer, and the bundle code is reported compatible with Symfony 8.x even though the test suite is currently capped at Symfony 7.x by Behat dependencies. Because the release line is an alpha, pin the exact version in composer.json instead of using a floating constraint.
- Is version 2.0.0-alpha.25 stable enough for production?
- Treat it as pre-stable. The 2.0.0-alpha.25 release fixed redirectTo() self-route refusals, prune-fixture-assets error reporting, and generate-fixtures per-scaffold asset scoping, which shows active churn in adjacent surfaces and implies breaking changes between alphas. For production use, review the changelog on every bump, pin exact versions, and wrap the bundle behind your own service boundaries. The scaffold and fixture generation tooling is useful for CI and preview environments, but it is another surface you have to operate.
- How does the /_/http_cache/purge endpoint work?
- You send POST /_/http_cache/purge with an optional JSON body containing paths and/or tags arrays. If the body is absent the bundle performs a full flush; any malformed body now returns 422 instead of silently flushing. This is a reverse-proxy and CDN purge contract (Varnish, Fastly, Cloudflare-style), not just an application-level cache clear, so design runbooks around targeted path and tag purges and keep full flush as a last resort.
- Is the HTTP cache purge endpoint protected by authentication?
- The bundle does not document an opinionated authorization model for /_/http_cache/purge, so you must secure it yourself before exposing it. In practice that means restricting it to internal networks, an IP allowlist, or a token-gated route, and never leaving it publicly reachable. Audit the route in your own firewall and routing configuration rather than assuming protection exists.
- Why does cache warming need an async worker or transport?
- The http_cache.warm_after_flush option is off by default, and when enabled it dispatches bounded warm requests for gzip and br encodings after a successful full flush. Those WarmHttpCacheMessages are dispatched on messenger.default_bus, so warming only makes sense if that bus is routed to a real async transport. If the bus points to a sync or void transport, warming will either block the request or silently no-op, which is a subtle failure mode worth monitoring.
- Can I use Laravel queues or Horizon instead of Symfony Messenger for cache warming?
- Not out of the box, because warming is dispatched on messenger.default_bus and there is no native Laravel queue bridge. You either run a Symfony Messenger transport and worker alongside Horizon, or write a small bridge adapter that forwards WarmHttpCacheMessage onto a Laravel queue job. Whichever route you take, verify with a test that a flush actually produces warm requests rather than a silent no-op.
- Does the bundle require Doctrine, or can I use Eloquent?
- The bundle is Symfony-oriented and may assume Doctrine for schema management, so plan for a migration layer if your Laravel app is Eloquent-based. In practice you would implement the component and structure repositories against Eloquent or the query builder and bind them in the container. Validate the persistence assumptions against the docs before committing, since alpha releases may change those contracts.
- What are the alternatives to this bundle for a Laravel API?
- For a plain Laravel API, native API Resources or Fractal transformers cover the resource abstraction without extra infrastructure. If what you actually need is a managed content and component model, headless CMS options or a small in-house structure service are usually cheaper than adapting a Symfony bundle. Choose this bundle only if you want its structure/component API plus the built-in HTTP cache purge and warming contract, and you are comfortable absorbing alpha churn.
Weaver
How can I help you explore Laravel packages today?