Testing if something exists: is defined, length, is not null, is not empty
In your Twig templates, it is often good practice to test if a variable or value exists before trying to display it on your page.
There are several different tests you can use. At first glance, it can be quite confusing which is the appropriate test for your needs. In this article, we’ll take a look at several of your options and identify when each is appropriate to use in your templates.
For an extensive reference on the most common conditional checks and their expected results, see How to check if a variable or value exists using Twig.
As you prepare to output a variable in your template, you need to ask two questions: 1. Does the variable, which holds the value you want to use, exist? 2. If the variable exists, does the variable have a value for you to display?
How can you tell if a variable exists?
The most important thing to understand with the defined test is that it is not checking for the existence of your content, it’s checking for the existence of the variable that holds your content. In the next section, we will go into several ways to test for the existence of content within a variable.
To test if a variable exists, use the defined test.
{% if currentUser is defined %}
Display the member area
{% endif %}
To test if an attribute exists within a variable, use the defined test and be sure to use array syntax for your variable:
{% if currentUser['customFieldHandle'] is defined %}
Do something
{% endif %}
Use the defined test if there is any chance that you may be trying to access a variable or attribute that doesn’t exist.
Why would I write code if I know a variable doesn’t exist?
When you try to use a variable that doesn’t exist in your templates, Twig (or actually, the PHP code that Twig uses to process your template) will throw a warning. Craft does a good job at suppressing these warnings on your live site when devMode is disabled (but you have higher standards). Enable devMode to see all the warnings your code is throwing and get them corrected.
You don’t need to test for existence when you know a variable exists and just want to test if the variable has a value (such as a non-blank string, a non-empty array or object, a number greater than zero, or value that returns true).
However, variables may not exist for several reasons. Here’s a partial list of some scenarios when a variable may not exist:
- A variable may only get created when certain conditions are met on your page
- A variable may be optional if you are sharing code between multiple templates that have similar display needs, but slightly different variable requirements
- A variable that is displaying content from the database may become unavailable if project specifications change and someone updates the database without updating the related templates
- A variable may not exist if a child template can optionally set or override a value in a parent template
- A variable may not exist because you made a mistake
Writing robust code requires planning for what you don’t know and planning for potential changes in your projects that you cannot predict. Becoming comfortable with when you need to test for existence will help you understand the data you are working with more intimately; write clean, DRY code; and create less problems for yourself down the road.
How can you tell if a variable has a value?
There are more options to choose from when trying to determine if a variable has a value. We use the term value here to mean any type of content that your variable may contain. This includes strings, numbers, arrays, objects, booleans, and null.
The reference How to check if a variable or value exists using Twig gives an overview of four different types of conditional checks that you can use to test if your variable has the content you are looking for.
{# Variable Test #}
{% if variable %} ... {% endif %}
{# Length Filter Test
The length filter returns the number of items in an sequence or mapping or the length of a string. This can help you determine if a variable has a value or not. The results of length filter and empty tests are the same. #}
{% if variable|length %} ... {% endif %}
{# Null Test
The null test will tell you if a variable is null but can give you undesirable results when testing empty arrays or objects, as they will be considered not null #}
{% if variable is not null %} ... {% endif %}
{# Empty Test
Testing if a variable is empty is helpful if you don't know what type of value your variable might have. The empty test evaluates to true if the foo variable is null, false, an empty array, or an empty string #}
{% if variable is not empty %} ... {% endif %}
Making sure your variable exists and has a value
We can combine the above tests to first check if a variable exists and then confirm the variable has a value:
{% if pageTitle is defined and pageTitle %}
<h1>{{ pageTitle }}</h1>
{% endif %}
{% if pageTitle is defined and pageTitle is not empty %}
<h1>{{ pageTitle }}</h1>
{% endif %}
The above example ensures that we don’t accidentally output any HTML code unless our pageTitle variable exists and has a value.