robindrost/prismic-eloquent
Prismic Eloquent brings Laravel’s Eloquent-style models to Prismic CMS, letting you query and manage Prismic documents with familiar fluent syntax, relationships, and casts. It makes content-driven Laravel apps feel like working with native database records.
Install and verify compatibility first. Run composer require robindrost/prismic-eloquent and immediately inspect the installed composer.json for its illuminate/* and PHP constraints. The package was archived in 2021, so it will not resolve against current Laravel majors without a fork or --ignore-platform-reqs-style workarounds. Confirm this before writing any application code against it.
Configure the connection. Publish the package config (php artisan vendor:publish) if it ships one, and set the Prismic repository endpoint plus an access token in .env. In almost every Prismic setup the master ref matters as much as the credentials — previews and release content require passing a specific ref with each query. Wire both into config/prismic.php and keep them in config, not inline in models, so config:cache behaves.
Read the source, not the docs. The README is thin. The two files worth reading end-to-end before anything else are the base model class (how $type, attributes, casts, and getAttribute work) and the query builder class (which Prismic predicates are exposed and how get/first/paginate translate to API calls). Everything you can do is visible there.
First use case: a singleton page. Define one model per Prismic custom type, with the $type slug matching Prismic exactly:
class Homepage extends PrismicModel
{
protected $type = 'homepage'; // must match the API ID in Prismic
}
$home = Homepage::first();
Then a list to prove filtering and pagination work:
$posts = Article::where('category', 'news')->orderBy('date', 'desc')->paginate(10);
If those two queries work with real content, the remaining integration is mostly mapping fields and rendering rich text.
One model per custom type, thin models, fat accessors. Prismic content comes back as nested structures ($document->data->title->value for rich text, image blocks with multiple renditions). Don't leak that shape into Blade. Define accessors on the model so views see $page->title and $page->hero_image, and keep the block/rendition parsing in one place per field type.
Cast rich text and slices deliberately. Rich text is an array of block objects, not a string. Write one custom cast (e.g. RichTextCast) that renders to HTML or to a structured array, and reuse it everywhere. For Prismic Slices, map slice_type to a Blade partial via a small renderer — do not switch on slice types in five different templates.
Treat relationships as API calls. The selling point is $article->author-style traversal, but each link resolution fetches a document from Prismic. Practical pattern: resolve links in batches where you can, cache aggressively, and never traverse relationships inside a loop over a large collection without measuring. A single listing page can easily turn into 50+ API round-trips.
Put a cache layer between the model and the API. Prismic is a CDN-backed read API, but quota and latency are still real. Wrap your queries in Cache::remember() keyed on the query signature plus the ref token, so preview/draft content never gets served from the published cache. Invalidate by document ID when you know content changed (webhook from Prismic → clear that key).
Plumb the preview ref through a scope or global config. The standard Laravel pattern here is to set the active ref from the request (a ?preview= token) in a service provider or middleware, and have every query pick it up. Preview functionality is otherwise invisible and you'll discover it's broken during a content launch.
Test against faked HTTP, never the live API. Because models are thin wrappers over HTTP, use Http::fake() (or a Guzzle mock handler) with recorded Prismic JSON responses. This also gives you a regression suite that survives the package being unmaintained — if you fork it, those tests are your safety net. Never let CI hit a real repository: rate limits will make tests flaky.
Use it as a read-only content layer. These models are not a full Eloquent replacement: assume no save(), no transactions, no real joins. Architecturally, treat Prismic as the source of truth and, if you need writes, a local cache/replica table.
composer.json, and budget for a fork. The most common failure mode is a silent Composer constraint conflict during a framework upgrade, not a runtime bug.assessment-tpm.md bundled with this package discusses Flysystem security advisories and says nothing about Prismic or Eloquent. That is a mismatched or hallucinated document — don't use it to make compatibility decisions. Verify constraints yourself.where is not SQL. Filters map to Prismic predicates. Only a subset is likely exposed. When you need a predicate the builder doesn't support (e.g. at/similar/fulltext with particular options), drop to the underlying Prismic client rather than contorting the fluent API.paginate() may not support arbitrary page sizes, and total/pageCount values come from the API response, not a count query. Test edge cases: last page, empty results, a single item.null rather than throwing. Add a sanity check or a nullable handling path, and cover it with a faked-response test.php artisan config:cache bakes the repository and token into the cache; changing .env without config:clear produces confusing auth errors in production but not locally.ref (preview vs. master), the custom-type slug, or the locale — not the fluent API.getAttribute. There's no macro system, so any reusable filter logic belongs in your own repository/scopes layer rather than being bolted onto the base class.How can I help you explore Laravel packages today?