Settings Api Laravel Package

Getting Started

liberusoftware/settings-api is not a standalone settings engine — it's a presentation adapter. In the Liberu module architecture, a domain module (module-settings) owns the model, migrations, repository and caching, while separate adapter packages expose that domain over different surfaces (-api, -web, -filament, -livewire). This package is the HTTP/JSON surface for settings, so almost every question you have about behaviour is answered by the domain module, and almost every question about routing, validation and response shape is answered here.

Minimal setup:

composer require liberusoftware/settings-api

Then, before writing a line of code:

1. composer.json — read the require block first. It tells you which domain package version this adapter was built against (liberusoftware/module-settings or similar) and whether it pulls in a service-provider host. Pin the adapter and the domain module to compatible constraints; with a 0-star package, floating constraints are how you get a broken Monday.
2. The service provider(s) in src/Providers — this is where route registration, middleware stack, route prefix and config merging happen. If routes aren't appearing, this file is why.
3. routes/ — the actual endpoint surface. php artisan route:list --path=api after install gives you the truth faster than the README.
4. config/ — publish it (php artisan vendor:publish --tag=...) and read the defaults: prefix, middleware, pagination, serialization.
5. Migrations — expect them to live in the domain module, not here. If settings tables are missing, you installed the adapter without the engine.

First use case: a read-through smoke test. Authenticate however the package's middleware demands (Sanctum is the usual choice in this ecosystem), then:

curl -H "Accept: application/json" -H "Authorization: Bearer $TOKEN" \
  https://app.test/api/settings

Then write one key and read it back. That two-minute loop exercises routing, auth middleware, validation, the domain repository and cache invalidation all at once — it's the fastest way to find out which of those is broken.

In application code, do not call the API. Resolve the domain service/repository from the container and read settings in-process; the HTTP adapter exists for external clients, SPAs and mobile apps.

Implementation Patterns

Treat the adapter as transport, not logic. Any setting your own code needs should be fetched through the domain contract, not by an internal HTTP call or by reading the settings table directly. Direct table reads bypass the cache and any normalisation the domain module performs.

Grouped/namespaced keys. Settings packages in this family almost always organise keys by group or namespace. Design your payloads and your front-end fetch strategy around that: one call per group beats one call per key, and a single "public config" endpoint beats fifteen.

A public config endpoint is the highest-value pattern. Expose only whitelisted, non-sensitive keys — feature flags, locale list, currency, theme tokens, support email — and let the SPA hydrate from it on boot:

// app/Http/Controllers/BootConfigController.php
public function __invoke(SettingsService $settings): array
{
    return [
        'features' => $settings->group('features'),
        'locale'   => $settings->get('app.locale'),
        'currency' => $settings->get('billing.currency'),
    ];
}

Keep this controller in your app, not in the package, so you control the whitelist.

Authorization is your job. Adapter packages typically ship a middleware slot, not a policy. Settings almost always split into read-public / read-admin / write-admin. Put a can:viewAny,Setting or a role middleware on the write routes explicitly; don't assume the vendor did.

Cache, then invalidate deliberately. Settings are read on nearly every request. Wrap the domain repository in a cache decorator or rely on the domain module's cache, and make sure writes invalidate. If you add your own Cache::remember, add your own Cache::forget in a model observer — the package cannot invalidate a cache it doesn't know about.

Multi-tenancy scoping. If the app is multi-tenant, decide early whether settings are global or per-tenant. The adapter's routes are likely global by default; tenant-scoped settings usually need either a route parameter, a tenant-aware middleware that sets context before the controller resolves, or a separate set of routes entirely. Doing this late is a rewrite.

Consume it from tests the way clients do. Use RefreshDatabase plus a seeded settings set, and assert on the JSON envelope rather than the raw model:

it('exposes public settings', function () {
    $this->getJson('/api/settings/group/features')
        ->assertOk()
        ->assertJsonPath('data.checkout_v2', false);
});

Version the contract immediately. Even at v1, mount the routes under /api/v1/... if the package allows a prefix override. A settings payload shape that leaks into a shipped mobile app is permanent.

Extension points to prefer over forks: binding your own implementation to the domain contract in a service provider, overriding published config (prefix, middleware), and decorating the repository. Forking a 0-star adapter means you own maintenance forever.

Gotchas and Tips

Zero stars, zero dependents is the headline risk. There is no community validation here: no third-party issues to read, no downstream projects proving the happy path. Budget an hour to read src/ end to end before it touches a production dependency tree. It's a small package — this is feasible and worth it.

License is NOASSERTION. That means the repository's LICENSE file didn't match a recognised SPDX identifier — not that it's unlicensed, but that a human must read it. Get legal sign-off before shipping commercially. This alone blocks adoption in many orgs.

The release metadata says 2026-10-26. Treat the versioning as untrustworthy until you've checked tags against commits. Pin exact versions ("liberusoftware/settings-api": "1.2.3") and commit composer.lock. Avoid dev-main in anything that matters.

Migrations live elsewhere. If php artisan migrate produces no settings tables, you've installed the adapter without the domain module, or the domain module's provider isn't registered. Check bootstrap/providers.php (Laravel 11+) as well as config/app.php.

Routes missing after install. Run php artisan route:list --path=api | grep -i setting. If nothing shows: the provider isn't auto-discovered (check composer.json extra.laravel.providers), or the package expects you to register it manually, or routes are gated behind a config flag that defaults to false.

Route caching + closures. If the package registers routes with closures, php artisan route:cache will fail or silently skip. This bites in CI-deployed production builds, never locally.

Config caching order. After publishing or editing the config, run php artisan config:clear before config:cache. A stale cached config with the wrong prefix is the single most common "the package is broken" report.

Type coercion. Settings stored as strings come back as strings. "0", "false" and "" are all truthy in PHP's loose comparison. Normalise at the boundary — a small value-object or cast layer in your app — rather than sprinkling filter_var(..., FILTER_VALIDATE_BOOLEAN) through views.

Response envelopes differ from your app's convention. Adapter packages often return {data: ...} or a custom {status, message, data} shape that won't match the rest of your API. Either accept the inconsistency and document it, or wrap it with a response macro. Don't silently reshape it per-endpoint.

Debugging checklist, in order: route:list → middleware stack on the route (php artisan route:list -v) → whether the controller resolves the domain contract → whether the domain repository returns anything (tinker) → cache. That ordering resolves ~90% of issues with this class of package.

Watch for hidden coupling to the Liberu host application. Packages in this ecosystem sometimes assume a specific application skeleton, panel provider or auth guard. If the service provider references classes you don't have, you'll get a BindingResolutionException at boot — a strong signal the adapter is designed for the Liberu starter kit rather than a generic Laravel app.

Have an exit plan. Because the surface is thin, replacing it is cheap: keep your own controllers thin, depend on the domain contract rather than adapter classes, and you can swap the adapter for three hand-written routes in an afternoon. That optionality is the right posture for a package with this score.