Data Retrieval and Manipulation
One of the most crucial aspects of extending a Content Management System is being able to retrieve the data and manipulate it. The Statamic API and it's related classes provide you with ways to handle these sorts of situations.
Consider the various aspects of Statamic: Pages, Entries, Terms, Globals, and Assets. They are all
Data. Data can have variables/fields that you can
Some of these are also
Content. Content can have URLs, slugs, publish statuses, etc.
Here’s the inheritance structure:
Data |-- Content | |-- Page | |-- Entry | |-- Term | `-- GlobalContent |-- Asset `-- User
You should retrieve data using our API methods. If you’ve used Laravel, it should feel similar to Eloquent. If it helps, try thinking of each Data type mentioned above as a Model. We have an API class for each of those.
For example, this will find a page with an ID of
Statamic\API\Page::find(1); // Returns an instance of \Statamic\Contracts\Data\Pages\Page
Like Laravel, if you’re expecting a collection of models, you will receive a collection. However, Statamic will give you a subclass like
EntryCollection which will do everything
Illuminate\Support\Collection does (docs), with a few more contextual methods at your disposal should you need them.
If you’re expecting a single model (like
Page::find(1) above), you’ll get the corresponding class.
Once you have a data instance, you can go to town on it.
This is like adding
foo: bar to the front-matter of the page file.
Once you’re done, go ahead and save it.
Now it’ll be written to file. Nice.
Of course, the data had to get there somehow. You can also create data using the corresponding API classes.
Each of them has a
create() method that will give you a factory class. You can use that factory to build up your object.
use Statamic\API\Page; $page = Page::create('/about') // The pages factory accepts a URI. ->order(2) ->published(true) ->with(['title' => 'About us', 'subtitle' => 'We are awesome']) ->get();
get() at the end is how you get your newly built object from the factory. Now you have a shiny new
Page. Keep in mind that it doesn’t exist anywhere until you
Note: Never manually do
new Page. Use the factories.
To add localized data to an object, first target it “
in” the locale.
$page->in('fr'); // returns a LocalizedData class
LocalizedData class simply holds a locale and the object, and will pass any actions onto the object while targeting that locale.
$page->in('fr')->set('foo', 'le bar');
All the different locales are stored on the object itself. So when it comes time to
save() it, Statamic will generate the appropriate files for you.
$page->save() would write both
fr.index.md for you.
Note: It’s worth noting that even though the
Data class can hold data in multiple locales, some data types are not (yet) capable of being localized.
Content is an extension of Data. Content is generally data that will be accessible on the front end. Pages, Entries, Taxonomy Terms, and Globals are all Content.
When we talk about URIs in Statamic, we are referring to the identifying part of the URL that comes after the root.
For example, a page that exists at
/carrot has a URI of
However you may have that page localized in Spanish as
/es/zanahoria. The URI is
/zanahoria. Notice that the locale prefix is omitted. This is because the root is
When retrieving data in Statamic using URIs, you should always use the default locale.
$uri = \Statamic\API\URL::getDefaultUri('es', '/zanahoria'); // returns /carrot
Similar to a URI, a URL is the location from the domain root.
Using the example above, the URLs would be
/es/zanahoria, for English and Spanish, respectively.
Absolute URLs (or permalinks) include the domain. They would be