Getting phpdotenv also into Craft 2 -> Craft 3 upgrades, plus hopeful adds

[narration-sd]

Doc is missing in the section for these conversions,, but it's easy to provide, thus allowing all Craft 3 sites to take advantage of the better security possible, and be consistent when addressed in future.

Think what would be useful in the initial Updating Craft CMS section of upgrade.md is:

• insert an step after 4) and similar to it, with this instruction. At present it will result in a tag of ^2.40, which should provide for future.

  compoaer require vlucas/phpdotenv

• In the step which now becomes 6), replace the index.php code substitution with something like this. Note that the phpdotenv call has added protection, in case the composer step hadn't been done or succeeded, or was lost.

<?php

// Project root path
$root = dirname(__DIR__);

// Load and run Craft
define('CRAFT_BASE_PATH', $root.'/craft');
require_once $root.'/vendor/autoload.php';

// dotenv?
if (file_exists($root.'/.env')
  && file_exists($root.'/vendor/vlucas/phpdotenv')) {
    $dotenv = new Dotenv\Dotenv($root);
    $dotenv->load();
}

$app = require $root.'/vendor/craftcms/cms/bootstrap/web.php';
$app->run();

• You could quite usefully add a further paragraph in this area, quite possibly a new step (now) 9) and after 'success and delete app', explaining how the converted site will continue to use the present db.php and general.php, while possibly needing some modifications, leading to the following Configuration section

  • In that Configuration section, then it's easy to say that you may want to move forward to putting security items like passwords into .env, because now you can.

• similarly, it could be quite informative to flesh out the rather misssable Asset Volume Settings section (bigger heading type there?) with a note that you can use .env entries to fill in the per-deployment-site differing values for ASSET_BASE_PATH and ASSET_BASE_URL in volumes.php.

• last point is that problems with old Redactor configs could usefully be a bit better explained in the Redactor configs section. I would follow your specifics with a short paragraph saying 1) in fact old Redator configs often don't follow these rules, by not quoting all values, and by using the wrong quote character otherwise, so you will have to edit them if Craft shows an on Rich Text fields, and 2) that http://jsonlint.com/ can be very useful in assuring you've made all the corrections.

• well, one more. It's likely to be helpful to add a now 10) item to the initial Updating Craft CMS section, suggesting to Clear Caches all nder the new Utilities menu, before beginning to try out the converted site. I've had some very misleading problems occur on conversion, until doing this, something easily overlooked but obviously of need for sites that have run before, when you think about it.

[narration-sd]

Added note: it's likely quite useful to add to primary doc how the file and url paths need to be set, especially with regard to Sites -- or even primary Site.

Points to be expressed -- I know we've hit some of these before, but to draw together:

• you need to have a full filesystem path for File System path -- example /home/vagrant/yoursite etc.
• you need to have a non-relative url path for Base Url -- example /resources/images
• both of these are visible in Assets>Volume settings
• the most effective way to set them, however, is in config/volumes.php, so that .env can adjust them for each server location (dev, staging, release etc.)
• the seeings suggested by default in the .env file for ASSETS_BASE_PATH and ASSETS_URL_PATH allow setting the complete paths according to server
• don't forget to use a "/" for teh ASSET_BASE_URL , so that you have a fixed path for assets on the web. If you have instead a relative complete path, this may seem to work at first, but images may not show in Live Preview, as one example, because of unexpected resulting paths. [I believe this could be made tamer in the code, but as seems best to you of course, so not issuing that in respect]
• When you need to have some images differing per site, define another Volume and config/volumes.php definition for them, and an Asset field which can use this appropriately in your templates. The same considerations about file and url paths apply, but you will set the appropriate Site base url and base path to suit the site folder, in the added volumes.php definition.

Ok, notes at least on a Sunday morning -- definitely can use careful editing and otherwise knocking into shape for doc...cases, though, taken from experiences, and the time taken to sort them out...

[AugustMiller]

I've decided to close this, in part because the Craft 2.x and 3.x docs have been frozen (aside from the occasional backwards-compatible edit), and in part because I found a spot to make mention of the primary asks (regarding phpdotenv and entry scripts) in the 3.x -> 4.x upgrade guide.

If you would like to submit the remainder of the requests individually, please do! This is all is a work-in-progress—and we’re aware of a few places where Assets are underserved by the documentation.