How to use the craft.entries tag in Twig and PHP

Craft provides several powerful options for you to retrieve content in templates and in plugins. Let's take a look how to query our Entries and other Elements in Twig and in PHP.

Retrieving Craft Entries content in Twig

In your Twig templates, there are multiple ways you can retrieve your Entries content.

Chained Parameters

{# Access your Entries using chained parameters. #}
{% set entries = craft.entries.section('sectionHandle').limit(10) %}

{# By default, the craft.entries tag uses the find() method.
   The line above and this line will behave in the same way. #}
{% set entries = craft.entries.section('sectionHandle').limit(10).find() %}

{# If you only need to fetch a single Entry from the database, 
   you can use the first() or last() function #}
{% set entries = craft.entries.section('sectionHandle').limit(10).first() %}

{% set entries = craft.entries.section('sectionHandle').limit(10).last() %}

{# If you prefer, you can place each parameter on it's own line #}
{% set entries = craft.entries
	.section('sectionHandle')
	.limit(10) 
%}

Object syntax

Craft also allows you to use Object Syntax for retreiving your Elements. You can choosed Chained Parameters or Object Syntax based on your preference or what works best for your situation.

{# With Object Syntax, you can define your parameters first #}
{% set params = {
  section:    'sectionHandle',
  limit:      10
} %}

{# And then use your parameters by passing them to your Entries tag #}
{% set entries = craft.entries(params) %}

{# You could also just set your Object parameters directly within your Entries tag  #}
{% set entries = craft.entries({
  section:    'sectionHandle',
  limit:      10
}) %}

{# Object Syntax is useful if you need to reuse parameters #}
{% set params = { section: 'sectionHandle' } %}

{% set entries = craft.entries(params) %}
{% set totalEntries = craft.entries(params).total() %}

{# You can combine Object Syntax together with Chained Parameters #}
{% set entries = craft.entries(params).limit(10) %}

What is the ElementCriteriaModel and how does it relate to our EntryModel?

When you define the content you want to retreive from your database - whether you know it or not - you're building an ElementCriteriaModel. The ElementCriteriaModel sounds intimidating, but is easier to use than it sounds. You can think of the ElementCriteriaModel as a set of rules about what you want to retrieve from the database – specifically rules about the type of Elements you want to retrieve. In all of our above examples we've been looking at the Entry Element, but we can also use the ElementCriteriaModel to define criteria about other types of Elements we want to retrieve as well.

When we define our rules about which Entry Elements we want to grab from the database, we use the craft.entries tag. If we want to retrieve User Elements, we would use the craft.users tag. For Asset Elements, use the craft.assets tag, and so on.

We build an ElementCriteriaModel before we retrieve data from the database. After our data is returned, we get an Element Model or array of Element Models to work with. In our example above, our Element Model is an EntryModel. If we were querying User Elements, it would be a UserModel. If we were querying Asset Elements it would be an AssetFileModel.

Let's review an example from the Entry tag we've been exploring above:

{% set entries = craft.entries.section('sectionHandle').limit(10) %}

{% for entry in entries %}
  <a href="{{ entry.url }}">{{ entry.title }}</a>
{% endfor %}

A closer look at the code:

Retrieving Craft Entry content in PHP

You can also retrieve Entry content from your database in a Craft plugin using PHP. To do so, we use the same method that is used behind the scenes when we use the craft.entries tag in our Twig templates.

// We can create the same query we saw above in our Twig templates like this
$criteria = craft()->elements->getCriteria(ElementType::Entry);
$criteria->section = 'sectionHandle';
$criteria->limit = 10;

// Get all entries that match
$entries = $criteria->find();

// Get the first entry that matches
$firstEntry = $criteria->first();

Here are a few more examples with other Element Types to illustrate the similarities between using the ElementCriteriaModel to query each Element Type.

Query Category Elements from the Database

// Retrieve Categories from the Category Group "flora"
$criteria = craft()->elements->getCriteria(ElementType::Category);
$criteria->group = 'flora';

$categories = $criteria->find();

Query GlobalSet Elements from the Database

// Retrieve all fields in our Global Set named "header"
$criteria = craft()->elements->getCriteria(ElementType::GlobalSet);
$criteria->handle = 'header';

// Each Global Set is a single Element, so we can retrieve our data by calling first()
$headerGlobals = $criteria->first();

Query MatrixBlock Elements from the Database

// Retrieve all Matrix Block Elements associated with a specific Field
$criteria = craft()->elements->getCriteria(ElementType::MatrixBlock);
$criteria->fieldId = $fieldId;

$matrixBlocks = $criteria->find();

To build your own Element queries, create an ElementCriteriaModel for the Element Type you wish to query, and define the criteria that you want to use to query the database. You can explore the available parameters you can add to your queries via the models in the Variables section of the Templating Reference in the Craft docs or via the specific Element Models in the Class Reference.

Comparing the craft.entries tag in templates and craft()->elements->getCriteria() in PHP

While we've kept the above examples simple, here is a comparison of a more advanced craft.entries Twig Tag and equivalent code in PHP.

{# Retrieve the most recent 10 entries from the 'articles' section
   that have a postDate before today and which are authored by 
   the author who matches authorId '1' #}
{% set entries = craft.entries({
  section: 'articles',
  authorId: 1,
  postDate: '<=' ~ (now.date),
  order: 'postDate DESC',
  limit: 10
}) %}

// Do the same in PHP
$criteria = craft()->elements->getCriteria(ElementType::Entry);
$criteria->section = 'articles';
$criteria->authorId = 1;
$criteria->postDate = '<=' . date("Y-m-d");
$criteria->order = 'postDate DESC';
$criteria->limit = 10;

$entries = $criteria->find();