/laravel-api-tool-kit

name: laravel-api-tool-kit
description: >
  Build production-grade Laravel REST APIs. Covers general best practices
  (code quality, DI, events, auth, exceptions, testing, database) AND
  essa/api-tool-kit specific patterns (ApiResponse, QueryFilters, dynamicPaginate, EnumHelpers).
  Use when creating or reviewing any Laravel API code in a project that has essa/api-tool-kit installed.
license: MIT
metadata:
  author: https://github.com/ahmedesa
  version: "3.2.0"
  domain: backend
  triggers: essa/api-tool-kit, ApiResponse, QueryFilters, dynamicPaginate, useFilters, EnumHelpers, create a controller, add an endpoint, add filtering, create a model, create a resource, create an action, create an event, review this API code, add pagination, write a test, how should I structure this feature
  role: specialist
  scope: implementation
  output-format: code
  related-skills: laravel-specialist, php-pro

Laravel API Tool Kit Skill

This project uses the `essa/api-tool-kit` package. All API code MUST follow the standards in this skill — both the general Laravel best practices and the package-specific patterns.

Assumed Setup

• `essa/api-tool-kit` is installed via Composer
• Base `Controller` already uses the `ApiResponse` trait
• The `dateTimeFormat()` global helper is available
• `dynamicPaginate()` macro is registered on the query builder

Project Defaults

**Fill these in when installing the skill.** The AI reads this section to match existing project conventions.

• **Primary key type**: `ulid` ← change to `id` if this project uses auto-increment
• **Auth guard**: `sanctum` ← change if different (e.g. `api`)
• **Test class**: `Tests\TestCase` ← change if the project uses a custom base

Structure Mapping & Customization

The rules in the `rules/` directory are **pattern-based**. While examples use standard Laravel paths (e.g., `app/Models`), they are designed to be mapped to any structure.

DDD / Domain-Driven Design

If the project uses a DDD structure, the rules apply to the corresponding domain folders. **Folder naming may vary by project** (e.g., `Repository` vs `Repositories`). Examples include:

• **Models**: `app/Domain/{Domain}/Models/`
• **Actions**: `app/Domain/{Domain}/Actions/`
• **Repositories**: `app/Domain/{Domain}/Repository/` (or `Repositories/`)
• **DTOs**: `app/Domain/{Domain}/DTO/` (or `DTOs/`)
• **Filters**: `app/Domain/{Domain}/Filters/`

**Note for AI**: Always run `ls app/Domain/` to identify the project's specific naming conventions before creating new files. Priority is always: **Project Patterns > Global Rules**.

Project-Specific Rules

If a specific project requires overrides (e.g., "We use `id` instead of `ulid`" or "We return raw arrays instead of DTOs"), **do not modify these global rules**. Instead: 1. Add the override to your project's AI instructions file (e.g. `AGENTS.md`, `CLAUDE.md`, or `.claude/rules/` for Claude Code). 2. The AI will prioritize project-level instructions over these global patterns.

Baseline — Applies to Every File

Before reading anything else, these rules apply universally:

• Every PHP file MUST start with `declare(strict_types=1);`
• Every method MUST have parameter types and a return type
• Constructor dependencies MUST use `private readonly` promotion
• User-facing strings MUST use `trans()` — never hardcoded

See `rules/code-quality.md` for the full baseline.

Component Map

When working on a specific concern, read the corresponding rule file:

General Standards (applies everywhere)

| Task | Read | |------|------| | Code style, types, naming, constants | `rules/code-quality.md` | | Injecting dependencies | `rules/dependency-injection.md` | | Events and listeners | `rules/events.md` | | Standalone queued jobs | `rules/jobs.md` | | Authorization and policies | `rules/authorization.md` | | Error and exception handling | `rules/exceptions.md` | | Writing feature tests | `rules/testing.md` | | Database patterns, ULIDs, transactions, bulk ops | `rules/database.md` | | External 3rd-party integrations | `rules/services.md` | | DDD structure, domain boundaries, cross-domain rules | `rules/ddd.md` |

Package-Specific Patterns

| Task | Read | |------|------| | Return a JSON response | `rules/responses.md` | | Add filtering / sorting / search to an endpoint | `rules/filters.md` | | Create a new Action class | `rules/actions.md` | | Create a DTO for an Action or Service | `rules/dtos.md` | | Write or review a Controller | `rules/controllers.md` | | Write a FormRequest | `rules/requests.md` | | Write an API Resource | `rules/resources.md` | | Create or update a Model | `rules/models.md` | | Create or update a Repository | `rules/repositories.md` | | Create an Enum | `rules/enums.md` | | Add pagination | `rules/pagination.md` |

Always Check First

| Task | Read | |------|------| | Before writing any code | `rules/anti-patterns.md` |

Building a New Endpoint

Follow `workflows/new-endpoint.md` for the full step-by-step process.

The order is always: **Model → Migration → Filter → Enum → Requests → Resource → Policy → Action (if needed) → Controller → Language file → Route → Test**

Available Workflows

Building

• `workflows/new-endpoint.md` — add a complete CRUD resource from scratch
• `workflows/add-filter.md` — add filtering to an existing model
• `workflows/write-tests.md` — write tests for any feature (decides test type, structure, actors, edge cases)

Reviewing

• `workflows/code-review.md` — multi-phase code review (structural + defense + scope discipline)

Debugging

• `workflows/investigate.md` — structured debugging (data-first, multi-source, 15-min checkpoint)
• `workflows/curl-test.md` — test an endpoint with curl and cross-reference response vs DB

Knowledge Management

• `workflows/update-knowledge.md` — save learnings into rules or knowledge files
• `workflows/organize-knowledge.md` — consolidate scattered docs into one-file-per-feature
• `workflows/create-workflow.md` — c