README

Small, reusable conventions for building Laravel REST APIs — the framework-level glue that would otherwise be copy-pasted between projects. Extracted from the net-tech portfolio API.

No service provider, no config, no magic: just a handful of classes you reach for directly.

Install

composer require net-code/laravel-kit

What's inside

Usage

use NetCode\Kit\Clock;
use NetCode\Kit\SystemClock;

$this->app->bind(Clock::class, SystemClock::class);

use NetCode\Kit\Http\PaginatedResponse;

return response()->json([
    'data' => $rows,
    ...PaginatedResponse::meta($request, $page, $perPage, $total),
]);

use NetCode\Kit\Validation\CountryCode;

$request->validate(['country' => ['required', new CountryCode]]);

Scramble (optional)

If you use Scramble for OpenAPI generation, the NetCode\Kit\Scramble\* operation transformers are available (install dedoc/scramble, and spatie/laravel-data for the query-parameter bridge):

TagByNamespace is convention-first (no annotation needed), with #[ApiTag] as a per-controller override. The resolver receives the split namespace and returns the tag — here, audience-first (Admin / Billing, Client / Projects), falling back to the context name when a controller has no audience subfolder:

use Dedoc\Scramble\Scramble;
use NetCode\Kit\Scramble\DocumentDataQueryParameters;
use NetCode\Kit\Scramble\DocumentErrorResponses;
use NetCode\Kit\Scramble\TagByNamespace;

Scramble::configure()->withOperationTransformers([
    new TagByNamespace('Contexts\\', static function (array $segments): ?string {
        $context = $segments[1] ?? null;

        if ($context === null) {
            return null;
        }

        $at = array_search('Controllers', $segments, true);
        $audience = is_int($at) && isset($segments[$at + 2]) ? $segments[$at + 1] : null;

        return $audience === null ? $context : $audience.' / '.$context;
    }),
    new DocumentErrorResponses(namespacePrefix: 'Contexts\\'),
    $this->app->make(DocumentDataQueryParameters::class),
]);

Any controller can opt out of the convention: #[ApiTag('Reports')] forces its group.

License

MIT