Profiles Api Laravel Package

Getting Started

Because this package is a presentation adapter, treat it as the HTTP skin over a profiles domain module — it almost certainly does not contain the entities, repositories, or migrations itself. Your first job is confirming what it depends on.

1. Install and inspect the dependency graph before writing code.

   composer require liberusoftware/profiles-api
   composer show liberusoftware/profiles-api
   

   Read require in the installed composer.json. You will likely see a sibling package such as liberusoftware/module-profiles (or an equivalent domain/application package). If that is not installed, the adapter will boot but fail at container resolution time. Install the domain package first.

2. Find the service provider. Look in vendor/liberusoftware/profiles-api/src/Providers/. Laravel auto-discovery should register it, but confirm with:

   php artisan about
   php artisan route:list --path=api
   

   The route list is the fastest way to learn the surface area of the adapter — it tells you the URI prefixes, controller classes, middleware, and route names in one shot.

3. Read these files in order:

   • routes/api.php (or routes/*.php) — the actual API contract.
   • src/Http/Controllers/ — how thin the controllers are and what they delegate to.
   • src/Http/Resources/ or src/Http/Responses/ — output shape and field names.
   • config/profiles-api.php (if present) — route prefix, middleware, pagination defaults.
   • src/Providers/*ServiceProvider.php — what interfaces are bound and what is publishable.

4. Publish anything publishable.

   php artisan vendor:publish --provider="LiberuSoftware\ProfilesApi\ProfilesApiServiceProvider"
   

   Check --tag options; adapters commonly publish config and sometimes route files so you can override middleware.

5. First use case: authenticate a request and call the profile read endpoint end-to-end. Use php artisan tinker or a seeded user, hit GET /api/profiles/{id} (verify exact path from route:list), and confirm the JSON envelope. That single request validates routes, middleware, the domain binding, and the resource transformer all at once. Do this before building anything on top.

Implementation Patterns

Keep controllers thin; put behavior in the domain layer. The adapter's controllers should be pure transport. If you need new business rules (e.g., "profiles can only be archived by their owner"), implement them in the domain/application package and let the adapter call them. Adding logic to the adapter controllers creates a second source of truth that will drift.

Override resources rather than editing vendor files. For response shape changes (adding a field, renaming a key, embedding a relation), extend the package's JsonResource class in your app and rebind or re-register the route. Typical approach:

// app/Http/Resources/ProfileResource.php
class ProfileResource extends \LiberuSoftware\ProfilesApi\Http\Resources\ProfileResource
{
    public function toArray($request): array
    {
        return array_merge(parent::toArray($request), [
            'avatar_url' => $this->avatarUrl(),
        ]);
    }
}

Then either bind it in a service provider if the package resolves resources from the container, or take over the route entirely.

Take over routes consciously. If the package's routes are registered from its provider, you have three options: (a) disable them via config and re-declare your own in routes/api.php, (b) register your routes after the package's under a different prefix/version, or (c) leave them alone and layer middleware. Option (a) is cleanest for anything beyond trivial customization, but it means you now own the contract — document that.

Version your surface area. If the adapter doesn't already prefix with v1, add it at the route group level. Presentation adapters are the most likely thing to change shape, and consumers need a stable prefix.

Composition with other modules. In a modular Liberu-style app, profiles will be referenced by accounts, teams, or auth. Pass IDs/DTOs across boundaries rather than Eloquent models. If the adapter exposes a profile lookup, other modules should consume it through the domain service, not by hitting the API internally — avoid HTTP calls to yourself.

Middleware placement matters. Auth (auth:sanctum), throttling, and authorization policies belong on the route group. Check what the package registers by default; it is common for presentation adapters to ship with minimal middleware and expect the host app to add auth.

Testing pattern. Use HTTP feature tests against the routes rather than unit-testing controllers:

public function test_profile_show_returns_expected_shape(): void
{
    $user = User::factory()->create();
    $profile = Profile::factory()->for($user)->create();

    $this->actingAs($user)
        ->getJson("/api/profiles/{$profile->id}")
        ->assertOk()
        ->assertJsonStructure(['data' => ['id', 'name', /* ... */]]);
}

Use RefreshDatabase and seed through the domain package's factories, not raw inserts.

Config-driven toggling. If a profiles-api.php config exists, use it to disable endpoints you don't need rather than deleting routes — this keeps upgrades sane.

Gotchas and Tips

• License is NOASSERTION. This is the single biggest risk. Before production use, verify the actual license terms in the repository (LICENSE file, composer.json license field, or contact the maintainer). Absent a clear license, you do not have unambiguous rights to use it commercially.
• Zero stars, zero dependents, no adopters. There is no community to lean on for answers. Pin the exact version in composer.json ("liberusoftware/profiles-api": "1.2.3"), not a caret range. Consider forking or vendoring if you depend on it seriously.
• Future-dated release. The reported last release (2026-10-26) is ahead of the present. Verify the tags actually exist and that the installed package matches what you think you installed:

  composer show liberusoftware/profiles-api --all
  

  Mismatched or untagged releases are a sign of an unstable release process.
• Presentation-only trap. The most common first error is a container binding failure for a repository or service interface because the domain module isn't installed or isn't registered. The stack trace will point at the adapter's controller constructor — read the constructor's type-hints to discover the missing dependency.
• Route collisions. If you already have api/profiles/* routes, the package's registration order determines which wins. Check php artisan route:list --path=profiles for duplicates and resolve by disabling one side.
• Auto-discovery can be silently disabled. If dont-discover is set in your root composer.json, or you're on an older Laravel, the provider won't register and routes will 404 with no error. Register it manually in bootstrap/providers.php / config/app.php.
• Route caching. If the package defines routes with closures (some adapters do for health checks or OPTIONS handlers), php artisan route:cache will fail in production. Test route:cache and route:clear as part of your deploy pipeline, not just locally.
• No OpenAPI spec is guaranteed. With no dependents, assume no generated docs. Generate your own contract from the resource classes or write an OpenAPI file — future maintainers will need it.
• Debugging flow: route:list → check middleware on the failing route → check provider registration in php artisan about → check container bindings with php artisan tinker resolving the controller's dependencies directly → check the domain layer is migrated and seeded. This sequence finds 90% of issues.
• Extension points to prefer: container bindings in your own provider, config overrides, and subclassing resources/controllers — in that order. Avoid editing anything under vendor/.
• Upgrade discipline. Because the package is a thin adapter over a domain module, breaking changes often arrive via the domain package, not this one. Watch both. Run the adapter's feature tests after any domain bump.

If you find yourself fighting the adapter's opinions for more than a day, it is usually cheaper to write the handful of controllers yourself against a stable domain module than to keep bending a zero-adoption package — the adapter's surface area is small by design.