Prismic Bundle Laravel Package

Getting Started

The bundle is a thin Symfony wrapper around prismic/php-sdk, so treat it as configuration glue rather than a framework in its own right. Almost all the substance you'll interact with daily lives in the PHP kit; the bundle just gives you a container-managed prismic.api service and a YAML config block.

Install and register (this is Symfony 2/3-era bundle style):

composer require prismic/prismic-bundle

// app/AppKernel.php
$bundles = [ new Prismic\Bundle\PrismicBundle\PrismicBundle(), ];

# app/config/config.yml
prismic:
    api:
        endpoint: https://your-repo.prismic.io/api
        token: "%prismic_token%"

Where to look first:

1. The prismic.api service ID — this is the single entry point the bundle exposes. Everything routes through it.
2. Prismic\Api::get() in the upstream php-kit README — that's effectively what the container hands you, and the kit docs are your real reference.
3. Your Prismic writing room custom types — every query and fragment accessor is shaped by the content model, not the bundle.

First use case: fetch one document by ID and read a fragment.

$api = $this->get('prismic.api');
$doc = $api->getByID('Wx...');
$title = $doc->getText('page.title');

That's the whole loop: config → prismic.api → typed document → fragment accessor. Get that working before anything else, because every pattern below builds on it.

Implementation Patterns

Use Prismic\Predicates, never hand-built URLs. The kit handles the ref parameter, pagination, and form encoding for you. Reach for predicates for every query:

$response = $api->query([
    Predicates::at('document.type', 'blog_post'),
    Predicates::any('document.tags', ['featured', 'homepage']),
    Predicates::fulltext('document', 'symfony'),
], ['pageSize' => 10, 'orderings' => '[my.blog_post.date desc]']);

Inject the service, don't pull from the container. In modern controllers and services, constructor-inject Prismic\Api (or a thin wrapper) rather than calling $this->get('prismic.api'). This makes the code testable and lets you mock the API in unit tests — which matters more here than usual, because you can't rely on upstream fixes to smooth over integration pain.

Map documents to view models once. Fragment accessors are type-specific: getText() only works on Text/StructuredText, getImage() only on Image, getSliceZone() only on SliceZone, and the bundle validates none of this. Calling the wrong accessor gets you a null or a notice. Define small DTOs that translate a Prismic document into typed PHP properties, and use those everywhere in your app. This is the biggest quality-of-life win — it centralizes the "what shape is this fragment?" question in one place.

Build a slice renderer. A SliceRenderer service that maps slice->getSliceType() to a Twig partial (slices/paragraph.html.twig, slices/image.html.twig, etc.) is usually ~30 lines and pays for itself immediately. The bundle ships nothing here, so you own this pattern.

Keep credentials in parameters/env, not config. Inject the endpoint and token from parameters.yml or environment variables. You'll want to point at a staging repository for previews without editing tracked config.

Caching. The kit's Api object fetches repository metadata (form endpoints, master ref, etc.) on construction and can take a PSR-6 or Doctrine cache. Wire your Symfony cache pool into the prismic.api service so metadata isn't fetched on every request. Note: document responses are not cached by the bundle. Add a decorator or explicit cache layer around your query service if you need document-level caching.

Preview support. Prismic preview works by swapping the master ref for a preview ref. The kit exposes Api::getPreviewRef($token). There is no bundle-level preview handling — you need a small listener or controller action that reads the preview cookie and passes the preview ref via Options::setRef(). Budget for it explicitly.

Gotchas and Tips

The bundle is archived. This shapes every other decision. The AppKernel registration style targets Symfony 2/3. On Symfony 4+ skip the bundle entirely and instantiate Prismic\Api in config/services.yaml yourself — you get the same DI ergonomics with code you control and can upgrade PHP/Symfony on your own schedule.

prismic.api is expensive if constructed off-container. The Api object does an HTTP round-trip to fetch form metadata. If you build it in tests, console commands, or workers (not via the container), you get one network call per instantiation. Use the container service, or wire a cache explicitly.

The access token is repository access, not viewer auth. It goes on the URL, it's visible in logs and proxies if you're careless — treat it as a secret, and remember it does not authorize end users. Access control lives in your app, not in Prismic.

Fragment accessors fail softly. Wrong-type accessors return null or emit a PHP notice rather than throwing. If a template suddenly renders a blank field, suspect a content-model change or a wrong accessor before suspecting the bundle. Add assertions in your DTO mapping layer.

Preview refs are easy to forget. The kit caches masterRef; if you swap in a preview ref, you need to bypass that cache or use a fresh Api instance with Options::setRef(). Otherwise your previews quietly serve published content.

Dependency resolution friction is likely. The bundle pins old versions of Symfony, Guzzle/HTTP clients, and the Prismic SDK. If you must adopt it (e.g., legacy codebase), fork it, pin dependencies, and own patching. If you're starting fresh, go directly to prismic/php-sdk with a small adapter service — same editor experience, upstream fixes, and no archived-package risk.

Extension point to lean on: the container service definition. The most useful thing the bundle gives you is a declarative place to build the Api with the right cache, serializer, and endpoint. If you migrate off the bundle, replicate that service definition — it's the durable part.