Upgrading from Craft 4

The smoothest way to upgrade to Craft 5 is to start with a fully-updated Craft 4 project. We recommend approaching the upgrade in three phases: preparation, a local upgrade, and rollout to live environments.

# Preparing for the Upgrade

Let’s take a moment to audit and prepare your project.

  • Your live site must be running the latest version (opens new window) of Craft 4;
  • The most recent Craft 4-compatible versions of all plugins are installed, and Craft 5-compatible versions are available;
  • Your project is free of deprecation warnings after thorough testing on the latest version of Craft 4;
  • All your environments meet Craft 5’s minimum requirements (the latest version of Craft 4 will run in any environment that meets Craft 5’s requirements, so it’s safe to update PHP and your database ahead of the 5.x upgrade):
    • PHP 8.2
    • MySQL 8.0.17+ using InnoDB, MariaDB 10.4.6+, or PostgreSQL 13+
  • You’ve reviewed the breaking changes in Craft 5 further down this page and understand that additional work and testing may lie ahead, post-upgrade;

Once you’ve completed everything above, you’re ready to start the upgrade process!

If your project uses custom plugins or modules, we have an additional extension upgrade guide.

# Performing the Upgrade

Like any other update, it’s essential that you have a safe place to test the upgrade prior to rolling it out to a live website.

These steps assume you have a local development environment that meets Craft 5’s requirements, and that any changes made in preparation for the upgrade have been deployed to your live site.

DDEV (opens new window) users should take this opportunity to update (opens new window) so that the craftcms project type reflects our latest recommendations.

In an existing DDEV project, you can change the PHP or database version with the config command…

ddev config --php-version=8.2
ddev config --database=mysql:8.0
ddev start

…or use ddev config --update to reapply project type defaults.

  1. Capture a fresh database backup from your live environment and import it.

  2. Make sure you don’t have any pending or active jobs in your queue.

  3. Run php craft project-config/rebuild and allow any new background tasks to complete.

  4. Capture a database backup of your local environment, just in case things go sideways.

  5. Note your current Temp Uploads Location setting in Settings → Assets → Settings.

  6. MySQL users: Add your database’s current character set and collation to .env. If you have always used Craft’s defaults, this will be:

    CRAFT_DB_CHARSET="utf8mb3"
CRAFT_DB_COLLATION="utf8mb3_general_ci"

    Read more about this process in the Database Character Set and Collation section, below.

  7. Edit your project’s composer.json to require "craftcms/cms": "^5.0.0" and Craft-5-compatible plugins, all at once.

    You’ll need to manually edit each plugin version in composer.json. If any plugins are still in beta, you may need to change your minimum-stability (opens new window) and prefer-stable (opens new window) settings.

    While you’re at it, review your project’s other dependencies! You may also need to add "php": "8.2" to your platform (opens new window) requirements, or remove it altogether.

  8. Run composer update.

  9. Make any required changes to your configuration.

  10. Run php craft up.

  11. MySQL users: Remove your database character set and collation settings from .env (and db.php—even if you didn’t modify it during the upgrade), then run php craft db/convert-charset.

Your site is now running Craft 5! If you began this process with no deprecation warnings, you’re nearly done.

Thoroughly review the list of changes on this page, making note of any features you use in templates or modules. Only a fraction of your site’s code is actually evaluated during an upgrade, so it’s your responsibility to check templates and modules for consistency. You may also need to follow any plugin-specific upgrade guides.

# Going Live

The Craft 5 upgrade can be run largely unattended during a routine deployment. Once you’ve performed the upgrade in your local environment and everything is working as expected, commit your updated composer.json, composer.lock, and config/project/ directory, as well as any template, configuration, or module files that required updates.

MySQL users must add the correct character set and collation settings to each remote environment for the duration of the upgrade.

Deploy your changes to each environment, then run php craft up.

If you added temporary character set or collation settings for the upgrade, remove them now, then run php craft db/convert-charset to apply Craft 5’s new defaults to all tables.

Read more about this part of the upgrade in the Database Character Set and Collation section, below.

# Cleanup + Optional Steps

# Entry Scripts

Older projects may use versions of vlucas/phpdotenv (opens new window) (the library that loads variables from your .env file) that depend on features deprecated in PHP 8.1. If you encounter errors during (or after) installation, change your vlucas/phpdotenv dependency in composer.json to ^5.6.0, then run composer update.

Along with this update, you’ll need to integrate changes from our starter project (opens new window)’s web/index.php script and craft executable. If you have done any low-level customization of Craft via bootstrap constants, make sure those values are preserved in the appropriate file(s)—constants shared between the two files can be moved to a common bootstrap.php file (opens new window).

# Breaking Changes and Deprecations

Features deprecated in Craft 4 may have been fully removed or replaced in Craft 4, and new deprecations have been flagged in Craft 5.

This list focuses on high-traffic, user-facing features. Review the complete changelog (opens new window) for information about changes to specific APIs, including class deprecations, method signatures, and so on.

# Configuration

The following settings have been changed.

# Database Character Set and Collation

MySQL 8.0 deprecated the utf8mb3 character set (opens new window), as well as the use of utf8 as an alias for utf8mb3 (opens new window). MySQL recommends utf8mb4 (opens new window) instead, and it’s expected that utf8 will become an alias for utf8mb4 in MySQL 8.1.

To ease that transition, Craft 5 is proactively treating utf8 as utf8mb4 for MySQL and MariaDB installs.

Explicitly setting the character set and collation ensures compatibility of new tables during the upgrade—afterwards, those settings can be scrubbed and the tables can be converted via Craft’s CLI. Here’s how this will look, in practice.

If you have never customized character set or collation settings for your database connection, set these variables in your .env file during the upgrade:

CRAFT_DB_CHARSET="utf8mb3"
CRAFT_DB_COLLATION="utf8mb3_general_ci"

If you are using these settings (either from .env or db.php), they can be left as-is, for now.

Once the upgrade is complete in an environment, convert your tables to utf8mb4 by removing the CRAFT_DB_CHARSET and CRAFT_DB_COLLATION environment variables (and clearing any charset and collation settings from db.php)…

# …or set them to Craft’s defaults…
CRAFT_DB_CHARSET="utf8mb4"
CRAFT_DB_COLLATION="utf8mb4_0900_ai_ci" # MySQL
CRAFT_DB_COLLATION="utf8mb4_unicode_ci" # MariaDB

…then running php craft db/convert-charset.

# Template Priority

The defaultTemplateExtensions config setting now lists twig before html, by default. This means that projects with templates that share a name (i.e. widget.twig and widget.html, in the same directory) may behave differently in Craft 5. Audit your templates/ directory for any overlap to ensure consistent rendering. If all your templates use one extension or another, no action is required!

This setting only affects rendering of templates in the front-end; the control panel will always use .twig files before .html.

# Volumes & Filesystems

Multiple asset volumes can now share a filesystem! However, they must be carefully arranged such that each volume has a unique and non-overlapping base path.

When selecting a filesystem, options that would result in a collision between two volumes are not shown. This means that you may need to adjust multiple volumes’ configuration in order to consolidate them into a single filesystem.

# Templates

# Variables

With the elimination of Matrix blocks as a discrete element type, we have removed the associated element query factory function from craft\web\twig\variables\CraftVariable (opens new window).

Old New
craft.matrixBlocks() craft.entries()

See the section on Matrix fields for more information about these changes.

# GraphQL

The reusability of entry types means that some GraphQL queries have changed.

  • GraphQL types corresponding to entry types no longer include their section names. In Craft 4, entries a section named “Ingredients” with the entry type “Ingredient” might have been represented in GraphQL as a type named ingredients_ingredient_Entry. That type would now be named ingredient_Entry.

    Entries can still be queried by section using the corresponding query type (i.e. ingredientsEntries) or the section argument for the generic entries query:


     






    query MyIngredients {
  ingredientsEntries {
    ... on ingredient_Entry {
      title
    }
  }
}

    The corresponding queries for entries nested within a Matrix field would look like this:


     







    query DifficultSteps {
  stepsFieldEntries(difficulty: "hard") {
    ... on step_Entry {
      title
      estimatedTime
    }
  }
}

  • The names of mutations targeting entries in a particular section remain unchanged, and still include the section and entry type handles, i.e: save_ingredients_ingredient_Entry and save_ingredients_ingredient_Draft.

  • Mutations directly targeting nested entries in Matrix fields will use a similar structure, but combining the field handle and entry type handle: save_stepsField_step_Entry.

  • When mutating a Matrix field value via GraphQL, the nested entries must be passed under an entries key instead of a blocks key:


     


     





















    mutation AddStep {
  save_recipes_recipe_Entry(
    title: "Yummy Bits and Bytes"
    summary: "Chocolate chip cookies that are out of this world!"
    steps: {
      entries: [
        {
          step: {
            difficulty: "hard",
            instructions: "Preheat oven to 20,000,000°F",
            estimatedTime: 120,
            id: "new:1"
          }
        }
        # ...
      ],
      sortOrder: [
        "new-first"
      ]
    }
  ) {
    title
    id
  }
}

# Elements & Content

Craft 5 has an entirely new content storage architecture that underpins many other features.

# Content Table

The content table has been eliminated! Elements now store their content in the elements_sites table, alongside other localized properties.

Content is stored as a JSON blob, and is dynamically indexed by the database in such a way that all your existing element queries will work without modification.

# Advanced Queries

When using custom fields in advanced where() conditions, you no longer need to manually assemble a database column prefix/suffix. Instead, Craft can generate the appropriate expression to locate values in the JSON content column:










 




{# Locate the field layout element that would save to the desired column: #}
{% set entryType = craft.app.entries.getEntryTypeByHandle('post') %}
{% set fieldLayout = entryType.getFieldLayout() %}
{% set sourceField = fieldLayout.getFieldByHandle('sourceMedia') %}

{% set entriesFromPhysicalMedia = craft.entries()
  .section('news')
  .andWhere([
    'or like',
    sourceField.getValueSql(),
    ['print', 'paper', 'press']
  ])
  .all() %}

This ensures that you are querying for the correct instance of a multi-instance field, each of which will store their content under a different UUID in their respective field layouts.

Craft already knows how to query against the appropriate instance of a field when using its handle as a query method, so this is only necessary for complex or compound conditions.

# Matrix Fields

During the upgrade, Craft will automatically migrate all your Matrix field content to entries. In doing so, new globally-accessible fields will be created with a unique name:

{Matrix Field Name} - {Block Type Name} - {Field Name}

These fields are then assigned to new entry types that replace your existing Matrix block types.

Field labels and handles are retained, within their field layouts—even if they collide with other fields in the global space!

Queries for nested entries will be largely the same—equivalent methods have been added to craft\elements\db\EntryQuery (opens new window) to enable familiar usage. The .owner() method still accepts a list of elements that the results must be owned by, and the field() and fieldId() methods narrow the results by those belonging to specific fields.

Values passed to the type() method of entry queries may require updates, as migrated entry types can receive new handles. For example, a Matrix field that contained a block type with the handle gallery might conflict with a preexisting entry type belonging to a section; in that event, the new entry type for that block would get the handle gallery1 (or potentially gallery2, gallery3, and so on, if multiple similar Matrix fields are being migrated).

Visit Settings → Entry Types to check if any handles appear to have collided in this way, then review and update templates as necessary.

# Consolidating Fields

We plan to introduce a console command to handle merging similar fields. There is no harm in running your project with extra fields for a time after upgrading.

# Eager-Loading

Eager-loading has been dramatically simplified for most sites. You no longer need to tell Craft which relational fields to load via the .with() query method—instead, call .eagerly() on any query that may result in an N+1 problem to automatically trigger eager-loading:

{% set articles = craft
    .entries()
    .section('blog')
    .with([
        ['featureImage'],
    ])
    .all() %}

{% for article in articles %}
  {% set image = article.featureImage|first %}
  {% if image %}
    {{ image.getImg() }}
  {% endif %}
{% endfor %}

This feature does have some limitations, though. While it will work for all elements connected via a relational or Matrix field, you will still need to explicitly eager-load native attributes like entries’ author (and now authors, plural) or assets’ uploader. Craft can only detect eager-loading opportunities when the original attribute or value is an element query. The two strategies can be safely combined, though:

{% set articles = craft
    .entries()
    .section('blog')
    .with([
      ['author'],
    ])
    .all() %}

{% for article in articles %}
  {# Lazily-eager-loaded relation: #}
  {% set image = article.featureImage.eagerly().one() %}

  {% if image %}
    {{ image.getImg() }}
  {% endif %}

  {# Explicitly eager-loaded element: #}
  <span>{{ article.author.fullName }}</span>
{% endfor %}
Eager-Loading Elements
Read more about opportunities to optimize your templates with automatic and manual eager-loading.

# Assets

# Reusable Filesystems

Filesystems can now be shared by multiple asset volumes, so long as each volume has a unique and non-overlapping base path. The assets page has more information on this new behavior.

# Temporary Filesystem

The new tempAssetUploadFs general config setting has replaced the Temp Uploads Location setting in the Settings → Assets → Settings screen. If you noted a custom asset volume in the upgrade process, you will need to follow these steps to set up a distinct filesystem for temporary uploads. Otherwise, Craft will use the legacy behavior and fall back on an instance of craft\fs\Temp (opens new window), which puts temporary uploads in a folder in your local storage/ directory.

Load-balanced or ephemeral environments that rely on a centralized storage solution should define a temporary upload filesystem using the steps below.

The location of temporary uploads is now defined by way of a filesystem instead of a volume:

  1. Create a new filesystem by visiting Settings → Filesystems, giving it an appropriate Name and Handle (users will not see this, so something like “Temporary” or “Scratch” is fine).
  2. Set the Base Path to agree with the old volume, keeping in mind that previously, its subpath and its filesystem’s base path were combined.
  3. Add the handle you chose to your general config file or define a CRAFT_TEMP_ASSET_UPLOAD_FS environment override.

A filesystem designated by your tempAssetUploadFs setting cannot be reused for volumes or image transforms, so it will not appear in filesystem selection menus. If you elect to define the temporary uploads filesystem handle via an environment variable, be sure and add it to your other environments as well!

# Plugins and Modules

Plugin authors (and module maintainers) should refer to our guide on updating Plugins for Craft 5.