Prismoquent

Usage

To most Laravel developers, the concept of using a Model to manage the data-layer of your application is not too foreign. Since Prismic.io is not supported by Eloquent, nor is it served via MySQL, the data-layer implmenation of Prismic.io is not identical to Eloquent. However, we have tried our best to make the transition easy and quite seamless.

It's important to note that the calibur of your Prismoquent application lies in your hands: if you can build your Prismic.io repository in a strong way, your development will be nothing short of "hygge".

Accessing Your Repository

After you have configured a model to work with Prismoquent, you can begin building queries to access your repository. Let's consider the following model:

// app/models/Video.php
<?php

class Video extends Prismic { 

  public $mask = 'video';

}

Based on the definition of public $mask, we can be sure that any queries used with this model will return nothing but documents with a document mask video. Note: this can be overridden with the mask() query method.

To retreive all of the documents with a mask of video, one could declare the following query:

$videos = Video::get();

The get() method executes the query based on the public $collection, $mask, $tags, and $conditions defined. It will return a Collection object that contains several instances of the Video model, one for each document returned in the query. The Video model is smart enough to decipher what you are attempting to do when you call methods and get attributes from the model, whether it's building a query or accessing a particular document (this will make some sense later).

You can limit the results of your query at runtime by using various query methods.

ref($ref)

Calling the ref($ref) method on a query will declare which release of your repository will be queried. Omitting this method will default to the master release. Furthermore, this method can be called to override any value declared in your model for protected $ref.

$oldVideos = Video::ref('<your-ref-id>')->get();

collection($collection)

Calling the collection($collection) method on a query will delcare which collection in your repository to be queried. Collections are defined in your Prismic.io repository, and limit the results based on any number of masks and/or tags. This method can be called to override any value declared in your model for public $collection.

Since our Video model already contains a public $mask declaration, it wouldn't make much sense to use the collection($collection) method unless the collection limits the results based on tag only. Thus, let's say that a collection entitled featured limits the results to documents with the tags featured, feature, and +1. In this case, we could access this collection like so:

$featuredVideos = Video::collection('featured')->get();

mask($mask)

Calling the mask($mask) method on a query will declare which mask in your repository you would like to be queried. This method can be called to override any value declared in your model for public $collection.

Again, since we have declared the public $mask in our Video model, it wouldn't make much sense to use the mask($mask) method in production. However, let's say, for one instance, we would like only documents with the mask article for this one query. Here's how we'd accomplish that:

$articles = Video::mask('article')->get();

tags(array $tags)

Calling the tags(array $tags) method on a query will declare which tags will be included in your query. This method can be called to override any value declared in your model for public $tags.

Let's replicate the use-case that we discussed above for collection($collection). We want to return all videos with a tag of featured, feature, and/or +1.

$featuredVideos = Video::tags(array('featured', 'feature', '+1'))->get();

at($key, $value)

The at($key, $value) method is great for declaring one-off "at" predicated queries. This method can be called to append an "at" predicated query to any value declared in your model for public $conditions.

When defining $key, you may use any of the following keys (read more about predicated queries on the Prismic.io API Documentation):

  • document.id
  • document.tag
  • document.type
  • my.<your-document-mask>.<your-fragment-name>
$videos = Video::at('my.video.title', 'Test Video')->get();

Please note that this predicate query will significantly decrease the number of results. Use it wisely!

any($key, array $value)

The any($key, array $value) method is great for declaring one-off "any" predicated queries. This method can be called to append an "any" predicated query to any value declared in your model for public $conditions.

When defining $key, you may use any of the following keys (read more about predicated queries on the Prismic.io API Documentation):

  • document.id
  • document.tag
  • document.type
  • my.<your-document-mask>.<your-fragment-name>

In this example, we will emulate our implementation of the tags(array $tags) method demonstrated above.

$videos = Video::any('document.tags', array('featured', 'feature', '+1'))->get();

fulltext($key, $value)

The fulltext($key, $value) method is great for declaring one-off "fulltext" predicated queries, namely searching your repository. This method can be called to append a "fulltext" predicated query to any value declared in your model for public $conditions.

When defining $key, you may use any of the following keys (read more about predicated queries on the Prismic.io API Documentation):

  • document.id
  • document.tag
  • document.type
  • my.<your-document-mask>.<your-fragment-name>

In this example, we'll find any videos that contain the word apple in the description:

$videos = Video::fulltext('my.video.description', 'apple')->get();

pageSize($pageSize)

The pageSize($pageSize) method will define the maximum number of results that will be returned by the API. The other results can be retreived by using the page($page) method.

page($page)

The page($page) method will define the offset of the results returned by the API. See Installation for more details.

Helpers

We have added a few additional helpers to aid you in querying your repository.

find($id)

The find($id) method will find a particular document based on ID, and the defined predicated query (both at runtime and in your model definition). This method will not return a Collection, rather simply a single instance of your model (in our case, Video).

$video = Video::find('<your-video-id>');

findSlug($slug)

The findSlug($slug) method will find a particular document based on its slug, and the defined predicated query (both at runtime and in your model definition). This method will not return a Collection, rather simply a single instance of your model (in our case, Video).

$video = Video::findSlug('<your-video-slug>');

first()

The first() method will return the first result of the current query. This can be used either with or in-place of the get() method, since first() is also a method provided by the Collection class.

$video = Video::first();
//or
$video = Video::get()->first();

Working with Laravel's Collection class.

I will leave it to you to figure out what methods are available on the Collection class and how they work, but I will provide you with a link to the Collection API documentation!

http://laravel.com/api/class-Illuminate.Support.Collection.html

Working With a Document

Prismic.io has provided a php-kit, which is utilized by Prismoquent. However, we have added some features that will make you feel more comfortable working in your application.

The following examples will imply that we have already fetched a Video using $video = Video::first(), and that any fragment names are defined in the Prismic.io Repository Document Mask video.

Accessing a Fragment as Text

To obtain the URL of the video, we can simply get the attribute off of the model:

echo $video->url;

Accessing a Fragment as an Object

Since Prismic.io's php-kit serves each fragment as an object, we've made it easy to interact with the php-kit directly. You can use any of the methods defined in \Prismic\Document.

echo $video->getHtml('video.title');
echo $video->get('video.url')->asText();
echo $video->getSlug();

Extending Your Model's Behavior

You can also add public methods to the Video class and access them on each video. Let's consider the following model:

<?php

class Video extends Prismic { 

  public $collection = 'videos';

  public function link()
  {
    return "<a href='/videos/{{$this->getSlug()}}'>{{$this->title}}</a>";
  }

}

We can now call the link() method on an instance of Video to generate an HTML link:

$video = Video::first();
echo $video->link();

Document Relations

We're working hard to implement document relations, similar to the way Eloquent does it. This involves complicated queries and customizations to the php-kit. Stay tuned for updates!

© 2013 dannenga., LLC

Adam's Blog