PHPackages netglue/expressive-prismic - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. netglue/expressive-prismic Abandoned → [netglue/primo](/?search=netglue%2Fprimo)Module[API Development](/categories/api) netglue/expressive-prismic ========================== Module/Library for creating content driven websites with prismic.io and Zend Expressive 4.5.1(4y ago)1480[2 issues](https://github.com/netglue/Expressive-Prismic/issues)MITPHPPHP >=7.3CI failing Since Mar 13Pushed 4y agoCompare [ Source](https://github.com/netglue/Expressive-Prismic)[ Packagist](https://packagist.org/packages/netglue/expressive-prismic)[ RSS](/packages/netglue-expressive-prismic/feed)WikiDiscussions master Synced 2w ago READMEChangelog (10)Dependencies (14)Versions (26)Used By (0) Zend Expressive / Prismic.io CMS Module ======================================= [](#zend-expressive--prismicio-cms-module) [![Build Status](https://camo.githubusercontent.com/0ce27ac055aeab571d5030202c6222d7f1b127d3bf341dae8bde4977475e179b/68747470733a2f2f6170692e7472617669732d63692e6f72672f6e6574676c75652f457870726573736976652d507269736d69632e737667)](https://travis-ci.org/netglue/Expressive-Prismic)[![Test Coverage](https://camo.githubusercontent.com/44e2d2b4b2b7cb1680d86023bfa646cd194e2dff7b810b9b8d19145afa5e4044/68747470733a2f2f6170692e636f6465636c696d6174652e636f6d2f76312f6261646765732f64303563623636353830643736306436643435652f746573745f636f766572616765)](https://codeclimate.com/github/netglue/Expressive-Prismic/test_coverage) Introduction ------------ [](#introduction) This module/library's purpose is to ease development of content driven websites using prismic.io's content API as a backend service. If you haven't heard of Prismic before, you can [find out about it here](https://prismic.io). Requirements ------------ [](#requirements) This module is only suitable for Zend Expressive ^3.0 and PHP ^7.1 Furthermore, it uses a fork of the official Prismic.io php library which you can see here: [netglue/prismic-php-kit](https://github.com/netglue/prismic-php-kit). This fork is quite different to the official kit and I recommend looking through the docs/code to make yourself aware of the differences if you are already familiar with the official lib. Install ------- [](#install) Install with composer ala `composer require netglue/expressive-prismic` This should also ask you if you want to inject the config provider too. Tests ----- [](#tests) ``` $ composer install $ vendor/bin/phpunit ``` Basic Configuration ------------------- [](#basic-configuration) This library exposes the Prismic API instance in your container as `Prismic\Api`. At the very least, you'll need to configure your credentials thus: ``` return [ 'prismic' => [ 'api' => [ 'token' => 'Permanent Access Token', 'url' => 'https://Repo-name.prismic.io/api', ], ], ]; ``` Defining Routes --------------- [](#defining-routes) In order to allow you to specify properties of a document to look out for during routing, you must map the route parameter names you want to use to the prismic document/api equivalent. The defaults are: ``` 'prismic' => [ 'route_params' => [ 'id' => 'prismic-id', 'bookmark' => 'prismic-bookmark', 'uid' => 'prismic-uid', 'type' => 'prismic-type', 'lang' => 'prismic-lang', ], ], ``` So, assuming the above, to define a route to a bookmarked document, you would configure something like this: ``` /** * @var \Zend\Expressive\Application $app * @var \Zend\Stratigility\MiddlewarePipeInterface $middlewarePipe */ $app->route('/', [$middlewarePipe], ['GET'], 'home') ->setOptions([ 'defaults' => [ 'template' => 'page::default', 'prismic-bookmark' => 'home', ], ]); ``` Normally, to save yourself some effort, you'd have a template that's capable of rendering perhaps any page of a given type such as a 'case-study' type. Let's say you want the url `/case-studies/{case-study-uid}`, then you'd define a route like this *(If you are using FastRoute)*: ``` $app->route('/case-studies/{prismic-uid}', [$middlewarePipe], ['GET'], 'case-studies') ->setOptions([ 'defaults' => [ 'template' => 'my:case-study', 'prismic-type' => 'case-study', ], ]); ``` Cache Busting Webhook --------------------- [](#cache-busting-webhook) You will see in `Factory\PipelineAndRoutesDelegator` that two routes are wired in by default, one of these is the webhook to bust the cache. In order to use it, you **should** provide a shared secret that Prismic.io sends in it's webhook payload to a local configuration file or Config Provider like this: ``` return [ 'prismic' => [ 'webhook_secret' => 'SomeSuperToughSharedSecret', ], ]; ``` You would also need to enter this secret into the relevant place in your Prismic repository settings. > By default the secret is `null`, which means that the secret will not be validated even if it's sent by Prismic. If you decide not to setup a secret, I **strongly** recommend that you configure an obscure URL otherwise anyone will be able to POST to your webhook endpoint and bust the cache on demand, slowing down your site. By default the url of the webhook will be `/prismicio-cache-webhook`. You should change this to something sufficiently random in the following way: ``` return [ 'prismic' => [ 'webhook_url' => '/send-prismic-webhooks-here', ], ]; ``` If the webhook url is hit with a POST request and valid JSON payload, the pre-configured middleware will empty the cache attached to the Prismic API instance. The webhook route points to a middleware pipe named `ExpressivePrismic\Middleware\WebhookPipe` so if you want to modify the pipeline to do other things, or replace it entirely, just alias that pipe to different factory or implement a delegator factory for the pipe. Link Resolver ------------- [](#link-resolver) The Link Resolver is a concept introduced by Prismic to turn documents, or document link fragments into local urls and there's a concrete implementation in this package at `ExpressivePrismic\LinkResolver`. Using the same setup for routing parameters, it tries to use the Expressive URL helper to generate local URLs. It's setup in the container as `Prismic\LinkResolver` as well as `ExpressivePrismic\LinkResolver` and throughout the package it's retrieved by the name of `Prismic\LinkResolver` so it's easy to replace with your own concrete implementation if you need one. Previews -------- [](#previews) There's another route that's auto-wired like the cache busting webhook for initiating previews. All you have to do is add the URL in the settings on your Prismic repository and clicks on the preview button in the writing room will put the site in preview mode. You can see how this is configured in `Factory\PipelineAndRoutesDelegator` - the URL is `/prismic-preview` by default, but you can change the url by setting the following configuration value: ``` return [ 'prismic' => [ 'preview_url' => '/some-other-endpoint', ], ]; ``` > In 4.2.0, the middleware responsible for initiating a preview session was altered to catch an exception that is thrown when the preview token has expired and subsequently return a simple html response with a descriptive error. Previously, in this situation, an uncaught exception would have occurred. View Helpers ------------ [](#view-helpers) ### URL Helper `$this->prismicUrl()` [](#url-helper-this-prismicurl) This view helper will generate a local URL using the link resolver. It's `__invoke()` method accepts - string - Treated as a Document ID - \\Prismic\\Document - \\Prismic\\Document\\Fragment\\LinkInterface ### Fragment Helper `$this->fragment()` [](#fragment-helper-this-fragment) This view helper operates on the current resolved document and provides an easy way of rendering simple fragments to views. It does not require the fully qualified fragment name, ie. `documentType.fragmentName` and instead you can pass it just `'fragmentName'`. `$this->fragment()->get('title');` will return the fragment object. `$this->fragment()->asText('title');` will return the text value of the fragment. `$this->fragment()->asHtml('title');` will return the HTML value of the fragment. CMS Managed Error Pages for Production -------------------------------------- [](#cms-managed-error-pages-for-production) **Error handling is wired in by default**… If you are using the Whoops error handler in development, you'll need to disable development mode `composer development-disable` to experience custom errors and 404's ### 404 Errors [](#404-errors) In the event of a 404, by default, Expressive will execute the `\Zend\Expressive\Handler\NotFoundHandler`. This module provides a pipeline in `\ExpressivePrismic\Middleware\NotFoundPipe` that initialises previews and experiments, locates a bookmarked error document in the Prismic API and renders that document to a template. To take advantage of pretty CMS managed 404's, first you will have to specify in your configuration the bookmark name for the error document in your repository and the template name to render like this: ``` return [ 'prismic' => [ 'error_handler' => [ 'template_404' => 'some::template-name', 'bookmark_404' => 'some-bookmark', ], ], ]; ``` Note that in development mode, 404's experienced after a route has matched, i.e. the Prismic Document can't be found, will cause a `DocumentNotFound` exception, thereby delegating to the Whoops error handler. ### Exceptions [](#exceptions) Presenting a pretty error page during errors and exceptions are handled in much the same way as 404's. Again, you'll need to configure a bookmark and a template name used to render the content. ``` return [ 'prismic' => [ 'error_handler' => [ 'template_error' => 'some::template-name', 'bookmark_error' => 'some-bookmark', ], ], ]; ``` The fallback *(i.e. when the error document cannot be retrieved from the api)* for exception situations is a simple plain text message stating that an error occurred. This fallback is not currently configurable to be anything more fancy than that. ### Health Score 26 — LowBetter than 41% of packages Maintenance0 Infrequent updates — may be unmaintained Popularity14 Limited adoption so far Community6 Small or concentrated contributor base Maturity68 Established project with proven stability Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~84 days Recently: every ~280 days Total 23 Last Release 1546d ago Major Versions 1.0.0 → 2.0.02017-03-29 2.0.1 → 3.0.02017-12-19 3.0.5 → 4.0.02018-06-12 3.x-dev → 4.3.12019-03-12 PHP version history (3 changes)2.0.0PHP >=7.0 3.0.0PHP >=7.1 4.5.0PHP >=7.3 ### Community Maintainers ![](https://www.gravatar.com/avatar/a6c21b0de8cc9938916a186f5f2ed0bee90a4e23e0b29cf7b9c18bfe99067f9b?d=identicon)[netglue](/maintainers/netglue) --- Top Contributors [![gsteel](https://avatars.githubusercontent.com/u/2803720?v=4)](https://github.com/gsteel "gsteel (171 commits)") --- Tags prismicprismiciozend-expressivezend-expressive2zend-expressive3 ### Code Quality TestsPHPUnit Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/netglue-expressive-prismic/health.svg) ``` [![Health](https://phpackages.com/badges/netglue-expressive-prismic/health.svg)](https://phpackages.com/packages/netglue-expressive-prismic) ``` ### Alternatives [cakephp/cakephp The CakePHP framework 8.8k19.1M1.7k](/packages/cakephp-cakephp)[laravel/octane Supercharge your Laravel application's performance. 4.0k24.7M205](/packages/laravel-octane)[aimeos/aimeos-laravel Cloud native, API first Laravel eCommerce package with integrated AI for ultra-fast online shops, marketplaces and complex B2B projects 8.7k220.7k5](/packages/aimeos-aimeos-laravel)[vonage/client-core PHP Client for using Vonage's API. 9319.5M23](/packages/vonage-client-core)[tempest/framework The PHP framework that gets out of your way. 2.2k31.1k12](/packages/tempest-framework)[flarum/core Delightfully simple forum software. 201.4M2.2k](/packages/flarum-core) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)