Fast Api Crud Laravel Package

Getting Started

Treat this as a scaffolding-first package and verify before you commit to it: it has a single maintainer, ~9 stars, and zero dependents, so the source is the documentation. v3.1.0 improves that situation considerably by shipping a source-derived AI reference set and MCP server — use those as your first read, but still verify.

1. Install and inspect.

   composer require anil/fast-api-crud
   

   Then read, in this order, before writing any code:

   • composer.json — the illuminate/* version constraints tell you which Laravel versions are actually supported (don't trust the README's badge).
   • src/*ServiceProvider.php — what is registered, whether it's auto-discovered, which config/stub/AI tags are publishable.
   • config/fast-api-crud.php (if present) — route prefix, middleware group, pagination defaults, response envelope.
   • resources/ai/sklils/fast-api-crud/references/*.md — new in v3.1.0 and the closest thing to real docs: controllers, routes, scaffolding, query params/responses, hooks/contracts/traits, HasApiResponse, macros, helpers, config/enums, spatie/laravel-permission integration, testing. A test asserts every public helper/responder/date scope/Builder macro/config key/controller property is documented, which is a better guarantee than the README.
   • stubs/ and any src/Console/Commands — this is where the real behaviour lives.

2. Publish everything you may want to edit.

   php artisan vendor:publish --provider="Anil\FastApiCrud\FastApiCrudServiceProvider"
   

   Publish config and stubs in one go if the tags allow it; re-publishing later silently overwrites stub customisations you've made. If you use AI tooling, php artisan vendor:publish --tag=ai publishes the skill and agent into .claude/.

3. Wire up the new AI tooling (optional but useful).

   php artisan fast-api:install-ai --target=all   # claude | agents | cursor | copilot | all
   php artisan fast-api:mcp                       # stdio MCP server
   

   install-ai installs the skill, a Claude Code subagent, a managed instructions block in CLAUDE.md / AGENTS.md / .cursor/rules / .github/copilot-instructions.md, and MCP registration in .mcp.json, .cursor/mcp.json, .vscode/mcp.json. It is idempotent (marker blocks replaced in place, JSON configs merged), but run it on a clean branch and review the diff. Do this after step 1, not instead of it — the generated instructions encode the package's conventions, and you want to know what those are before an agent applies them.

4. First use case: one resource, end to end. Pick a trivial model (Post) that already exists with a migration and factory. Generate or wire up the CRUD, register the routes, and exercise all five endpoints with curl/Postman before touching a real domain model. You want to see, concretely:

   • the JSON shape of index (envelope, pagination meta keys),
   • the status codes on store (201 vs 200) and destroy (204 vs 200),
   • what a validation failure looks like (422 body shape).

   If you're using the MCP server, scaffold produces the same files as the Artisan generator — generate once by hand first so you can tell what the agent changed.

5. Diff the generated output against your house style immediately. If the package emits controllers into app/Http/Controllers, check whether it respects a custom namespace; if it doesn't, decide then whether you're adopting its conventions or forking the stubs. Retrofitting 30 resources later is miserable.

Implementation Patterns

Scaffold-then-own (recommended). Use the package's generator/command once per resource, commit the generated files, and stop depending on the package at runtime. Move it to require-dev and let it be a code generator plus a dev-time introspection tool. You get fast first-pass CRUD without a runtime dependency you can't audit.

Inherit-and-configure (only if the base class is thin). If the package ships a base controller, extend it and declare the resource in properties rather than writing methods:

class PostController extends FastCrudController
{
    protected string $model = Post::class;
    protected string $resource = PostResource::class;
    protected string $storeRequest = StorePostRequest::class;
    protected string $updateRequest = UpdatePostRequest::class;
    protected array $searchable = ['title', 'slug'];
    protected array $with = ['author:id,name'];
    protected array $sortable = ['created_at', 'title'];
}

Override individual actions (index, store) as your needs grow; keep the inherited ones for the boring resources. If the base class is a god-object with 40 protected properties, prefer the generator path instead. describe_controller over MCP is the fastest way to see which properties a given controller actually honours.

Keep validation in FormRequests. Don't rely on the package's inline rules array for anything non-trivial — unique rules need the route-bound model's ID on update, which is far cleaner in a FormRequest with Rule::unique(...)->ignore($this->route('post')). If the package supports per-action request classes, wire them; otherwise override store()/update() to type-hint your requests.

Standardise the query-param contract for your frontend. Whatever the package supports for filtering/sorting/pagination, document it once (?filter[status]=published&sort=-created_at&per_page=50) and keep it identical across resources. Use the new query_reference MCP tool / reference doc to get the real supported syntax rather than guessing from the README. If the package's convention diverges from what your SPA already sends, override the index method or add a middleware that rewrites params — don't make the frontend special-case one endpoint.

Pin the response envelope. If you have an existing ApiResponse trait or JsonResource convention, override the package's serialization early — the HasApiResponse reference doc is the place to start. Mixed envelopes across a single API is the most common way these packages become a liability.

Layer authorization outside the CRUD. Policies and authorizeResource() via $this->authorize() in the constructor work fine with a base controller; keep tenancy scoping (where('tenant_id', ...)) in a global scope on the model, not in the controller, so the package's generated queries can't bypass it. v3.1.0 documents the spatie/laravel-permission integration (alias registration, guards, seeding, caching, teams) — read that before inventing your own mapping.

Use MCP for discovery, not for runtime. list_controllers, describe_controller, list_routes, model_info, get_config are read-only and genuinely useful when onboarding to a codebase that already uses the package, or when auditing what routes actually exist. search_reference/read_reference beat grepping vendor. Treat scaffold as a generator: same review bar as Artisan output.

Managed AI instruction blocks live in your repo. Commit CLAUDE.md/AGENTS.md/.cursor/rules/.github/copilot-instructions.md changes deliberately. Keep your own conventions outside the marker block so re-running install-ai doesn't delete them, and put a note in the PR describing what the installer changed.

Test the generated surface, not the package. Write feature tests per resource: happy-path index with pagination, 422 on invalid store, 404 on missing ID, 403 for a forbidden user. Those tests survive a swap to hand-written controllers later — and they're the check that AI-assisted generation didn't quietly diverge from the contract.

Gotchas and Tips

• Bus-factor risk, now with more surface area. Single maintainer, no dependents, plus a new MCP server, installer, instruction-file writer and JSON-config merger — all of which touch your repo. Pin an exact version in composer.json and, if you adopt the runtime base class, fork it into packages/ under your VCS. Budget an hour to verify it actually works against your Laravel version before it appears in a sprint estimate.
• install-ai writes to files you care about. It edits CLAUDE.md/AGENTS.md/.cursor/rules/copilot instructions and merges .mcp.json, .cursor/mcp.json, .vscode/mcp.json. It's idempotent — marker blocks are replaced in place — but that means custom edits inside the markers are lost on re-run. Run on a clean branch, review the diff, and keep house rules outside the markers. Check the merged JSON didn't clobber an existing MCP server entry of the same name.
• MCP configs are local-dev artifacts. They can embed absolute paths and commands, and the server runs with your user's privileges over stdio. Review before committing .mcp.json/.vscode/mcp.json; keep the server out of production images and CI unless you actually need it there.
• Reference docs are generated, and coverage ≠ correctness. The v3.1.0 test asserts every public helper/macro/config key is documented, not that the docs match runtime behaviour. On version bumps, re-read the reference topic you depend on rather than trusting a cached copy in .claude/.
• Auto-discovery ambiguity. Confirm the provider is in bootstrap/providers.php/config/app.php after install; on older Laravel versions with composer.lock cache issues, a stale vendor/composer/installed.json will make commands (including the new fast-api:* ones) "not exist". composer dump-autoload fixes it.
• Stub overwrites. vendor:publish --force will clobber customised stubs and published config. Copy stubs into your own namespace and point the config at them, or keep the published copies under code review. Same applies to --tag=ai if you've edited the published skill files.
• Mass assignment. Generated controllers often pass $request->all() straight to create(). If the model's $fillable doesn't list every request key you send, fields are silently dropped — no exception, just missing columns. Assert on the persisted row in tests, not just the response body. AI-generated controllers are no better here; review the diff.
• Route model binding keys. If the package resolves {post} via id but your frontend uses slugs, add getRouteKeyName() on the model rather than patching the controller. Soft-deleted models will 404 by default; if you want ?with_trashed=1, verify the package honours it — likely it doesn't, so override show/destroy.
• N+1 in index. Check whether $with is applied on the query builder or only in the resource. DB::listen(fn ($q) => logger($q->sql)) while hitting index with 20 rows is the fastest way to find out. describe_controller will show the property, not the effect.
• Pagination caps. per_page=100000 is a common DoS vector in generated CRUD. Clamp it in the config if exposed, or in a middleware. Check get_config for the default before assuming it's safe.
• Validation error shape. Laravel's default 422 body doesn't match most API contracts (errors keyed by field). If you have a global Handler that reshapes it, confirm the package isn't catching and re-throwing ValidationException with its own format.
• Debugging tip. php artisan route:list --path=api -v shows which controller class actually handles each verb — invaluable when auto-registered routes shadow your manual ones, or when an agent claims a route exists. list_routes over MCP gives the same picture without shelling out.
• Extension points to check for, in order of preference: publishable stubs → overridable protected methods → container bindings for repository/service interfaces → model-level scopes and accessors. Editing vendor/ is not on this list. The new prompts (build-resource, debug-endpoint) are a convenience layer over these, not a replacement.
• Exit strategy. Because it's generator-shaped, your escape hatch is cheap: keep generated controllers small, keep business logic in actions/services rather than controller overrides, and dropping the package later is a composer remove, a stub commit, and deleting the managed AI blocks/config entries.