laravel-api-kit

composer require devespresso/laravel-api-kit

php artisan vendor:publish --provider="Devespresso\LaravelApiKit\LaravelApiKitServiceProvider"

php artisan devespresso:api-kit:scaffold Post

# Only specific components
php artisan devespresso:api-kit:scaffold Post --only=model,repository,transformer

# Skip specific components
php artisan devespresso:api-kit:scaffold Post --except=model

# Overwrite existing files
php artisan devespresso:api-kit:scaffold Post --force

return [

    // false = simplePaginate()  |  true = paginate() (includes total count)
    'pagination' => ['with_pages' => false],

    // Auto SELECT only transformer-required columns — prevents SELECT *
    'auto_select'     => true,

    // Auto eager-load nested relations defined in the transformer — prevents N+1
    'auto_eager_load' => true,

    // When true, only explicitly whitelisted request keys drive filter methods
    'enable_explicit_filtering' => false,

    // Invokable class returning the current user's role — must be cacheable
    'role_resolver'  => App\Support\RoleResolver::class,
    'roles'          => ['moderator', 'editor', 'admin'], // ordered lowest → highest
    'numeric_roles'  => false,

    // Namespaces — scaffold places files here, auto-resolution reads from here
    'paths' => [
        'models'          => 'App\\Models\\',
        'transformers'    => 'App\\Transformers\\',
        'repositories'    => 'App\\Repositories\\',
        'controllers'     => 'App\\Http\\Controllers\\',
        'requests'        => 'App\\Http\\Requests\\',
        'authorisation'   => 'App\\Services\\Authorisation\\',
        'filter_services' => 'App\\Services\\Filters\\',
    ],

    // Single-char prefixes in transformer $formats — change if they clash with your column names
    'transformers' => [
        'prefixes' => [
            'hidden_attributes'   => '!',  // SELECTed but excluded from JSON output
            'custom_attributes'   => '@',  // computed via transformer method
            'accessor_attributes' => '~',  // Laravel model accessor
            'unmerged_format'     => '_',  // format key not merged with '*'
        ],
    ],

];

use Devespresso\LaravelApiKit\Traits\EnableDatabaseFiltering;

class Post extends Model
{
    use EnableDatabaseFiltering;

    protected $defaultFilterService = PostFilterService::class; // optional

    // Columns searched when 'search' key is present in the request
    protected $searchableColumns = ['title', 'body'];
}

// Basic — validated request data drives all filters
$posts = Post::filter(
    data:   $request->validated(),
    user:   $request->user(),
);

// Pre-scoped query — base constraints enforced before filters run
$posts = Post::filter(
    data:   $request->validated(),
    user:   $request->user(),
    query:  Post::where('team_id', $team->id),
);

// Extra context passed to the filter service
$posts = Post::filter(
    data:    $request->validated(),
    user:    $request->user(),
    extras:  ['team' => $team],
);

// Explicit filter allowlist — only listed keys trigger filter methods
$posts = Post::filter(
    data:            $request->validated(),
    user:            $request->user(),
    explicitFilters: ['status', 'author_id'],
);

use Devespresso\LaravelApiKit\Services\Filters\BaseFilterService;

class PostFilterService extends BaseFilterService
{
    // Columns users can sort by
    protected $sortColumns = ['created_at', 'updated_at', 'id', 'title'];

    // Friendly alias => real column
    protected $customSortColumns = ['date' => 'created_at'];

    // Complex sort alias => method returning raw SQL expression
    protected $rawSort = ['status_order' => 'sortByStatus'];

    // Default sort when no 'sort' key is in the request
    protected $defaultSortingColumn = ['created_at,desc'];

    // Block these public methods from request dispatch
    protected $guardedMethods = ['sensitiveMethod'];

    // Methods restricted to specific roles (hierarchical)
    protected $roleMethods = [
        'moderator' => ['includeArchived'],
        'editor'    => ['includeUnpublished'],
        'admin'     => ['includeTrashed', 'byAnyTeam'],
    ];

    // Always applied regardless of request data
    protected $autoApply = ['onlyPublished' => true];

    // Baseline scope — runs before any filter methods
    protected function setConditions(): void
    {
        $this->query->where('team_id', $this->user->team_id);
    }

    // Triggered by ?status=published
    public function status(string $value): void
    {
        $this->query->where('status', $value);
    }

    // Triggered by ?author_id=5
    public function authorId(int $value): void
    {
        $this->query->where('user_id', $value);
    }

    // Always applied (via $autoApply)
    public function onlyPublished(bool $value): void
    {
        $this->query->where('published', true);
    }

    // Admin-only: include soft-deleted records
    public function includeTrashed(bool $value): void
    {
        if ($value) {
            $this->query->withTrashed();
        }
    }

    // Complex raw SQL sort — triggered by ?sort=status_order,asc
    protected function sortByStatus(): string
    {
        return "FIELD(status, 'active', 'pending', 'closed')";
    }

    // Internal helper — protected, so it can never be triggered from request data
    protected function applyTeamScope(): void
    {
        $this->query->where('team_id', $this->user->team_id);
    }
}

GET /posts?sort=created_at,desc
GET /posts?sort[]=title,asc&sort[]=created_at,desc
GET /posts?sort=status_order,asc  # triggers $rawSort method

class RoleResolver
{
    public function __invoke(?Authenticatable $user): mixed
    {
        return $user?->role; // e.g. 'admin', 'editor', or null
    }
}

use Devespresso\LaravelApiKit\Transformers\BaseTransformer;

class PostTransformer extends BaseTransformer
{
    // Wrap response under this key instead of the default 'data'
    protected $wrapper = 'post';

    protected $formats = [
        // Always included in every response
        '*' => [
            'id',
            'title',
            'status',
            '!user_id',        // SELECTed (for eager-load join), hidden from output
            '@word_count',     // calls $this->getWordCount($model)
            '~reading_time',   // calls $model->getReadingTimeAttribute()
            'author' => [       // nested relation — auto eager-loaded
                'id',
                'name',
                '!email',       // SELECTed but hidden
            ],
        ],

        // Merged with * on the 'show' action
        'show' => ['body', 'created_at'],

        // Standalone — does NOT merge with *, returned as-is on 'index'
        '_index' => ['id', 'title'],
    ];

    // Rename output keys
    protected $renames = [
        '*'           => ['created_at' => 'createdAt'],
        'author.name' => 'authorName',
    ];

    // Format attribute values via method names
    protected $formatters = [
        '*' => ['status' => 'formatStatus'],
    ];

    // Default values when attribute is null
    protected $defaults = [
        '*' => ['status' => 'draft'],
    ];

    // Conditionally hide attributes — method returns true to hide
    protected $guarded = [
        '*' => ['salary' => 'isNotAdmin'],
    ];

    // Custom attribute methods (used with '@' prefix)
    protected $customAttributes = [
        'word_count' => 'getWordCount',
    ];

    public function getWordCount($model): int
    {
        return str_word_count($model->body ?? '');
    }

    public function formatStatus($value): string
    {
        return ucfirst($value);
    }

    public function isNotAdmin($model): bool
    {
        return !auth()->user()?->isAdmin();
    }
}

'versioning' => [
    'enabled' => true,
    'driver'  => 'route_prefix',  // or 'header'
    'header'  => 'X-Api-Version',  // used when driver = 'header'
    'versions'=> ['v2', 'v3'],        // ordered — v3 builds on v2
],

use Devespresso\LaravelApiKit\Repositories\BaseRepository;

class PostRepository extends BaseRepository
{
    protected $model = Post::class; // optional — auto-resolved from class name

    protected function beforeCreate(array &$attributes): void
    {
        $attributes['slug'] = Str::slug($attributes['title']);
    }

    protected function afterCreated(Model $model, array $attributes): void
    {
        event(new PostCreated($model));
    }

    protected function beforeUpdate(?Model $model, array &$attributes): void
    {
        if (isset($attributes['title']))
            $attributes['slug'] = Str::slug($attributes['title']);
    }

    protected function afterUpdated(Model $model, array $attributes): void
    {
        Cache::forget("post:{$model->id}");
    }

    protected function afterDeleted(Model $model): void { }
}

$repo->index($data, $user);
$repo->index($data, $user, explicitFilters: ['status', 'name']);
$repo->get($id);
$repo->create($attributes);
$repo->update($model, $attributes);
$repo->delete($model);

// Skip all hooks
$repo->withoutHooks()->delete($model);

// Skip specific hooks only
$repo->withoutHooks('afterCreated')->create($attributes);
$repo->withoutHooks('beforeUpdate', 'afterUpdated')->update($model, $attributes);

use Devespresso\LaravelApiKit\Controllers\ApiController;

class PostController extends ApiController
{
    public function index(PostRequest $request): JsonResponse
    {
        return $this->setData(
            $this->repository->index($request->validated(), $request->user())
        )->respond();
    }

    public function store(PostRequest $request): JsonResponse
    {
        return $this->setData(
            $this->repository->create($request->validated())
        )->respondCreated();  // 201 Created
    }

    public function show(PostRequest $request, Post $post): JsonResponse
    {
        return $this->setData($post)->respond();
    }

    public function update(PostRequest $request, Post $post): JsonResponse
    {
        return $this->setData(
            $this->repository->update($post, $request->validated())
        )->respond();
    }

    public function destroy(Post $post): JsonResponse
    {
        $this->repository->delete($post);
        return $this->respondNoContent();  // 204 No Content
    }
}

// Merge extra keys into the response
$this->setData($post)->respond(['extra' => 'value']);

// Override wrapper key and format
$this->setData($post, 'post', format: 'show')->respond();

// Bypass the transformer entirely
$this->setRawData(['total' => 100, 'active' => 42], 'stats')->respond();

// Accumulate items under one key
$this->appendTo($post1, 'posts');
$this->appendTo($post2, 'posts')->respond();

// Attach metadata
$this->addMeta('permissions', ['edit', 'delete'])
     ->addMeta('roles', ['admin'])
     ->setData($post)->respond();

// Error response
$this->setCode(404, 'Post not found')->respond();

// Swap transformer at runtime
$this->setTransformer(SummaryTransformer::class)->setData($post)->respond();

{
    "code":       200,
    "status":     "success",
    "message":    "OK",
    "meta":       { ... },  // only present when set via setMeta() / addMeta()
    "data":       { ... },
    "pagination": { ... }
}

use Devespresso\LaravelApiKit\Requests\BaseRequest;

class PostRequest extends BaseRequest
{
    protected function actionsRules(): array
    {
        return [
            'store' => [
                'title' => ['required', 'string', 'max:255'],
                'body'  => ['required', 'string'],
            ],
            'update' => fn () => [
                'title' => ['sometimes', 'string', 'max:255'],
                'body'  => ['sometimes', 'string'],
            ],
        ];
    }

    // Optional: per-action authorization
    protected function storeAuth(): bool
    {
        return $this->user()->can('create', Post::class);
    }
}

use Devespresso\LaravelApiKit\Services\Authorisation\BaseAuthorisationService;

class PostAuthorisationService extends BaseAuthorisationService
{
    protected $mainProperty = 'post';
}

// Usage in a controller or service
(new PostAuthorisationService())
    ->setUser($user)
    ->setProperties(['post' => $post])
    ->doesItBelongToUser()    // asserts post->user_id === $user->id
    ->requireUser()           // asserts user is authenticated
    ->passwordVerification($password);

$auth = (new PostAuthorisationService())
    ->skipExceptions()
    ->setUser($user)
    ->setProperties(['post' => $post])
    ->doesItBelongToUser();

if (!$auth->isValid()) {
    return response()->json(['errors' => $auth->getErrors()], 403);
}