Application Api Laravel Package

Getting Started

This is an unreleased-grade package: zero stars, zero dependents, and a NOASSERTION license. Treat the first hour as reconnaissance, not integration.

1. Confirm installability before committing. This package is one node in the Liberu module graph and will almost certainly hard-require liberusoftware/application-core (or similarly named siblings) at a pinned version. Check the constraint graph first:

   composer require liberusoftware/application-api --dry-run
   composer show liberusoftware/application-api
   

   If the dry run drags in a half-dozen sibling modules you did not plan for, stop and evaluate the whole graph, not just this package.

2. Read the service provider before you read anything else. With no README worth trusting, src/Providers/*.php is the actual documentation. It tells you what routes get registered, what config gets merged, what bindings are aliased, and whether anything is publishable:

   ls vendor/liberusoftware/application-api
   cat vendor/liberusoftware/application-api/composer.json
   find vendor/liberusoftware/application-api/src -name '*Provider*.php' -exec sed -n '1,120p' {} \;
   

3. Let auto-discovery do its job, then verify. Laravel package discovery should pick up the provider. Confirm with php artisan about and then enumerate what actually landed:

   php artisan route:list --path=api -v
   php artisan vendor:publish --provider="Liberu\ApplicationApi\...ServiceProvider"
   

4. First use case: a read-only smoke test. Before wiring any write paths, prove the adapter resolves the core domain correctly. Hit a single index/show endpoint, confirm the JSON shape matches the core's aggregate, and confirm auth middleware is actually applied (many presentation adapters ship routes without the guard you assume). One authenticated GET returning a correctly-shaped resource is your green light for everything else.

The mental model: this package is a thin HTTP skin over application-core. Your job is not to learn this package's API surface — it's to learn the core's and then confirm the adapter maps it faithfully.

Implementation Patterns

Pattern 1 — Consume the routes, don't rewrite them. The adapter's value is that endpoint contracts already exist. Resist the urge to duplicate controllers in app/Http/Controllers; you'll fork the contract and lose upgrades. Customise through the extension points the provider exposes (route groups, middleware config, resource bindings) rather than by copying files.

Pattern 2 — Bind the core, let the adapter follow. Configure the core package's repository/service bindings in a dedicated provider. The API adapter resolves whatever the core container gives it, so environment-specific behaviour (tenant scoping, cache driver, repository implementation) belongs in the core config — not in the adapter's config.

Pattern 3 — Middleware is the primary integration seam. Typical:

// config/application-api.php (name per the provider's mergeConfigFrom call)
return [
    'middleware' => ['api', 'auth:sanctum', 'throttle:api'],
    'prefix'     => 'api/v1',
];

Pin the prefix explicitly. Presentation adapters frequently default to api/ with no version, and adding versioning later is a breaking change for every client.

Pattern 4 — DTO/Resource shaping via with() and resource subclasses. If the adapter ships JsonResource classes, extend them rather than returning raw models. Add computed fields and relationship includes in the subclass, keep the base class for the canonical shape.

Pattern 5 — Feature-test the contract, not the internals. You don't control this package's tests, and it likely has none that are meaningful. Write your own:

public function test_application_index_requires_auth(): void
{
    $this->getJson('/api/v1/applications')->assertUnauthorized();
}

These tests are your regression net when you bump the package — which, given the release cadence and bus factor, is the most likely thing to break you.

Pattern 6 — Wrap it behind your own route file when clients depend on stability. If external consumers integrate, register your own route group and point it at the package's controllers via Route::apiResource(...)->only([...]) with explicit names. That gives you a seam to swap the implementation later without touching client code.

Gotchas and Tips

• NOASSERTION license is a procurement problem, not a style nit. Before this touches anything commercial, get a human to read LICENSE in the repo. GitHub's classifier failing to match a known license usually means a custom or malformed file — sometimes permissive, sometimes not. Do not assume MIT because the rest of the ecosystem is.

• Zero dependents + zero stars + a future-dated release (2026-10-26) is a red flag worth naming. A release date ahead of the current date suggests automated/manual versioning that isn't tracking reality. Pin the exact version in composer.json ("liberusoftware/application-api": "1.2.3", not ^1.2) and commit composer.lock. Never composer update this package casually.

• Route-name collisions. Modular packages love generic names like applications.index. If you run other modules, route:list will show the collision immediately — check before assuming route('applications.index') resolves to the package. Namespace your own routes.

• mergeConfigFrom shallow-merges. If the provider merges config, nested arrays (e.g. middleware) may be replaced wholesale rather than per-key. Publish the config file and edit it directly rather than relying on partial overrides in config/.

• Auto-discovery can silently not fire. If dont-discover is set in your root composer.json, or the provider isn't in the package's extra.laravel.providers, you'll get 404s with no error. Register manually and move on.

• Debug with route:list -v and tinker, not with the source. Because documentation is effectively absent, the fastest path to understanding a binding is:

  php artisan tinker
  >>> app(\Liberu\ApplicationApi\Contracts\...::class);
  

  If the container resolves it, you know the binding exists and what concrete class backs it. That's more reliable than reading provider code that may be conditionally registered.

• Extension points to check for, in order of preference: (1) published config, (2) container bindings you can override in AppServiceProvider::register(), (3) middleware you can append, (4) resource/controller subclassing, (5) forking. Forking is a last resort here — you'll own the maintenance, and given the project's activity level, you may end up owning it anyway. Budget for that possibility before you build on it.

• Check the Laravel/illuminate version constraint in composer.json against your app. A zero-star package with a 2026 release may target Laravel 12+ only. Installing on an L10/L11 app will either fail loudly (good) or resolve against a stale branch with subtly different behaviour (bad).

• Verdict for day-to-day use: treat it as an internal-style adapter you are adopting, not a dependency you are consuming. Read the provider, pin it hard, test the contract yourself, and keep a thin seam so replacement is cheap.