The Mijingo Blog

Latest news, updates, free tutorials, and more from Mijingo.

11 Things You Need to Know About Craft 3

by Ryan Irelan

There are dozens of changes to Craft in version 3 but below I’ve compiled the eleven things you need to know to have a smooth transition from Craft 2 to Craft 3.

Ready? Let's go.

1. Installable via Composer

If you installed Craft 3 during the beta period then you will know that Craft can now be installed with Composer. A nuisance to some but a big step up for others, Composer will make it easy to manage dependencies in Craft.

So how do you install Composer? This video walks through the process:

Note: The final release of Craft 3 will allow a non-Composer installation.

After you have Composer installed, you are ready to install Craft 3.

Follow the instructions in this video to get your first Craft 3 installation going:

Need help upgrading a Craft 2 site to Craft 3? Watch this video

2. Uses Twig 2

Craft 3 uses Twig 2. This update to Twig is, for the most part, a clean-up release. Here are a few important things to know about Twig 2 with regards to Craft:

  • Twig 2 Requires PHP 7 (and so does Craft 3)
  • Your current templates should work as-is with Twig 2. There is some deprecated template code but that’s related to Craft services, not Twig.
  • Twig slightly changed how macros are handled. All macros defined in-template must be imported explicitly in each template in which you want to use them (including “included” templates). See the docs for more information on macros.

3. Access to Craft service APIs in your templates

As of Craft 3 you now have access to the Craft service APIs right inside of your templates. Previously, Craft made available some special template functions that made some of the service APIs available.

Many of those template functions are going away in Craft 3 in favor of using the new service API access.

These template functions were mostly just Twig variables that exposed the data via an existing function. So instead of doing that we just get direct access to the function itself.

There is no PHP allowed in Craft templates, so previously if you wanted to access something in the backend of Craft you had to use a plugin.

Using a plugin is still a good idea if you have a significant amount of features you need to achieve, but for simple one-off things, having access to the Services inside of your template is going to be a game changer.

Here’s a look at how you can use this new functionality in your templates:

4. Multi-site Support

Another new feature in Craft 3 is multi-site. This was a popular feature when it was first announced but there was some confusion about it so let’s clear things up.

The Craft 3 multi-site feature allows you to handle multiple sites of content right from the Craft control panel. This could be a multi-language site, where there’s a different version of the site for different languages, or multiple sites with similar content (like micro sites for product lines).

Note: this feature is an enhancement of and replaces Locales in Craft 2.

Here's a walk-thru of using the new multi-site feature:

5. Better Debugging

The Yii Debug Toolbar is a new feature in Craft 3 that allows you to have a constant toolbar at the bottom of your front-end and control panel pages.

This toolbar gives you access to important debugging information including items that aren’t specific to Craft.

Here’s how it works and how you enable it:

6. Command Line Interface

When you are done installing Craft with Composer, you'll notice a little message at the end, just before the new command prompt, encouraging you to use the Craft setup command.

Craft 3 offers a new way to set up the site, which replaces the normal set up you do via the web browser.

So, why is this important?

  • Keeps you right in the terminal after installing
  • Possible to script the setup process--maybe part of a bigger routine where you're installing and setting up a new installation.
  • It automates the populating of your .env file for the site's database connection.

The craft CLI offers several options, but we're only going to concern ourselves right now with setup command.

Here’s how it works:

7. Hash Redirect Parameters

Back in version 2.5, Pixel & Tonic introduced a hash filter and later in a 2.6 release the ability to require hashing of the redirect parameters that are set in forms (like when you sign in or sign up).

They introduced this enhancement to make Craft more secure. There is a potential Denial of Service security issue with in -the-clear form data. In the example of the redirect parameter, this could allow someone to redirect the user to something other than what is specified in the hidden form element.

In Craft 3, however, the hashing of redirect parameters is required.

Here’s an overview of how that works:

8. Always use .all()

In Craft 2, we might do something like:

{% for entry in craft.entries.section('news') %}
       {{ entry
.title }}
% endfor %

We iterate over the element query directly. Behind the scenes Craft knew we wanted that actual data so it calls find() for us automatically.

Based on a problem discovered with Twig’s loop variables and Craft, the Craft team decided to just force the usage of .all() and deprecate the usage of iterating over the element query without explicitly calling for the results.

What does this mean?

We need to now use all() on every element query in Craft 3. If you don’t it will still work but you’ll receive a deprecation error in your log (and it’ll break in Craft 4).

So the above code is now:

{% for entry in craft.entries.section('news').all() %}
       {{ entry
.title }}
% endfor %

Here’s a hands-on review of this:

9. Use one() instead of first()

In Craft 3 the first() method to execute an Element Query is now deprecated in favor of one(). The new method will return the same thing as first() (the first matching element) and also return null if there are no matches.

So, this code:

{set entry craft.entries.section('news').first() %}
    {{ entry
.title }} 

Will now need to be written as:

{set entry craft.entries.section('news').one() %}
    {{ entry
.title }} 

10. Support for PostgreSQL

You hatin’ on MySQL or maybe your systems admininistrator thinks PostgreSQL is better? Now you can run Craft off a PostgreSQL database server.

11. Remote Assets are Now Plugins

Remote Assets Volumes (they’re called Volumes in Craft 3) now require a free, third-party plugin. The default installation of Craft only includes Local Volume support.

Until the Craft Plugin Store is available, you can download the Remote Volumes plugins from their Github repositories:

Is that it?

Well, that’s 11. But if you want even more here’s a big list of changes from Craft 2 to Craft 3.

Filed Under: Craft CMS