Filament Cms Api Laravel Package

Getting Started

This package is the read-only JSON API layer for a TomatoPHP Filament CMS site. Install it alongside its required core:

composer require tomatophp/filament-cms ^5.0 tomatophp/filament-cms-api
php artisan vendor:publish --tag=filament-cms-api-config

Before wiring anything up, confirm your environment matches the v5 constraint set — Laravel 12/13, PHP 8.2+, and tomatophp/filament-cms at ^5.0. If you are still on the Filament v4-era CMS, this release will not install; stay on the previous API package line until the app is upgraded.

The first place to look is the published config file (config/filament-cms-api.php). It is where the route prefix, middleware stack, pagination size, and the bound models/resources live. Read it before touching routes — most of what you'll want to change day-to-day is configured there, not in code.

Your first use case is almost certainly a headless front-end or mobile app that needs to consume published content without going through Filament's admin panel. Hit /api/cms/posts and confirm you get a paginated list, then /api/cms/posts/{slug} for a single item. If those respond, the package is wired correctly and you can start building against it.

Implementation Patterns

Consume, don't extend, for basic reads. The four endpoints (/api/cms/posts, /api/cms/posts/{slug}, /api/cms/categories, /api/cms/categories/{slug}) cover the common content-delivery case. Build your front-end or client directly against them rather than adding controllers.

Lean on query filters for listing pages. The list endpoints accept type, category, tag, trend, search, for, menu, and root. Typical patterns:

• Category archive page: GET /api/cms/posts?category=news&page=2
• Tag listing: GET /api/cms/posts?tag=laravel
• Site search: GET /api/cms/posts?search=deployment
• Featured/trending carousel: ../posts?trend=1
• Menu-driven navigation: ../posts?menu=main-nav
• Hierarchical category trees: ../categories?root=1

Use ?locale= for translated fields. If your CMS content is multilingual, pass ?locale=fr (or your configured codes) to receive the translated field values instead of the default locale. Decide on a locale-resolution convention in the consuming app (header, subdomain, or query param) so this stays consistent.

Treat the API as published-only by design. The endpoints expose only published posts and active categories. That means you do not need to filter drafts client-side, and equally you cannot use this API to preview unpublished content — keep previews inside the Filament admin.

Configure the prefix and middleware to fit your stack. Change the route prefix in config if /api/cms clashes with your existing API surface, and push authentication, rate limiting, or CORS middleware into the configured middleware array rather than editing package routes. If you need to swap in your own models or API resources (e.g. to add computed fields or adjust serialization), override the bindings in config instead of forking.

Adjust page size per environment. The configured page size is a single global value; for a large content site you may want a larger default and explicit page params from the client. Remember pagination metadata follows Laravel's standard resource collection shape, so your client can rely on meta/links.

Gotchas and Tips

This release is breaking for anyone using FAQ, ticket, or page transformers. v5.0.0 removes the unused FAQ, ticket, and page transformers along with the api/pages routes. The release notes say the page controller never shipped, so the routes were dead weight — but if you had built anything against /api/pages (or expected those transformers to exist), audit your consumers now. Anything referencing page, FAQ, or ticket types through this API needs to move to a custom endpoint or be dropped.

Version alignment is strict. tomatophp/filament-cms must be ^5.0, and Laravel must be 12 or 13 on PHP 8.2+. A partial upgrade — new API package against an old CMS — is the most likely install failure. Check composer why-not tomatophp/filament-cms ^5.0 first if install fails.

Nothing is writable through this API. It is deliberately read-only. If a requirement arrives for comments, submissions, or content creation, that is out of scope for this package — build a separate authenticated API rather than trying to bend these endpoints.

Only published/active content is visible. When debugging "missing" posts, check publish status and category active flags in the CMS before suspecting the API or your filters. This is the single most common source of confusion.

Filter combinations can silently return empty sets. Queries combine (category + tag + search etc.), so an over-specified request narrows to nothing. When a listing is unexpectedly empty, strip filters down to the base endpoint and add them back one at a time.

Locale is per-request, not per-model. Do not assume translated fields fall back transparently — if a translation is missing for the requested ?locale=, expect default-locale values or empty fields depending on CMS configuration. Pin down your fallback behavior with a quick test against known partial translations.

Debug through the test suite's shape. The package ships a full endpoint test suite and runs a Laravel 12/13 × PHP 8.3/8.4 matrix. When something behaves unexpectedly, write a small feature test against the route in your own app (using RefreshDatabase with seeded published content) — that reproduces issues far faster than poking a running server, and it mirrors how the package itself is verified.

Extension point: config over code. Prefix, middleware, page size, models, and resources are all configurable. Prefer config overrides for customization; reserve subclassing for genuinely new behavior, and re-run the endpoint tests after any model/resource swap to catch serialization breakage.