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.
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
Some will 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.
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
$entry = \Statamic\Facades\Entry::find('f6d5a87');
Each data type may have more methods for retrieving data. You can also find an entry by it’s slug or URI:
Entry::findBySlug('shoes', 'clothing'); Entry::findByUri('/clothing/shoes'); Entry::findByUri('/vetements/chaussures', 'french'); // For multisite
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
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 entry file.
Once you’re done, go ahead and save it.
Now it’ll be written to file. Nice.
When you are saving or creating your data instance, the
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
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() ->data(['title' => 'About us', 'subtitle' => 'We are awesome']) ->etc(); // and so on... $entry->save();
Make sure to use the
makemethod, 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 right class.