Download the PHP package ozankurt/laravel-modules-core without Composer

laravel-modules-core

Shared bootstrap kit for KurtModules Laravel packages.

Requirements

• PHP ^8.4
• Laravel ^13.0
• (Optional) Filament 3, 4, or 5

Installation

What it provides

• Kurt\Modules\Core\Providers\PackageServiceProvider — abstract base every kurtmodules service provider extends. Wraps spatie/laravel-package-tools and dispatches to registerFilamentV{3,4,5} based on the installed Filament major.
• Kurt\Modules\Core\Contracts\UserResolver (+ ConfigUserResolver) — resolves the consumer's user model via kurtmodules.user_model config or auth.providers.users.model fallback.
• Kurt\Modules\Core\Concerns\ResolvesUser — trait that gives module models a userBelongsTo() helper.
• Kurt\Modules\Core\Concerns\InteractsWithModuleConfig — sugar for config("{module}.key") access.
• Kurt\Modules\Core\Concerns\AbortsInProduction — trait for Artisan commands; abortIfProduction() blocks demo/destructive commands in production unless --force is passed. Lets *:demo commands drop their hand-rolled guards.
• Kurt\Modules\Core\Concerns\HasEnumLabels — trait giving string-backed enums a Title-Case getLabel() and a null getColor() default, so downstream enums can satisfy Filament's HasLabel/HasColor without Core requiring Filament.
• Kurt\Modules\Core\Support\FilamentVersion — ::major(), ::isAtLeast(), ::isExactly().
• Kurt\Modules\Core\Enums\{Approval,MediaKind,Visibility} — generic cross-module enums.
• Kurt\Modules\Core\Testing\PackageTestCase — Testbench-backed base test case with an in-memory users table.
• API kit — Http\HttpMode, Http\ApiRouteGroup, Http\Controllers\ApiController, Http\Concerns\HandlesApiQuery, Support\ApiRateLimiter, plus the PackageServiceProvider::registerModuleApi() hook. The config-convention-driven REST foundation every module inherits (see API kit).

Configuration

Publish the config file:

Command & enum helpers

Guard demo/destructive Artisan commands so they cannot run in production without --force:

Give a string-backed enum Filament-ready labels/colors without Core depending on Filament (the enum declares the contracts, the trait supplies the bodies):

API kit

A config-convention-driven foundation for a module's out-of-the-box REST API. It generalises the loyalty.http.mode pattern so every module exposes a JSON API the same way, safe-by-default: nothing is registered until a consumer opts in, and write routes require auth + a Policy.

Config convention

Every consuming module reads these per-module keys (module slug = the value returned by the provider's module()):

Every group is throttled by a named limiter {slug}-api (keyed by user id, or client IP for guests). A module's config/{slug}.php therefore ships:

Base classes

• Http\HttpMode — HttpMode::forModule($slug) resolves {slug}.http.mode (unknown → Headless); ->apiEnabled(), ->is(...).
• Http\ApiRouteGroup — ApiRouteGroup::attributes($slug, $authenticated = false) returns the Route::group() array (prefix, merged middleware + throttle [+ auth_middleware when $authenticated], as = "{slug}.api.").
• Http\Controllers\ApiController — abstract base (adds AuthorizesRequests, ValidatesRequests) with a consistent envelope:
  • respond($data, array $meta = [], int $status = 200) → { "data": …, "meta": … } (meta omitted when empty).
  • respondCreated($data) (201), respondNoContent() (204, empty body).
  • respondPaginated(LengthAwarePaginator $p, ?string $resourceClass = null) → items as data (mapped through the resource class when given) + meta.pagination (current_page, per_page, total, last_page).
  • fail(string $message, int $status = 422, array $errors = []) → { "message": …, "errors": … }.
• Http\Concerns\HandlesApiQuery — allow-list-driven query helpers (never interpolate raw input as SQL identifiers):
  • applyApiSorts($q, $r, array $allowed) — ?sort=field,-other (leading - = desc); non-allowed fields dropped.
  • applyApiFilters($q, $r, array $allowed) — ?filter[field]=value; $allowed is a list of exact fields (['name']) or a mode map (['name' => 'like', 'status' => 'exact']). like → %value%.
  • apiPaginate($q, $r, int $default = 15, int $max = 100) — ?per_page= clamped to [1, $max], standard ?page=.
• Support\ApiRateLimiter — ApiRateLimiter::register($slug) registers the {slug}-api limiter from {slug}.http.rate_limit.

Resources vs envelope helpers

The envelope's top-level key is data, matching Laravel API Resources. Use Laravel resources directly (Core ships no resource base) and hand the result of a resource to the envelope helpers so the payload is wrapped exactly once:

Do not return a bare JsonResource from a route and also call respond() — that double-wraps as {"data":{"data":…}}.

How a module exposes an API

1. Config — add the http block above to config/{slug}.php; keep mode defaulting to headless.
2. Resources — define App-style JsonResource classes for your models.
3. Controller — extend ApiController; keep controllers thin over domain services. use HandlesApiQuery on index controllers for sort/filter/paginate. Enforce a Policy on every write ($this->authorize(...)).

4. Routes — routes/api.php, read vs write split via ApiRouteGroup::attributes():

5. Provider — wire it in packageBooted(); it is a no-op in headless mode and registers the rate limiter + route group otherwise:

The outer group (prefix, base middleware, throttle, "{slug}.api." name prefix) is applied by registerModuleApi(); the route file only distinguishes read vs write.

Testing

CI runs the same checks on every push and pull request (.github/workflows/tests.yml), against PHP 8.4 / Laravel 13. Static analysis is held at PHPStan level 8; the suite runs on Pest 5.

License

MIT © Ozan Kurt