Registry Bridge Laravel Package

Getting Started

This package bridges a Laravel app to the Fleetbase registry: it exposes the registry HTTP endpoints (~registry/v1/engines, registry-extensions, installed, purchased, categories) and ships the front-end pieces (ExtensionCard, console engine) that render them.

1. Install and publish config.

   composer require fleetbase/registry-bridge
   php artisan vendor:publish --provider="Fleetbase\RegistryBridge\RegistryBridgeServiceProvider"
   

2. Check where the first thing to look is: the published config/registry-bridge.php (or equivalent). Confirm three values before writing any code:
   • the registry base URI / API host
   • the credentials or API key used to authenticate against the registry
   • which database connection the registry models use (this is the crux of v0.1.11 — see Gotchas)
3. Verify the routes are registered. The package mounts the registry endpoints under a prefix (~registry/v1/...). Run php artisan route:list | grep registry and confirm engines, registry-extensions, installed, purchased, and categories appear. If they don't, the service provider isn't auto-discovered, or the routes are gated behind a config flag.
4. First use case: list installed extensions for the current tenant. Hit GET /~registry/v1/installed (or call the corresponding facade/repository) from a tinker session with an authenticated user. This exercises auth → registry lookup → model hydration in one shot and surfaces misconfiguration immediately.
5. Run the test suite with the console engine enabled. v0.1.11 specifically fixes console test mode, so if you're on ≤ v0.1.10 and your tests boot the console, expect 500s from the registry endpoints before upgrading.

Implementation Patterns

Keep registry data behind your own controller/service. Don't let the Vue/Ember components call the ~registry/v1 endpoints directly from the browser. Proxy through an app controller (or the package's controller) so you can add caching, authorization, and tenant scoping. The registry is an external system and its latency will show up in your page loads otherwise.

Cache the read-heavy, slow-changing endpoints. categories and registry-extensions are near-static; installed and purchased change per-tenant. Use Cache::remember() with a short TTL for the former and tag/forget on install or purchase events for the latter:

$categories = Cache::remember('registry:categories', now()->addDay(), fn () =>
    $registry->categories()
);

Treat installed and purchased as two different states. purchased means the tenant owns it; installed means it's active in their fleet. UIs almost always need the union with flags, not two independent lists — build that merge in one place (a resource class or view model) rather than in each component.

Front-end integration: always pass @resource. The v0.1.11 fix confirms the contract — every card component expects the full registry resource object, not a stripped extension. If you render ExtensionCard in your own Blade templates or pass props from a Livewire/Inertia page, pass the entire resource payload:

<ExtensionCard :resource="$extension" />

Passing a flattened model will silently render blank cards rather than erroring — see Gotchas.

Console test mode is now safe, but isolate it anyway. Since v0.1.11 pins registry models to the live connection, you can boot the console engine inside tests. Still, prefer HTTP fakes or a boundary interface (a RegistryClient contract bound to a fake) over hitting the live registry from CI. Add a registry: fake mode to your test bootstrap and assert against fixtures for installed/purchased.

Upgrade workflow. v0.1.11 has no migrations or commands. The work is in npm, not PHP: the console engine now depends on fleetbase/ember-ui ^0.4.6 and fleetbase/ember-core ^0.3.26. Run composer update fleetbase/registry-bridge and then rebuild your assets (npm install && npm run build). Pin those two front-end packages in package.json so a fresh install doesn't resolve to an incompatible minor.

Gotchas and Tips

The connection split is the big one. If your app uses a sandbox/multi-tenant database and you're on ≤ v0.1.10, the registry endpoints query your tenant connection where registry tables don't exist, producing 500s. After v0.1.11 the registry models and category queries are pinned to the live connection. Two consequences:

• Your live connection must be defined in config/database.php in every environment, including tests.
• Don't add a $connection override to any registry model you extend — you'll reintroduce the bug. Let the package's base model decide, and if you must override, set it to live explicitly.

Blank cards are a silent failure mode. ExtensionCard reads @resource; if the prop is named anything else (@extension, @item) the component renders an empty shell — no name, icon, price, or date — with no console error. If a purchased extension page looks empty but the API returns data, inspect the prop name in the parent component first. This is fixed in v0.1.11 for the Purchased page; if you've copied the purchased page markup into your own app, check it too. The same release fixed descriptions failing to render on all cards, so if descriptions were missing app-wide before, that was the cause, not your templates.

Debugging registry 500s. Reproduce with php artisan tinker and log the SQL connection actually used: DB::connection()->getName() inside the failing path. Compare against config('database.default'). If they differ from live, you're on the pre-fix behavior.

Extension points. Favor overriding the package's config and binding your own implementation of whatever registry client/repository contract it exposes, rather than editing published views in resources/views/vendor/.... Vendor-published views are overwritten only if you re-publish, but the compiled front-end components are not — keep customizations in your own components that wrap ExtensionCard rather than forking it.

Config quirks to watch. Cache the config (php artisan config:cache) after changing registry credentials; Laravel will keep serving the old values in production and you'll chase phantom auth errors. Similarly, route:cache retains the registry route prefix — changing the prefix at runtime requires a re-cache.

Version-skew risk on the front end. The PHP package and the ember-ui/ember-core versions move in lockstep. If you see runtime template errors after a composer update but no PHP exceptions, check your node_modules versions resolve to at least ember-ui 0.4.6 and ember-core 0.3.26. Clear the build cache (rm -rf node_modules/.cache public/js) before assuming a code bug.