Prismoquent

Installation

In order to install Prismoquent, you must first install Laravel. You can read up on the Laravel installation process over at Laravel.com/docs.

For those of you with Composer installed, simply install Laravel by executing composer create-project laravel/laravel . in your project directory.

Once Laravel is installed, you can install Prismoquent by adding "adamgoose\prismic-io": "dev-master" to your composer.json's "require" array.

Alternatively, you may use composer require adamgoose\prismic-io, providing dev-master as the version (or any other version from packagist).

Finally, simply add "Prismic" => "Adamgoose\PrismicIo\Model" to the aliases array in your /app/config/app.php file.

Configuration

To configure Prosmoquent, you have two options.

  1. Configure your Prismic.io repository globally in /app/config/prismic.php, or
  2. Configure your Prismic.io repositories in any particular model you plan to use as a Prismoquent model.

Global Prismic.io Repostiory Configuration

Configuring your Prismic.io Repositories in /app/config/prismic.php will provide a default API endpoint and application token to all of your Prismoquent models that do not have configuration present in the model itself. Your /app/config/prismic.php file might look like this:

<?php

return array(
  'endpoint' => 'https://<your-repository-id>.prismic.io/api',
  'token' => '<your-application-token>,
);

These global variables can be overridden at the model level.

Model-Level Prismic.io Repository Configuration

To configure your repository API endpoint and application token at the model level, simply define protected $endpoint and protected $token in your model. Your model (stored in /app/models/Document.php) might look like this:

<?php

class Document extends Prismic { 

  protected $endpoint = 'https://<your-repository-id>.prismic.io/api';
  protected $token = '<your-application-token>';

}

You may have multiple models that extend Prismic, each of which can have their own $endpoint and $token definitions.

Query Scope Configuration

Each model can have any of the following variables defined to limit the scope of the results returned from the Prismic.io API call:

  • protected $ref
  • public $collection
  • public $mask
  • public $tags
  • public $conditions

Each of these variables is explained below.

protected $ref

By defining the protected $ref in your model, you are telling Prismic.io that you would like to return the data from a particular release. By default, Prismoquent will use your master revision. This variable should only be defined if you plan to preserve the state of the website at a particular release manually.

Your release $ref IDs can be found easiest in the Prismic.io Repository API Browser (located at https://<your-repository-id>.prismic.io/api).

public $collection

Collections are defined in the Prismic.io repository, and are used as query scopes to limit the results by a set of masks and/or tags. If you utilize collections in your repository, this is a great way to compartamentalize your applicaton's models.

For example, a model named Article could utilize the collection articles and only return documents with the document mask article. Alternatively, a model named FeaturedArticle could utilize the collection featured and only return documents with the document mask article and the tag featured.

public $mask

Similar to public $collection, public $mask will limit the scope of the Prismic.io API query to return only documents using a particular mask.

For example, a model named Article could be limited to return only documents with the document mask article.

public $tags

The public $tags variable is an array of tags by which to limit the scope of the Prismic.io API query. It's important to note that by setting this variable, you are likely to limit the results substantially. It is recommended to use the tags(array $tags) method on your query at runtime if you don't plan to use the same $tags definition for each query.

public $conditions

The public $conditions variable is an associative array of predicated queries to be applied to the Prisimc.io API query. This array must contain any of keys (any other keys will be ignored):

  1. at
  2. any
  3. fulltext

Each of these keys will contain an array of query predicates. Each of the values in this array must contain two keys (any other keys will be ignored):

  1. key
  2. value (must be an array for "any" predicate queries)

An example might look like this:

  public $conditions = array(
    'at' => array(
      array(
        'key' => 'document.type',
        'value' => 'article',
      )
    ),
    'any' => array(
      array(
        'key' => 'document.tags',
        'value' => array(
          'article',
          'blog',
          'tutorial'
        ),
      ),
    ),
    'fulltext' => array(
      array(
        'key' => 'my.article.title',
        'value' => 'tutorial'
      ),
    ),
  );

While this example is impractical for production use, it is a great example of the structure and syntax of the public $conditions array.

public $pageSize

By defining the public $pageSize, you will set the default maxinum number or results returned by the API. This value defaults to 20.

public $page

By defining the public $page, you will set the default offset factor for the results returned by the API. The equation is as follows:

$offset = $page * $pageSize - $pageSize;

Therefore, if $pageSize = 20, and $page = 2, you will receive 20 results, beginning with the 21st result.

It is not recommended that you configure this variable at the model level, rather at runtime.

© 2013 dannenga., LLC

Adam's Blog