Upgrading Craft CMS to 3.4

Having tried dozens of content management systems (CMS) over the years including rolling my own, by far the best I've found has been Craft. Intuitive to use and extremely flexible from both a development and end user point of view it is a no brainer to recommend it for clients.

It is also under active development regularly releasing new features and enhancements so when version 3.4 was recently launched I couldn't wait to start updating client websites.

Whilst the auto updating function normally works like a charm there are sometimes snags, especially when it comes to a significant upgrade such as this. Credit to Pixel and Tonic the first issue with auto updates was resolved within 24 hours and I was able to start updating websites.

However, in the release notes there was this note:

“Element search indexing is a little smarter in Craft 3.4. It’s recommended that you resave all your entries from your terminal after updating.”

./craft resave/entries --update-search-index

I tried running this command but on a few websites I received the following error:

Uncaught Error: Call to undefined method Dotenv\Dotenv::create()

Upon investigating I found the cause to be the version of phpdotenv which was being used in the Craft installation. I'd assumed that this would have been automatically updated each time Craft was but apparently not.

In order to resolve I updated the project config.json file as follows:

"vlucas/phpdotenv": "^2.4.0”
changed to:
"vlucas/phpdotenv": "^3.4.0"

I then ran composer update which caused another issue. The website, front end and control panel, became unaccessible. The issue was with the index.php file in the webroot.

It was a simple matter of replacing this file with the latest version or replacing the code in the file. The issue is the different code on line 13:

<?php
/**
 * Craft web bootstrap file
 */

// Set path constants
define('CRAFT_BASE_PATH', dirname(__DIR__));
define('CRAFT_VENDOR_PATH', CRAFT_BASE_PATH.'/vendor');

// Load Composer's autoloaderr
require_once CRAFT_VENDOR_PATH.'/autoload.php';

// Load dotenv?
if (file_exists(CRAFT_BASE_PATH.'/.env')) {
    (new Dotenv\Dotenv(CRAFT_BASE_PATH))->load();
}

// Load and run Craft
define('CRAFT_ENVIRONMENT', getenv('ENVIRONMENT') ?: 'production');
$app = require CRAFT_VENDOR_PATH.'/craftcms/cms/bootstrap/web.php';
$app->run();

<?php
/**
 * Craft web bootstrap file
 */

// Set path constants
define('CRAFT_BASE_PATH', dirname(__DIR__));
define('CRAFT_VENDOR_PATH', CRAFT_BASE_PATH.'/vendor');

// Load Composer's autoloader
require_once CRAFT_VENDOR_PATH.'/autoload.php';

// Load dotenv?
if (class_exists('Dotenv\Dotenv') && file_exists(CRAFT_BASE_PATH.'/.env')) {
    Dotenv\Dotenv::create(CRAFT_BASE_PATH)->load();
}

// Load and run Craft
define('CRAFT_ENVIRONMENT', getenv('ENVIRONMENT') ?: 'production');
$app = require CRAFT_VENDOR_PATH.'/craftcms/cms/bootstrap/web.php';
$app->run();

The websites then run as normal so I tried updating the search index as recommended:

./craft resave/entries --update-search-index

This threw the same error again:

Uncaught Error: Call to undefined method Dotenv\Dotenv::create()

I found this to be caused by the craft file in the project root. Again, as with the index.php file just a simple matter of updating it with the latest version as there is a slight difference in the code which caused the error:

#!/usr/bin/env php
<?php
/**
 * Craft console bootstrap file
 */

// Set path constants
define('CRAFT_BASE_PATH', __DIR__);
define('CRAFT_VENDOR_PATH', CRAFT_BASE_PATH.'/vendor');

// Load Composer's autoloader
require_once CRAFT_VENDOR_PATH.'/autoload.php';

// Load dotenv?
if (file_exists(CRAFT_BASE_PATH.'/.env')) {
    (new Dotenv\Dotenv(CRAFT_BASE_PATH))->load();
}

// Load and run Craft
define('CRAFT_ENVIRONMENT', getenv('ENVIRONMENT') ?: 'production');
$app = require CRAFT_VENDOR_PATH.'/craftcms/cms/bootstrap/console.php';
$exitCode = $app->run();
exit($exitCode);

#!/usr/bin/env php
<?php
/**
 * Craft console bootstrap file
 */

// Set path constants
define('CRAFT_BASE_PATH', __DIR__);
define('CRAFT_VENDOR_PATH', CRAFT_BASE_PATH.'/vendor');

// Load Composer's autoloader
require_once CRAFT_VENDOR_PATH.'/autoload.php';

// Load dotenv?
if (class_exists('Dotenv\Dotenv') && file_exists(CRAFT_BASE_PATH.'/.env')) {
    Dotenv\Dotenv::create(CRAFT_BASE_PATH)->load();
}

// Load and run Craft
define('CRAFT_ENVIRONMENT', getenv('ENVIRONMENT') ?: 'production');
$app = require CRAFT_VENDOR_PATH.'/craftcms/cms/bootstrap/console.php';
$exitCode = $app->run();
exit($exitCode);

Now everything on these websites is running without issue. However, on some websites I also had to manually delete all files and folders within storage > runtime > compiled_templates as they caused errors on the front end and within the field editing pages in the control panel.

I have since updated other websites without having to go through these steps so it's a bit odd that it only affects some but not all websites. However, given that new installations of Craft use a later version of phpdotenv it‘s probably a good thing to do this on all the websites so that it avoids any potential issues in future.

Now I can enjoy the great new features and functionalities of version 3.4!