Skip to content

Commit

Permalink
Improve environment management
Browse files Browse the repository at this point in the history 
- Do not use putenv/getenv by default
- Decouple as much as possible from Symfony package
- Use a single method to load env files, instead of "load" VS "loadFile" VS "loadAppended"
- Move all the "dump cache" logic to the Helpers class
- Fix PHP 8.1 deprecation in filter octal values
  • Loading branch information
@gmazzap
gmazzap committed Nov 10, 2023
1 parent 7512871 commit cb0967a
Show file tree
Hide file tree
Showing 11 changed files with 263 additions and 265 deletions.
6 changes: 3 additions & 3 deletions composer.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,13 +47,13 @@
"ext-SPL": "*",
"composer-plugin-api": "^2",
"composer/installers": "^2",
"symfony/dotenv": "^3.4 || ^5 || ^6"
"symfony/dotenv": "^5 || ^6"
},
"require-dev": {
"roave/security-advisories": "dev-latest",
"composer/composer": "^2.6.5",
"symfony/process": "^5.4.19",
"wp-cli/wp-cli": "^2.7.1",
"symfony/process": "^v5.4.28",
"wp-cli/wp-cli": "^v2.9.0",
"inpsyde/php-coding-standards": "^2@dev",
"inpsyde/wp-stubs-versions": "dev-latest",
"vimeo/psalm": "^5.15.0",
Expand Down
32 changes: 27 additions & 5 deletions docs/02-Environment-Variables.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,23 @@ In PHP there are two functions: [`getevn`](http://php.net/manual/en/function.get

There's nothing in PHP core that parse env files, but is no surprise that there are different libraries to do that.

WP Starter uses one of these libraries: the **[Symfony Dotenv Component](https://symfony.com/doc/3.4/components/dotenv.html).**
WP Starter uses one of these libraries: the **[Symfony Dotenv Component](https://symfony.com/components/Dotenv).**



### About `putenv()` and `getenv()`

These two PHP functions are problematic as they are not thread safe. So **recent versions of WP Starter** (as well as recent version of Symfony Dotenv Component) **do not use `putenv()` by default** to store in the environment the values loaded via `.env` files.

Even if `.env` files are discouraged in production where thread safety is important, we still prefer to have a safe behavior by default and not use `putenv()`. This means that environment variables loaded from WP Starter `.env` files will not be available to `getenv()`.

There are different ways those values could be read instead:

- Because WP Starter converts environment variables to constants (after converting to the correct type), one approach is to access values constants.
- Directly access super globals: `$_ENV['var_name'] ?? $_SERVER['var_name'] ?? null`.
- Make use of WP Starter helper, like ` WeCodeMore\WpStarter\Env\Helpers::readVar('var_name');` This approach has the benefit of obtaining "filtered values". E. g. obtaining the intended type instead of always a string.

If any of the above can be used for some reason, it is still possible to let WP Starter use `putenv()` to load environments by setting the `use-putenv` configuration to `true`.



Expand All @@ -82,6 +98,8 @@ Moreover, **if the "actual environment" contains all the variables WP Starter an

Configuring WP Starter to **bypass** the loading of env files is accomplished via the **`WPSTARTER_ENV_LOADED`** env variable, which when set tells WP Starter to assume all variables are in the actual environment.



### Important security note about `.env` file

WP Starter loads an `.env` file found in the project root folder, and it is worth noting that if no additional configuration is made, project root is also the folder assumed as webroot for the project.
Expand Down Expand Up @@ -121,7 +139,7 @@ If there's a plugin that supports a constant like `"AWESOME_PLUGIN_CONFIG"`, by
So you might need to write code like:

```php
$config = getenv('AWESOME_PLUGIN_CONFIG');
$config = $_ENV['AWESOME_PLUGIN_CONFIG'] ?? $_SERVER['AWESOME_PLUGIN_CONFIG'] ?? null;
if ($config) {
define('AWESOME_PLUGIN_CONFIG', $config);
}
Expand All @@ -131,6 +149,8 @@ There are many places in which such code can be placed, for example a MU plugin.

Alternatively WP Starter can be instructed to do something like this automatically.



### Let WP Starter define constants for custom env vars

WP Starter supports an environment variable called `WP_STARTER_ENV_TO_CONST` containing a list of of comma-separated environment variables to be turned into constants:
Expand Down Expand Up @@ -165,6 +185,8 @@ As described above, all WordPress configuration constants are natively supported

Moreover, there are a few env variables that have a special meaning for WP Starter.



### DB check env vars

During its bootstrap process, before doing any operation on the system, WP Starter checks if the environment is already setup for database connection.
Expand All @@ -181,6 +203,8 @@ The three env vars are registered in the order they are listed above: if one is
Sometime it might be desirable to bypass this WP Starter check and there's a way to accomplish that via the `skip-db-check` setting.
Learn more about that in the [_"WP-Starter-Configuration"_ chapter](04-WP-Starter-Configuration.md).



### WordPress Configuration

Those are a few env vars that are used in `wp-config.php` that WP Starter generates.
Expand Down Expand Up @@ -226,9 +250,7 @@ The filter is executed very late (so could be added in MU plugins, plugins and e
For example, to only allow cache in production a code like the following can be used:

```php
add_filter('wpstarter.skip-cache-env', function ($skip, $envName) {
return $skip || $envName !== 'production';
});
add_filter('wpstarter.skip-cache-env', fn ($skip, $envName) => $skip || $envName !== 'production');
```


Expand Down
57 changes: 29 additions & 28 deletions docs/09-Settings-Cheat-Sheet.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,35 +7,36 @@ nav_order: 9

Alphabetically ordered:

| Key | Description | Default value |
|:------------------------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------:|
| `autoload` | PHP file loaded before WP Starter its steps.<br />Path to the file, relative to root. | "./wpstarter-autoload.php" |
| `cache-env` | Whether to cache env for WP requests. | true |
| `check-vcs-ignore` | Whether to check for VCS-ignored paths.<br>By default `true`, can be set to `false` to not do any check.<br>Can also be set to`"ask"`, in which case WP Starter will ask user what to do. | true |
| `command-steps` | Objects steps of custom steps to add to be ran via WP Starter command.<br />Values must be steps FQCN, keys the step names, matching what `Step::name()` returns.<br />Given classes must be autoloadable. | {} |
| `content-dev-dir` | Source folder for "development content".<br />Path to the folder, relative to root. | "./content-dev" |
| Key | Description | Default value |
| :----------------------: | :----------------------------------------------------------- | :------------------------: |
| `autoload` | PHP file loaded before WP Starter its steps.<br />Path to the file, relative to root. | "./wpstarter-autoload.php" |
| `cache-env` | Whether to cache env for WP requests. | true |
| `check-vcs-ignore` | Whether to check for VCS-ignored paths.<br>By default `true`, can be set to `false` to not do any check.<br>Can also be set to`"ask"`, in which case WP Starter will ask user what to do. | true |
| `command-steps` | Objects steps of custom steps to add to be ran via WP Starter command.<br />Values must be steps FQCN, keys the step names, matching what `Step::name()` returns.<br />Given classes must be autoloadable. | {} |
| `content-dev-dir` | Source folder for "development content".<br />Path to the folder, relative to root. | "./content-dev" |
| `content-dev-op` | Operation to perform for "development content"<br />That is, plugins, themes, MU plugins, translations and dropins shipped with the project.<br />Valid values are "auto", symlink", "copy" and "none".<br />Can also be set to`"ask"`, in which case WP Starter will ask user what to do. | "auto" |
| `create-vcs-ignore-file` | Whether to check for VCS-ignore file if it does not exist.<br/>By default `true`, can be set to `false` to not create it.<br/>Can also be set to`"ask"`, in which case WP Starter will ask user what to do. | true |
| `custom-steps` | Map of custom step names to custom step classes.<br />Classes must be autoloadable. | null |
| `db-check` | Determine if and how DB check is done.<br />By default `true`, can be set to `false` to not do any check, or to `health` to do a health check using `mysqlcheck` binary. | true |
| `dropins` | Array of dropins files to move to WP content folder.<br />Can be local paths or remote URLs. | [] |
| `dropins-op` | Operation to perform for "dropins"<br />Valid values are "auto", symlink", "copy" and "none".<br />Can also be set to`"ask"`, in which case WP Starter will ask user what to do. | "auto" |
| `early-hook-file` | PHP file that adds callbacks to early hooks.<br />Path to the file, relative to root. | null |
| `env-bootstrap-dir` | Folder where to look for env bootstrap files.<br />Path to the folder, relative to root. | null |
| `env-dir` | Folder where to look for `.env` file.<br />Path to the folder, relative to root. | "./" |
| `env-example` | How to deal with `.env.example` file. Can be:<br />- `true` (copy default example file to root)<br />- `false` (do nothing)<br />- path, relative to root, to example file to copy.<br />- `"ask"` (user will be asked what to do) | true |
| `env-file` | Name of the `.env` file.<br />Will be searched inside `env-dir` | ".env" |
| `install-wp-cli` | Whether to install WP CLI from phar if necessary. | true |
| `move-content` | Whether to move default themes and plugins<br />to project wp-content folder.<br />Can be set to`"ask"`, in which case WP Starter will ask user what to do. | false |
| `prevent-overwrite` | Array of paths to preserve from overwrite.<br />Paths relative to root, might use glob patterns.<br />Can be set to`"ask"`, in which case WP Starter will ask confirmation before *each* overwrite attempt. | [] |
| `register-theme-folder` | Whether to register default themes.<br />Can be set to`"ask"`, in which case WP Starter will ask user what to do. | false |
| `require-wp` | Whether to check for WP package being required. | true |
| `scripts` | Array of script to run before or after steps.<br />An object where key is in the format:<br /> `"pre-{$step}"` or `"post-{$step}"`<br />and value is either a callback.<br />Callbacks must be autoloadable. | [] |
| `skip-steps` | Array of step *names* to skip. | [] |
| `templates-dir` | Folder where to look for custom templates.<br />Path relative to root. | null |
| `wp-cli-commands` | Array of WP CLI commands.<br />Can be a path to a PHP file _returning_ the array of commands, or to a JSON file containing the array.<br />Paths relative to root. | [] |
| `wp-cli-files` | Array of file paths to be passed to WP CLI `eval file`. Can be an array of objects with "file", "args", and "skip-wordpress" properties.<br />Paths relative to root. | [] |
| `wp-version` | When `require-wp` is set to `false` this instruct WP Starter about the WP version that will be used with WP Starter. | null |
| `create-vcs-ignore-file` | Whether to check for VCS-ignore file if it does not exist.<br/>By default `true`, can be set to `false` to not create it.<br/>Can also be set to`"ask"`, in which case WP Starter will ask user what to do. | true |
| `custom-steps` | Map of custom step names to custom step classes.<br />Classes must be autoloadable. | null |
| `db-check` | Determine if and how DB check is done.<br />By default `true`, can be set to `false` to not do any check, or to `health` to do a health check using `mysqlcheck` binary. | true |
| `dropins` | Array of dropins files to move to WP content folder.<br />Can be local paths or remote URLs. | [] |
| `dropins-op` | Operation to perform for "dropins"<br />Valid values are "auto", symlink", "copy" and "none".<br />Can also be set to`"ask"`, in which case WP Starter will ask user what to do. | "auto" |
| `early-hook-file` | PHP file that adds callbacks to early hooks.<br />Path to the file, relative to root. | null |
| `env-bootstrap-dir` | Folder where to look for env bootstrap files.<br />Path to the folder, relative to root. | null |
| `env-dir` | Folder where to look for `.env` file.<br />Path to the folder, relative to root. | "./" |
| `env-example` | How to deal with `.env.example` file. Can be:<br />- `true` (copy default example file to root)<br />- `false` (do nothing)<br />- path, relative to root, to example file to copy.<br />- `"ask"` (user will be asked what to do) | true |
| `env-file` | Name of the `.env` file.<br />Will be searched inside `env-dir` | ".env" |
| `install-wp-cli` | Whether to install WP CLI from phar if necessary. | true |
| `move-content` | Whether to move default themes and plugins<br />to project wp-content folder.<br />Can be set to`"ask"`, in which case WP Starter will ask user what to do. | false |
| `prevent-overwrite` | Array of paths to preserve from overwrite.<br />Paths relative to root, might use glob patterns.<br />Can be set to`"ask"`, in which case WP Starter will ask confirmation before *each* overwrite attempt. | [] |
| `register-theme-folder` | Whether to register default themes.<br />Can be set to`"ask"`, in which case WP Starter will ask user what to do. | false |
| `require-wp` | Whether to check for WP package being required. | true |
| `scripts` | Array of script to run before or after steps.<br />An object where key is in the format:<br /> `"pre-{$step}"` or `"post-{$step}"`<br />and value is either a callback.<br />Callbacks must be autoloadable. | [] |
| `skip-steps` | Array of step *names* to skip. | [] |
| `templates-dir` | Folder where to look for custom templates.<br />Path relative to root. | null |
| `use-putenv` | Tell WP Starter to store variables loaded from `.env` files _also_ using `putenv()`.<br />Use only if something is relying on `getenv()` and can not be changed. | false |
| `wp-cli-commands` | Array of WP CLI commands.<br />Can be a path to a PHP file _returning_ the array of commands, or to a JSON file containing the array.<br />Paths relative to root. | [] |
| `wp-cli-files` | Array of file paths to be passed to WP CLI `eval file`. Can be an array of objects with "file", "args", and "skip-wordpress" properties.<br />Paths relative to root. | [] |
| `wp-version` | When `require-wp` is set to `false` this instruct WP Starter about the WP version that will be used with WP Starter. | null |



Expand Down
Loading

0 comments on commit cb0967a

Please sign in to comment.