Craft CMS Hard Mode

This tip originates from the official Craft CMS Knowledge Base. It’s somewhat hidden under the upgrade guide for Craft CMS 4, but it’s incredibly useful beyond that context too.

Why use hard mode?

In the Craft CMS control panel, warnings are displayed for features, tags, or query parameters that will no longer work in future updates. You can also enable the debug toolbar in the frontend to see these warnings. However, these warnings only appear after the fact—when the code is already in place.

By enabling "hard mode," you can catch these deprecation warnings as they happen during development, treating them like errors that stop the process. This proactive approach helps prevent technical debt, keeps your codebase future-proof, and saves you from nasty surprises during updates.

Think of it as Craft CMS turning into your stricter but caring coach—keeping you in line while you code!

Steps to enable hard mode

To enable hard mode, add the following code to your config/app.php file:

use craft\helpers\App;

return [
  'components' => [
    'deprecator' => [
      // Throw exceptions on deprecation warnings
      'throwExceptions' => App::parseBooleanEnv('$HARD_MODE') ?? false,
    ],
  ],
];

Don’t forget to add the environment variable in your .env file:

HARD_MODE=true

The use of an environment variable allows you to avoid enabling hard mode on production. We don't want to throw errors in production environments when the site could still render perfectly fine.

Why this matters

• Avoid technical debt: Stay ahead of changes and ensure your codebase remains maintainable.
• Save time later: Catch issues during development instead of during a rushed update.
• Team efficiency: Ensures all developers address warnings before merging code.

Enabling hard mode might seem a bit harsh at first, but it will make your development process smoother and your project future-proof. Your code will thank you later!