Data Retrieval and Manipulation

Consider the various aspects of Statamic: Entries, Terms, Globals, and Assets. They are all Data. Data can have variables/fields that you can get, set, etc.

Facade Primer

In most cases, the first point of contact with Statamic functionality will be through a Facade.

You can find more details on which ones to use later, but you will find them all in the Statamic\Facades namespace. Of course there are exceptions, but in most cases you will be looking for a Facade.

Each facade will proxy method calls to another class. You can see which class by looking for the getFacadeAccessor method.

Some will be simple, direct class mappings, like the YAML facade.

Statamic\Facades\YAML::parse();
// This calls the `parse` method on an instance of `Statamic\Yaml\Yaml`

Some reference a contract, which could change depending on how an application is configured, like the Entry facade. This class references the EntryRepository contract, which by default is bound to the Stache implementation, but could be changed to use databases, etc.

Statamic\Facades\Entry::make();
// This calls the `make` method on an instance of `Statamic\Contracts\Entries\EntryRepository`
// By default it's `Statamic\Stache\Repositories\EntryRepository`, but could change.

The facades will have a @see annotation in their docblock to give you a hint on where to look.

Retrieving Data

You should retrieve data using Facade 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 a Facade for each of those.

For example, this will find an entry with an ID of f6d5a87.

$entry = \Statamic\Facades\Entry::find('f6d5a87');

Each data type may have more methods for retrieving data. For example, you can find an entry by its URI.

Entry::findByUri('/clothing/shoes');
Entry::findByUri('/vetements/chaussures', 'french'); // For multisite

Most of them also have dedicated query builders which you can use with the query method. Then you may craft a query just like Laravel:

Entry::query()
    ->where('collection', 'clothing')
    ->where('slug', 'shoes')
    ->first();

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 you’ll get the corresponding class. (In the example above, you’ll get a Statamic\Entries\Entry instance).

Once you have your objects, you may get data out of them in a handful of ways.

Manipulating Data

Once you have a data instance, you can go to town on it.

$entry->set('foo', 'bar');

This is like adding foo: bar to the front-matter of the entry file.

Want to change nested data? That works too.

Since you can only set the top-level field, you’ll need to get the existing top-level value, update the nested part, and then re-set the top-level field again.

$values = $entry->get('top_level_value');
$values[0]['nested_value'] = 'foo';
$entry->set('top_level_value', $values);

Once you’re done, go ahead and save it.

$entry->save();

Now it’ll be written to file. Nice.

Events

When you are saving or creating your data instance, the EntrySaving, EntryCreated and the EntrySaved events are dispatched. In some cases, you would rather suppress those events. For example, to prevent causing an infinite loop of EntrySaved events.

$entry->saveQuietly();

Similarly, when deleting data, the EntryDeleting and EntryDeleted events are dispatched. To surpress those events, use the deleteQuietly method:

$entry->deleteQuietly();

Creating Data

Of course, the data had to get there somehow. You can also create data using the corresponding facades.

Each of them has a make method that will give you a new instance. Once you have an instance, you can manipulate it using various methods the same way as if it already existed. Most of the time, these are chainable to give you a nice fluent interface:

use Statamic\Facades\Entry;
 
$entry = Entry::make()
            ->published(true)
            ->data(['title' => 'About us', 'subtitle' => 'We are awesome'])
            ->etc(); // and so on...
 
$entry->save();

Hot Tip!

Make sure to use the make method, rather than simply new’ing up a class. For example, if a user has customized their application to store entries in a database, they will have a different Entry class. Using Entry::make() will make sure to get the correct class.

Getting Field Data

More often than not, you’ll want to use the “standard” way of getting data out of items like entries. Other less common ways are explained further down the page.

Standard

You can use property access to get a single field’s augmented value:

id: 123
title: My post
content: |
  # Heading
  The post content.
related_posts: [2, 3, 4]

$entry->id; // 123
$entry->title; // "My post"
$entry->content; // "<h1>Heading</h1><p>The post content.</p>
$entry->related_posts; // EntryCollection([Entry, Entry, Entry])

This will be the value of the field, factoring in inheritance, and will perform any required augmentation.

Relationships

Any fields with query builders (like the Entries fieldtype) will be available using the method for the corresponding field. This will allow you to further refine your results.

$entry->related_posts() // EntryQueryBuilder
      ->where('published', true)->get(); // EntryCollection([Entry, Entry])

As shown in the earlier example, if you use the property, it will just give you the results without you needing to manually complete the query.

$entry->related_posts; // EntryCollection([Entry, Entry, Entry])

Data

This would be the data defined directly on the item, like what you’d find in an entry’s YAML front-matter. (Some specific keys may be stripped out, like an entry’s id).

id: 123
title: My post
content: |
  # Heading
  The post content

$entry->data();
// Illuminate\Support\Collection([
//    'title' => 'My post',
//    'content' => "# Heading\nThe post content'
// ])

You can use the get method to get a single field’s data.

$entry->get('title') // 'My post'
$entry->get('content') // "# Heading\nThe post content"

This does not factor in inheritance or augmentation.

Values

The “values” are similar to data, except they will also inherit from any originating items. For example, if an entry has been localized from another entry.

id: 123
title: My post
content: The post content
image: post.jpg

id: 456
origin: 123
title: My localized post

$entry->values();
// Illuminate\Support\Collection([
//    'title' => 'My localized post',
//    'content' => 'The post content'
//    'image' => 'post.jpg',
// ])

You can use the value method to get a single field’s value.

$entry->value('title'); // 'My localized post'
$entry->value('image'); // 'post.jpg'

Augmented Values

If you want to get the Value instances for the fields, you may use the following methods.

Hot Tip!

Most of the time, you probably don’t need to reach for these. Using property access will get the underlying augmented value.

$entry->title; // "Post title"
$entry->image; // Asset
$entry->related_posts; // EntryCollection(Entry, Entry, ...)

You can get a single augmented value instance:

$instance = $entry->augmentedValue('image'); // Statamic\Fields\Value({ raw: "post.jpg", fieldtype: "assets" })
$instance->value(); // Asset

All the available augmented values. Each item in the returned collection will be a Value instance.

$entry->toAugmentedCollection();
// AugmentedCollection([
//    'title' => Value('The post title'),
//    'content' => Value("# Heading\nSome content"),
//    'collection' => Value(Statamic\Entries\Collection),
//    'uri' => Value('/posts/my-post'),
//    ...etc...
// ])

Or a subset of augmented values:

$entry->toAugmentedCollection(['title', 'collection']);
// AugmentedCollection([
//    'title' => Value('The post title'),
//    'collection' => Value(Statamic\Entries\Collection),
// ])

The toAugmentedArray method does the same as toAugmentedCollection, except that it returns an array.

Checking for data changes

Statamic provides isDirty, isClean, and getOriginal methods to let you see what data has been changed in your item since it was originally retrieved.

The isDirty method checks if any of the item’s data has been changed since it was last saved. You may pass a specific attribute name or an array of attributes to the isDirty method to determine if any of the attributes are “dirty”. The isClean method will determine if an attribute has remained unchanged since the item was retrieved. This method also accepts an optional attribute argument:

$entry->title; // "Post title"
$entry->image; // "/path/to/image.jpg"
 
$entry->title = 'New Title';
 
$entry->isDirty(); // true
$entry->isDirty('title'); // true
$entry->isDirty('image'); // false
$entry->isDirty(['image', 'title']); // true
 
$entry->isClean(); // false
$entry->isClean('title'); // false
$entry->isClean('image'); // true
$entry->isClean(['image', 'title']); // false
 
$entry->save();
 
$entry->isDirty(); // false
$entry->isClean(); // true

The getOriginal method returns an array containing the original attributes of the item regardless of any changes to the item since it was retrieved. This method also accepts an optional attribute argument:

$entry->title; // "Post title"
$entry->image; // "/path/to/image.jpg"
 
$entry->title = 'New Title';
 
$entry->getOriginal('title'); // "Post title"
$entry->getOriginal(); // ["Post title", "/path/to/image.jpg"]