Identity Core Api Laravel Package

Getting Started

liberusoftware/identity-core-api is a presentation adapter, not an auth solution. It sits at the HTTP edge of a modular Liberu stack and translates requests into calls against an identity core domain package (likely liberusoftware/identity-core or a sibling module). That distinction drives everything below: you own the host app, the core owns the rules, and this package owns the routing/serialization boundary.

Minimal setup:

1. composer require liberusoftware/identity-core-api — then immediately read the installed composer.json. The require block tells you which core package and which major version it expects; that constraint is the real contract you're adopting.
2. Check for auto-discovery (extra.laravel.providers). If present, the service provider is registered for you; if not, add it to bootstrap/providers.php (Laravel 11+) or config/app.php.
3. Run php artisan vendor:publish --provider="Liberu\...\IdentityCoreApiServiceProvider" and inspect what appears — config, routes, migrations. Publish selectively; don't blanket-publish routes if you intend to wrap them.
4. php artisan route:list --path=identity is your first real look at the surface area. The route table is the most reliable documentation this package has.
5. Confirm the core is actually wired: the adapter is useless if the core's migrations haven't run. php artisan migrate then hit a read endpoint (GET /api/identity/users/{id} or whatever the route list shows) with a seeded record.

First use case: treat it as a read-only consumer before you treat it as a write path. Authenticate a request, fetch a single identity resource, and assert the JSON shape in a feature test. That test becomes your upgrade canary. Only then move to registration/login flows, which drag in guards, tokens, and mail — the parts most likely to be host-app-specific and least likely to be covered by a 0-star package.

Implementation Patterns

Keep the adapter at the edge. Within your own application code, depend on the identity core contracts (interfaces, domain services), not on this package's controllers or HTTP resources. Call the HTTP layer only from actual HTTP clients. If a service class of yours is importing a class from this package's Http\ namespace, you've inverted the dependency and every adapter upgrade becomes a refactor.

Wrap, don't edit. Register the package's route group inside your own with the middleware it needs in your app:

Route::middleware(['api', 'throttle:identity', ResolveTenant::class])
    ->prefix('api/v1')
    ->group(base_path('vendor/liberusoftware/identity-core-api/routes/api.php'));

This gives you tenant resolution, guard selection, and rate limiting without touching vendor code — and survives composer update.

Version by addition. If the package ships v1 routes, don't mutate them. Add a v2 route file pointing at your own thin controllers that delegate to the same core services. You get to reshape the payload without forking.

Override via decoration, not inheritance, where possible. For response shaping, prefer binding your own JsonResource/transformer or extending the container binding with $this->app->extend(...) in a provider registered after the package's. Subclassing package controllers is the last resort — it couples you to their constructor signature and middleware assumptions.

Validation belongs to the adapter; rules belong to the core. Reuse the package's form requests when they exist, but keep business invariants (uniqueness, state transitions, policy checks) in the core. Duplicating an invariant in a FormRequest means two places to fix when it changes.

Test the contract, not the implementation. Feature tests with actingAs($user, 'sanctum') plus assertJsonStructure([...]) will catch breaking payload changes on upgrade far better than asserting exact values. Add one test per endpoint you actually consume, and delete tests for endpoints you don't — you're not the package's maintainer.

Events for cross-module work. If the core dispatches domain events (user registered, email verified), listen to those for onboarding, provisioning, and notifications instead of hooking into controller responses. This keeps your module decoupled from the adapter's lifecycle.

Gotchas and Tips

The license is the first blocker, not a footnote. NOASSERTION almost always means a missing or malformed LICENSE file, not a permissive grant. Read the repository's LICENSE/COPYING directly before this touches anything commercial, and get written clarification from the maintainer. With 0 stars, 0 dependents, and a single publisher, there is no ecosystem pressure keeping the terms stable.

Treat this as vendored-source risk. Zero dependents means zero field testing. Pin an exact version ("liberusoftware/identity-core-api": "1.2.3"), commit composer.lock, and be prepared to fork. Budget for reading the source — it's a small package, and reading it is faster than debugging it.

Upgrade coupling is the real cost. Adapter and core versions move together. Before composer update, diff the adapter's composer.json constraints against what you have installed; a bump here frequently forces a core bump and therefore migrations. Sequence: read changelog → update core → run migrations in staging → update adapter → run your contract tests.

Domain exceptions leak as 500s. Presentation adapters routinely forget to map core exceptions to HTTP codes. Add an exception renderer in your bootstrap/app.php (or Handler) mapping the core's not-found/conflict/validation exceptions to 404/409/422. Test it — an identity API returning 500 for "user not found" breaks every client's retry logic.

Route caching. If the package's route file uses closures, php artisan route:cache fails in production but works locally. Test the cached path in CI; it's a classic deploy-time-only failure.

Config merge vs. publish. mergeConfigFrom only merges the top level shallowly, and a published config file with a slightly different key name silently wins over package defaults. After publishing, php artisan config:show identity-core-api (or config() in tinker) to confirm the effective values rather than the file contents.

Binding order matters. If you override a container binding, your provider must boot after the package's. Auto-discovered providers run in composer.json order — if your override is silently ignored, that's why. Verify with app()->make(TheContract::class)::class in tinker.

Debugging checklist, in order: php artisan about (is the provider loaded?), php artisan route:list --path=identity (are routes registered?), php artisan config:clear && php artisan route:clear (stale cache?), then a dd() in the controller to confirm the request reaches the adapter at all. Nine times out of ten it's a stale cache or a provider that never registered.

Escape hatch. The moment you find yourself patching vendor code, copy the package into packages/ as a path repository. It's small; owning it outright is cheaper than maintaining a patch stack against a package with no release cadence guarantees.