Api
in package
This class embodies a connection to your Prismic repository's API.
Initialize it with Prismic::Api::get(), and use your Prismic::Api::form() to make API calls (read more in the kit's README file)
Table of Contents
- EXPERIMENTS_COOKIE = "io.prismic.experiment"
- Name of the cookie that will be used to remember the experiment reference
- PREVIEW_COOKIE = "io.prismic.preview"
- Name of the cookie that will be used to remember the preview reference
- VERSION = "5.0.0"
- Kit version number
- $accessToken : string|null
- The API's access token to be used with each API call
- $data : ApiData
- An instance of ApiData containing information about types, tags and refs etc
- $cache : CacheInterface
- The cache instance
- $httpClient : ClientInterface
- Guzzle HTTP Client
- bookmark() : string|null
- From a bookmark name, returns the ID of the attached document.
- bookmarks() : array<string|int, mixed>
- Returns the list of all bookmarks on the repository. If you're looking for a document from it's bookmark name, you should use the bookmark() function.
- defaultCache() : CacheInterface
- Use the APCu cache if APCu is activated on the server, otherwise fallback to the noop cache (no cache)
- form() : SearchForm
- Returns the form of type Prismic::SearchForm based on its name.
- get() : static
- This is the factory method with which to retrieve your API client instance
- getByID() : stdClass|null
- Search a document by its id
- getByIDs() : stdClass
- Return a set of document from their ids
- getByUID() : stdClass|null
- Search a document by its uid
- getCache() : CacheInterface
- Accessing the cache object specifying how to store the cache
- getData() : ApiData
- Accessing raw data returned by the /api endpoint
- getExperiments() : Experiments
- getHttpClient() : ClientInterface
- Accessing the underlying Guzzle HTTP client
- getRefFromLabel() : Ref|null
- Return the ref identified by the given label
- getSingle() : stdClass|null
- Get a single typed document by its type
- inExperiment() : bool
- Whether the current ref in use is an experiment
- inPreview() : bool
- Whether the current ref in use is a preview, i.e. the user is in preview mode
- master() : Ref
- Returns the master ref repository: the ref which is to be used to query content that is live right now.
- oauthInitiateEndpoint() : string
- Return the URL of the endpoint to initiate OAuth authentication.
- oauthTokenEndpoint() : string
- Return the URL of the endpoint to use OAuth authentication.
- previewSession() : string
- Return the URL to display a given preview
- query() : stdClass
- Shortcut to query on the default reference.
- queryFirst() : stdClass|null
- Return the first document matching the query Use the reference from previews or experiment cookie, fallback to the master reference otherwise.
- ref() : string
- Return the ref currently in use
- refs() : array<string|int, Ref>
- Returns all of the repository's references (queryable points in time)
- submit() : array<string|int, mixed>
- Submit several requests in parallel
- __construct() : mixed
- getExperimentRef() : string|null
- If an experiment cookie is set, return the ref as determined by \Prismic\Experiments::refFromCookie
- getPreviewRef() : string|null
- If a preview cookie is set, return the ref stored in that cookie
- prepareDefaultQueryOptions() : array<string|int, mixed>
- Given an options array for a query, fill the lang parameter with a default value
Constants
EXPERIMENTS_COOKIE
Name of the cookie that will be used to remember the experiment reference
public
mixed
EXPERIMENTS_COOKIE
= "io.prismic.experiment"
PREVIEW_COOKIE
Name of the cookie that will be used to remember the preview reference
public
mixed
PREVIEW_COOKIE
= "io.prismic.preview"
VERSION
Kit version number
public
mixed
VERSION
= "5.0.0"
Properties
$accessToken
The API's access token to be used with each API call
protected
string|null
$accessToken
$data
An instance of ApiData containing information about types, tags and refs etc
protected
ApiData
$data
$cache
The cache instance
private
CacheInterface
$cache
$httpClient
Guzzle HTTP Client
private
ClientInterface
$httpClient
Methods
bookmark()
From a bookmark name, returns the ID of the attached document.
public
bookmark(string $name) : string|null
You can then use this ID for anything, for instance to query with a predicate that looks like this [:d = at(document.id, "abcdefghijkl")]. Most starter projects embed a helper to query a document from their ID string, which makes this even easier.
Parameters
- $name : string
-
the bookmark name to use
Return values
string|null —the ID string for a given bookmark name
bookmarks()
Returns the list of all bookmarks on the repository. If you're looking for a document from it's bookmark name, you should use the bookmark() function.
public
bookmarks() : array<string|int, mixed>
Return values
array<string|int, mixed> —the array of bookmarks
defaultCache()
Use the APCu cache if APCu is activated on the server, otherwise fallback to the noop cache (no cache)
public
static defaultCache() : CacheInterface
Return values
CacheInterface —form()
Returns the form of type Prismic::SearchForm based on its name.
public
form(string $formName) : SearchForm
The intended syntax of a call is: api->form('everything')->query(query)->ref(ref)->submit(). Learn more about those keywords in Prismic's documentation on our developers' portal.
Parameters
- $formName : string
Return values
SearchForm —get()
This is the factory method with which to retrieve your API client instance
public
static get(string $action[, string $accessToken = null ][, ClientInterface $httpClient = null ][, CacheInterface $cache = null ][, int $apiCacheTTL = 5 ]) : static
If your API is set to "public" or "open", you can instantiate your Api object just like this: Api::get('https://your-repository-name.prismic.io/api/v2')
Parameters
- $action : string
-
The URL of your repository API's endpoint
- $accessToken : string = null
-
A permanent access token to use if your repository API is set to private
- $httpClient : ClientInterface = null
-
Custom Guzzle http client
- $cache : CacheInterface = null
-
Cache implementation
- $apiCacheTTL : int = 5
-
Max time to keep the API object in cache (in seconds)
Return values
static —getByID()
Search a document by its id
public
getByID(string $id[, array<string|int, mixed> $options = [] ]) : stdClass|null
Parameters
- $id : string
-
the requested id
- $options : array<string|int, mixed> = []
-
query options: pageSize, orderings, etc.
Return values
stdClass|null —the resulting document (null if no match)
getByIDs()
Return a set of document from their ids
public
getByIDs(array<string|int, mixed> $ids[, array<string|int, mixed> $options = [] ]) : stdClass
Parameters
- $ids : array<string|int, mixed>
-
array of strings, the requested ids
- $options : array<string|int, mixed> = []
-
query options: pageSize, orderings, etc.
Return values
stdClass —the response, including documents and pagination information
getByUID()
Search a document by its uid
public
getByUID(string $type, string $uid[, array<string|int, mixed> $options = [] ]) : stdClass|null
Parameters
- $type : string
-
the custom type of the requested document
- $uid : string
-
the requested uid
- $options : array<string|int, mixed> = []
-
query options: pageSize, orderings, etc.
Return values
stdClass|null —the resulting document (null if no match)
getCache()
Accessing the cache object specifying how to store the cache
public
getCache() : CacheInterface
Return values
CacheInterface —getData()
Accessing raw data returned by the /api endpoint
public
getData() : ApiData
Return values
ApiData —getExperiments()
public
getExperiments() : Experiments
Return values
Experiments —getHttpClient()
Accessing the underlying Guzzle HTTP client
public
getHttpClient() : ClientInterface
Return values
ClientInterface —getRefFromLabel()
Return the ref identified by the given label
public
getRefFromLabel(string $label) : Ref|null
Parameters
- $label : string
-
The label of the requested ref
Return values
Ref|null —a reference or null
getSingle()
Get a single typed document by its type
public
getSingle(string $type[, array<string|int, mixed> $options = [] ]) : stdClass|null
Parameters
- $type : string
-
the custom type of the requested document
- $options : array<string|int, mixed> = []
-
query options: pageSize, orderings, etc.
Return values
stdClass|null —the resulting document (null if no match)
inExperiment()
Whether the current ref in use is an experiment
public
inExperiment() : bool
Return values
bool —inPreview()
Whether the current ref in use is a preview, i.e. the user is in preview mode
public
inPreview() : bool
Return values
bool —master()
Returns the master ref repository: the ref which is to be used to query content that is live right now.
public
master() : Ref
Return values
Ref —the master ref
oauthInitiateEndpoint()
Return the URL of the endpoint to initiate OAuth authentication.
public
oauthInitiateEndpoint() : string
Return values
string —oauthTokenEndpoint()
Return the URL of the endpoint to use OAuth authentication.
public
oauthTokenEndpoint() : string
Return values
string —previewSession()
Return the URL to display a given preview
public
previewSession(string $token, LinkResolver $linkResolver, string $defaultUrl) : string
Parameters
- $token : string
-
as received from Prismic server to identify the content to preview
- $linkResolver : LinkResolver
-
the link resolver to build URL for your site
- $defaultUrl : string
-
the URL to default to return if the preview doesn't correspond to a document (usually the home page of your site)
Return values
string —the URL you should redirect the user to preview the requested change
query()
Shortcut to query on the default reference.
public
query(string|array<string|int, mixed>|Predicate $q[, array<string|int, mixed> $options = [] ]) : stdClass
Use the reference from previews or experiment cookie, fallback to the master reference otherwise.
Parameters
- $q : string|array<string|int, mixed>|Predicate
-
the query, as a string, predicate or array of predicates
- $options : array<string|int, mixed> = []
-
query options: pageSize, orderings, etc.
Return values
stdClass —queryFirst()
Return the first document matching the query Use the reference from previews or experiment cookie, fallback to the master reference otherwise.
public
queryFirst(string|array<string|int, mixed>|Predicate $q[, array<string|int, mixed> $options = [] ]) : stdClass|null
Parameters
- $q : string|array<string|int, mixed>|Predicate
-
the query, as a string, predicate or array of predicates
- $options : array<string|int, mixed> = []
-
query options: pageSize, orderings, etc.
Return values
stdClass|null —the resulting document, or null
ref()
Return the ref currently in use
public
ref() : string
In order of preference, returns the preview cookie, the experiments cookie or the master ref otherwise
Return values
string —refs()
Returns all of the repository's references (queryable points in time)
public
refs() : array<string|int, Ref>
Return values
array<string|int, Ref> —submit()
Submit several requests in parallel
public
submit() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —__construct()
private
__construct(ApiData $data[, string|null $accessToken = null ][, ClientInterface|null $httpClient = null ][, CacheInterface|null $cache = null ]) : mixed
Parameters
- $data : ApiData
- $accessToken : string|null = null
- $httpClient : ClientInterface|null = null
- $cache : CacheInterface|null = null
Return values
mixed —getExperimentRef()
If an experiment cookie is set, return the ref as determined by \Prismic\Experiments::refFromCookie
private
getExperimentRef() : string|null
Return values
string|null —getPreviewRef()
If a preview cookie is set, return the ref stored in that cookie
private
getPreviewRef() : string|null
Return values
string|null —prepareDefaultQueryOptions()
Given an options array for a query, fill the lang parameter with a default value
private
prepareDefaultQueryOptions(array<string|int, mixed> $options) : array<string|int, mixed>
Parameters
- $options : array<string|int, mixed>