Rest Bundle Laravel Package

Getting Started

• Understand what this actually is before composer require. xrow/rest-bundle is a Symfony bundle (package type symfony-bundle), not a Laravel package. It was built as a web-service layer for eZ Publish / eZ Platform (Ibexa) style media/content systems. Laravel's package discovery will not register it, there is no ServiceProvider, no facade, and no config/rest-bundle.php to publish.
• First read: open vendor/xrow/rest-bundle/composer.json after installing (or browse it on GitHub) and note:
  • type and require — expect symfony/framework-bundle, possibly ezsystems/* or Ibexa kernel packages, and a PHP constraint that predates PHP 8.2.
  • autoload PSR-4 namespace, so you know where controllers/services live.
  • Whether extra.laravel exists. It won't. Plan accordingly.
• Second read: the bundle's Resources/config/ (services, routing) and DependencyInjection/Configuration.php. That config tree is the actual public API surface — everything else is implementation detail.
• First use case, in the intended world: a media company exposing a read-only content API (sections → articles → media assets/renditions) to a partner or to a decoupled frontend. That is the shape of endpoint you should expect and the one worth studying.
• First use case for a Laravel team: treat it as a reference implementation, not a dependency. Run it in a throwaway Symfony/Ibexa container to observe real request/response pairs, then reimplement the contracts in Laravel. Do not attempt to mount a Symfony bundle inside a Laravel app.
• Minimum viable decision gate: if you don't already run Symfony or Ibexa, the only sane path is "read the source, copy the contract." If you do run Ibexa, this bundle installs and registers like any Symfony bundle (config/bundles.php) — but then you're doing Symfony work, not Laravel work.

Implementation Patterns

• Pattern A — Consume over HTTP (recommended). Keep Laravel as the client. Wrap the bundle's endpoints in a dedicated client class:

  // app/Services/MediaApiClient.php
  final class MediaApiClient
  {
      public function __construct(private string $baseUrl, private ?string $token = null) {}
  
      public function articles(int $page = 1): array
      {
          return Http::baseUrl($this->baseUrl)
              ->withToken($this->token)
              ->retry(2, 200)
              ->get('/api/articles', ['page' => $page])
              ->throw()
              ->json();
      }
  }
  

  Bind it in a service provider, cache responses with Cache::remember, and test with Http::fake() plus recorded fixtures. This is the only pattern that survives the bundle being abandoned.
• Pattern B — Port the endpoints. Map bundle routes → routes/api.php, controllers → invokable Laravel controllers, the Symfony service container → constructor injection, bundle config parameters → config/media-rest.php, and the content repository calls → Eloquent/query-builder equivalents. Preserve the response envelope, status codes, pagination and error format exactly so existing clients don't notice the swap. Validate the port by replaying captured requests against both implementations and diffing JSON.
• Pattern C — Sidecar. If you genuinely need the bundle's behavior (e.g., it does content-model flattening you can't cheaply reproduce), deploy a small Symfony app exposing only the API, run it as a separate service, and have Laravel proxy or call it internally. Accept two runtimes and two deploy pipelines as the cost.
• Contract-first workflow. Whatever pattern you pick, write down the API contract (paths, auth, pagination params, error body) as OpenAPI or as Laravel feature tests first. The bundle is under-documented, so the source and observed responses are the spec.
• Auth integration. Expect HTTP Basic or a static token rather than OAuth/JWT. In Laravel, terminate the real auth at your edge (Sanctum/Passport) and translate to the bundle's mechanism in the client — never leak the bundle's credentials to browsers.
• Domain mapping. Model the media-company vocabulary explicitly: Section, Article, MediaAsset, Rendition. Use Laravel API Resources (ArticleResource) to normalize the bundle's JSON into your own stable shape, so upstream quirks stay contained in one mapper.
• Migration path. If you start on Pattern A and later port to Pattern B, the client class is the seam: swap its transport for direct service calls without touching callers.

Gotchas and Tips

• Zero Laravel affordances. No auto-discovery, no publishable config, no migrations, no facade. Any tutorial implying otherwise is wrong. Check php artisan package:discover output and don't be surprised when nothing appears.
• Staleness is the headline risk. Last release 2019, zero stars, zero dependents. Expect: PHP 8 deprecations, Symfony APIs that no longer exist, and no upstream fixes. Pin the version, and if you must ship it, fork it into your own org and take ownership — you are now the maintainer.
• Unresolvable DI. The bundle very likely pulls services from an eZ/Ibexa kernel (content service, search service, repository). Outside that runtime you'll get "service not found" / "cannot autowire" errors. That error is your signal to switch from "install" to "port" — don't chase it with stubs.
• Config keys are guesswork until you read Configuration.php. Parameters live under a bundle-specific root key (e.g. xrow_rest:) with YAML/XML service definitions in Resources/config. Copy keys from the bundle's own tests/fixtures rather than inventing them.
• No Laravel-style route caching. Bundle routes are Symfony routing YAML. If proxying, define the proxy routes in routes/api.php yourself; don't try to import Symfony route files.
• Debugging without a working Laravel stack: stand the bundle up in a minimal Symfony app with the Symfony profiler, or log raw Http:: responses (Http::globalMiddleware / ->withOptions(['debug' => true])) and diff against fixtures. Guessing at undocumented payloads is the main time sink.
• Extension points to look for before forking: event listeners/subscribers on controller events, custom normalizers or serialization handlers, and the DI configuration node. These are the intended customization seams; each maps cleanly to Laravel middleware, API Resources, or config in a port.
• Test the boundary, not the package. Since upstream has no test suite you can trust and no maintainers, invest in your own contract tests. They are the only thing that will tell you a response changed.
• Don't build new product features on top of it. Use it as a specification or a temporary sidecar. If it becomes load-bearing, budget for the port now rather than after the next PHP upgrade forces it.