Skip to content

Home

Jump to bottom
Ben Gurney edited this page Oct 14, 2020 · 26 revisions

Defining Documents

Each Custom Type within Prismic should have a corresponding document class in your project. Document classes make it easy for you to query your Prismic repository and organise your code around your content model.

All document classes must extend the base WebHappens\Prismic\Document class and define a protected static $type property that matches the API ID of the Custom Type in Prismic.

<?php

namespace App;

use WebHappens\Prismic\Document;

class Article extends Document
{
    /**
     * The 'API ID' of the Custom Type in Prismic.
     *
     * @var string
     */
    protected static $type = 'article';
}

Registering Documents

You must register all document classes in a Service Provider using the Prismic::documents() method. Typically this would happen in the register method of your App\Providers\AppServiceProvider.

use App\Article;
use WebHappens\Prismic\Prismic;

public function register()
{
    Prismic::documents([
        Article::class,
    ]);
}

Retrieving Documents

Once you have created a document class and its associated documents in Prismic, you are ready to start retrieving content from your repository.

Passing the correct ref (Master, Release, Draft) to the Prismic API is automatically handled for you by the package.

You may retrieve all documents for a Custom Type using the all method. For example, let's get all Article documents:

$articles = Article::all();

The documents will be returned inside a Laravel Collection object. If no documents are found, the Collection will be empty.

Adding Additional Constraints

Each document class is queryable, meaning you may use any of the methods defined in WebHappens\Prismic\Query to add additional constraints and return a subset of results:

Article::where('featured', true)
    ->orderBy('title')
    ->get();

The above is simply a more expressive way of doing:

Query::where('type', 'article')
    ->where('featured', true)
    ->orderBy('title')
    ->get();

You should review all of the methods available in the Querying section of the documentation.

Chunking Results

If you need to process a lot of documents, use the chunk method to retrieve a small "chunk" of the results and feed them to a given Closure for processing. This will conserve memory when working with large result sets. For example, let's work through every Article in chunks of 100 results at a time:

Article::chunk(100, function ($articles) {
    foreach ($articles as $article) {
        //
    }
});

The largest chunk size is 100 due to a limit on the Prismic API.

Single Type Documents

If you have created a 'single', rather than 'repeatable', Custom Type in Prismic, you may use the single method to retrieve it without having to add any constraints:

$homepage = Homepage::single();

Querying

The Prismic API has a wide range of predicates available for querying your content and the WebHappens\Prismic\Query class provides a convenient, fluent interface into this. For each predicate there is a corresponding where method, along with usage guidance in line with the Prismic documentation.

There are two types of field that can be queried:

Document fields

Available on all documents and typically includes type tags and id. Query constraints against these fields do not have to be scoped to a specific Custom Type.

Content fields

Added by you to your Custom Types. When querying a content field you must also ensure a type is defined.

The following example assumes a Custom Type with an API ID of 'person' and a Key Text field with an API ID of 'name'.

$query = Query::where('type', 'person')->where('name', 'John');

Or if you're accessing the query methods via a document class:

$query = Person::where('name', 'John');

Retrieving Results

To retrieve all results that match your query, you can call the get method.

$people = Query::where('type', 'person')->get();

Or if you just want to retrieve a single result, you can call the first method:

$person = Query::where('type', 'person')->where('name', 'John')->first();

Finding By ID

If you already know the ID of document(s) you'd like to retrieve, you should use the find and findMany methods rather than where methods.

The find method accepts a single document ID and will return an instance of that document. If no document exists with that ID, null will be returned.

$document = Query::find('WAjgAygABN3B0a-a');

The findMany method accepts an array of document IDs and will return a Laravel Collection containing instances of each document. Any documents that do not exist will be ignored. If no documents are found the Collection will be empty.

$documents = Query::findMany(['WAjgAygABN3B0a-a', 'Zr0u8hAcACAAbCKF']);

Where Predicates

where($field, $value)

This is an alias for whereAt.

whereAt($field, $value)

Argument Accepted values
$field string Field API ID

Document fields: type tags id
Content field types: UID Key Text Select Number Date Boolean
$value Single value (except for tags)
array Values (only for tags)

whereNot($field, $value)

Argument Accepted values
$field string Field API ID

Document fields: type tags id
Content field types: UID Key Text Select Number Date Boolean
$value Single value

whereAny($field, $values)

Argument Accepted values
$field string Field API ID

Document fields: type tags id
Content field types: UID Key Text Select Number Date
$values array Values

whereIn($field, $values)

Argument Accepted values
$field string Field API ID

Document fields: id
Content field types: UID
$values array Values

whereFulltext($field, $values)

Argument Accepted values
$field string Field API ID

Content field types: UID Key Text Rich Text Title Select
$values string Space separated search terms

whereHas($field)

Argument Accepted values
$field string Field API ID

Content field types: All except Group

whereMissing($field)

Argument Accepted values
$field string Field API ID

Content field types: All except Group

whereSimilar($id, $value)

Argument Accepted values
$id string The document ID
$value integer Maximum number of documents that a term may appear in to still be considered relevant

whereNear($field, $latitude, $longitude, $radius)

Argument Accepted values
$field string Field API ID

Content field types: GeoPoint
$latitude float Latitude of the centre of the search area
$longitude float Longitude of the centre of the search area
$radius float Radius of search in kilometres

whereLt($field, $value)

Argument Accepted values
$field string Field API ID

Content field types: Number
$value float Number value

whereGt($field, $value)

Argument Accepted values
$field string Field API ID

Content field types: Number
$value float Number value

whereInRange($field, $lowerLimit, $upperLimit)

Argument Accepted values
$field string Field API ID

Content field types: Number
$lowerLimit float Lower limit of the range
$upperLimit float Upper limit of the range
Clone this wiki locally