[FR] Improve messaging for basic bootstrap errors

[lindseydiloreto]

Craft's modern bootstrap file is great for its simplicity, but could probably benefit from some additional messaging when things aren't going smoothly. Currently, there is virtually no error handling in the bootstrap file. Basic errors are just barfed onto the screen when the system gets off to a rocky start.

If you've worked with Craft long enough, at some point you've seen this ugly error message...

---

Warning: require_once(/var/www/html/vendor/autoload.php): Failed to open stream: No such file or directory in /var/www/html/bootstrap.php on line 11

Fatal error: Uncaught Error: Failed opening required '/var/www/html/vendor/autoload.php' (include_path='.:/usr/share/php') in /var/www/html/bootstrap.php:11 Stack trace: #0 /var/www/html/public/index.php(7): require() # 1 {main} thrown in /var/www/html/bootstrap.php on line 11

---

Seasoned veterans will recognize this as "the vendor folder is missing" (or something similar). It's typically a cue to run composer install or composer update when setting up a project.

But for newbies, it's very off-putting and confusing. The error message seems scarier than it really is, and often occurs when someone is unfamiliar with Craft and how it works.

In fact, the lack of proper error handling contributes to a long list of related issues from casual users...

• https://discord.com/channels/456442477667418113/456442477667418115/1271207060947730472
• https://discord.com/channels/456442477667418113/456442867163070466/922877924770742272
• https://discord.com/channels/456442477667418113/707324026577485934/933330472963022870
• https://discord.com/channels/456442477667418113/456448961679589386/972023817323024424
• https://discord.com/channels/456442477667418113/456442867163070466/963519384121401384
• etc, etc, etc

---

I propose putting a few additional checks in the bootstrap logic to ensure that everything starts smoothly...

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

// Ensure base path is valid
if (!is_dir(CRAFT_BASE_PATH)) {
    exit("The CRAFT_BASE_PATH is invalid:" . CRAFT_BASE_PATH);
}

// Ensure vendor path is valid
if (!is_dir(CRAFT_VENDOR_PATH)) {
    exit("The CRAFT_VENDOR_PATH is invalid:" . CRAFT_VENDOR_PATH);
}

// Define the path to autoload.php
$autoloader = CRAFT_VENDOR_PATH . '/autoload.php';

// Ensure autoloader is available
if (!is_file($autoloader)) {
    exit("The autoloader cannot be found:" . $autoloader);
}

// Load Composer's autoloader
require_once $autoloader;

Even beyond the simple examples given above, the error messages could also:

• give further guidance, and/or
• link back to a knowledgebase article with more information.

I recommend that we "pave the footpaths" and give these users a smoother learning curve for getting comfortable with Craft.

Thanks, curious to hear your thoughts! 👍

[khalwat]

Agree with this, with the caveat that if the message displayed is just The autoloader cannot be found then it isn't any more helpful than the current error that is displayed.

So in other words, do it... but go with the latter part of @lindseydiloreto 's suggestion, with a verbose explanation of how to fix it and/or a link to a KB article that explains how to fix it.

I will say that I think this is a general issue with Craft error messages/exceptions, something @michaelrog was working to improve with Canary: https://github.com/TopShelfCraft/Canary

[michaelrog]

yeah, but these particular errors occur too early in the chain for Craft/packages to add anything fancy... so, a helpful hint or KB URL would be most welcome.