Prismic Io Laravel Package

Getting Started

• Install with an explicit constraint, not a floating branch: composer require adamgoose/prismic-io:1.3.*. This package predates Laravel package auto-discovery, so nothing happens until you register it yourself.
• Laravel 4.2: add the package service provider to app/config/app.php under providers, and the facade (if one is shipped) under aliases. Run composer dump-autoload afterwards; a missing alias entry is the most common cause of a confusing "Class not found" on first boot.
• Publish the config: php artisan config:publish adamgoose/prismic-io (4.2 path) — the file lands under app/config/packages/adamgoose/prismic-io/. Put your Prismic API endpoint and access token there, or in .env if the package's config reads it.
• Read the service provider's register() first. That is where the Prismic client is bound into the container and where the config keys are actually consumed; the README quick-start is secondary. The provider tells you the binding name you will type-hint and inject everywhere else.
• First use case: open php artisan tinker, resolve the client from the container (App::make('...')), and run a single read against a known document type before touching a controller. That one step validates credentials, config publishing, and container bindings simultaneously — if the query returns a document, your integration is live.

Implementation Patterns

• Inject, don't facade. Type-hint the bound client (or the package's wrapper class) in controller constructors, artisan commands, and queue job handle() methods. Reserve the facade alias for Blade templates and tinker. This is what makes the rest of these patterns possible.
• Wrap it in one application-level gateway. Create a ContentRepository / PrismicGateway class that owns the client and exposes domain-shaped methods (getHomepage(), getArticleBySlug($slug), getLatestPosts($limit)). Every view and controller talks to that class, never to the Prismic client directly. When Prismic's API shifts — or when you eventually replace this package — you change one file.
• Fragment mapping belongs in the gateway, not the view. Prismic returns structured fragment objects (rich text, images, document links, groups). Map them to plain PHP arrays or simple view models at the boundary. Blade should receive strings and URLs, not Prismic\Fragment\* instances, otherwise every template becomes coupled to the CMS SDK.
• Pin the ref explicitly. Prismic queries are resolved against a ref, and the master ref advances every time an editor publishes. Fetch the master ref once (the package/client supports this) and pass it into queries rather than relying on an implicit default — this is also the hook you need for release previews and previews of unpublished drafts.
• Cache aggressively, invalidate by ref. Content queries are network calls against a hosted API. Cache the mapped output under a key that includes the master ref, and bust it when the ref changes — either by polling the ref on a schedule or via a Prismic webhook hitting a small route in your app. Keying on the ref means a publish is a cache miss, and nothing else is.
• Pagination over "fetch everything." The Prismic API returns a page size and total count. For listings, expose page/pageSize from your gateway and return the total so the controller can build pagination links. Do not loop until exhausted inside a request.
• Queue the sync-shaped work. Bulk re-indexing, sitemap generation, or warming caches after a publish should be a queued job that resolves the client inside handle(), not a long-lived object holding a stale config from before the deploy.
• Testing. Bind a fake implementation of your gateway (or a Mockery double of the client) in setUp() via App::bind(). Because your views depend on the gateway's plain arrays rather than the SDK, the vast majority of your feature tests never need to know Prismic exists.

Gotchas and Tips

• The compatibility ceiling is the real story. This is a 2014 package whose last release explicitly targeted Laravel 4.2. Check composer.json for the illuminate/support constraint before planning anything — if it's 4.2.*, this will not install on a modern Laravel without a maintained fork, and forking means you now own the whole package. Confirm that up front; it determines whether the rest of this document applies at all.
• "Fixing some bugs" is not a changelog. v1.3's release note is two lines. If you can reach the repo, git diff <previous-tag>..1.3 and scan for changed defaults, changed return shapes, or changed exception types before upgrading production. With no detail available, treat the release as unaudited and lean on a smoke test.
• Add one smoke test and run it on every upgrade. A single feature test that fetches a document through your gateway and asserts on mapped output is the cheapest possible regression guard for a package with this little release documentation.
• Config cache will silently ignore your edits. After changing the published config, clear it (php artisan config:clear where available, or delete the cached file) and re-run the smoke test. On 4.2 the config lives under app/config/packages/...; do not edit the file inside vendor/.
• Never edit vendor files to add a feature. Bind your own implementation to the package's binding in a service provider registered after the package provider, or use App::extend() to decorate the existing resolution. Vendor edits vanish on the next composer update and make patch upgrades hazardous.
• Debugging order. Service provider → published config → resolved class. Log get_class(App::make('...')) to confirm you are hitting the implementation you think you are; container overrides that don't take effect are almost always a provider ordering problem.
• Credential and endpoint drift. A wrong endpoint URL or a token for the wrong repository produces errors that look like empty results. Log the endpoint at boot in non-production environments so a misconfiguration is obvious rather than mysterious.
• Exit-cost awareness. Given the package's age and single-maintainer profile, keep the Prismic dependency behind your gateway and avoid letting fragment objects or client types leak into domain code. That single discipline is what makes replacing this package a contained task rather than a rewrite.