Console commands for .htaccess and config.php #

For administrators, hosting operators and anyone who scripts installations. Every installation ships three templates at its root: .htaccess_root and .htaccess_root_static (the rules for Apache and LiteSpeed, the second with the static cache offload) and config.php-RECOMMENDED (the documented settings of config.php). Seven console commands put them into place and read and change config.php, so nobody has to copy them by hand or edit PHP in an editor on a server:

What makes them safe #

• Dry run first. Without --apply each command shows what it would change; --apply with --dry-run is a usage error (exit 2).
• No silent overwrite. An existing .htaccess or config.php that differs from the template is shown as a diff and kept unless --force.
• A backup before every write, to var/backup/setup/<time>/ or var/backup/config/<time>/, with the file's mode and owner, in directories of mode 0700.
• Atomic writes through a temporary file in the same directory, renamed into place.
• cp -a behavior for owners and modes. A new file gets the template's mode and, run as root, the template's owner (never root's); an existing file keeps its own. --mode and --owner=user[:group] set them; -v prints each copy like cp -v.
• config.php is parsed, not searched. It is read as PHP tokens and never run; only the value of one define( 'NAME', value ) changes, and comments, order and formatting stay. A define() inside a condition is reported and left alone.
• Checked before it lands. A new config.php must pass php -l and read back with the value asked for. A config.php that does not compile is refused, and ./console still starts to repair it.
• Typed values. bool, int, octal (modes such as 0640), float, string, null, from --type, the current value or the documented one.
• Secrets masked. Values of names with PASS, SECRET, KEY, TOKEN, CREDENTIAL or PWD are ******** in every output and diff unless --show-secrets; setting one in a config.php everyone can read prints a warning.
• Only known names, those config.php-RECOMMENDED documents, unless --allow-unknown, so a typing mistake is caught instead of written.

Example #

./console exp:setup:htaccess --apply -v
./console exp:setup:config --apply
./console exp:config:set EZP_INI_FILEMTIME_CHECK false --apply
./console exp:config:set EZP_FILE_MODE_MAX 0640 --apply
./console exp:config:list --only-set

'.htaccess_root' -> '.htaccess'
PASS: .htaccess_root copied to .htaccess (mode 0644, owner www-data:www-data)
...
config.php: 2 setting(s) set, 30 documented in config.php-RECOMMENDED

INI FILES OPTIMIZATIONS
  EZP_INI_FILEMTIME_CHECK              false (line 57)
      RECOMMENDED false - This new setting controls whether eZINI should check if the settings have been updated...

FILE PERMISSIONS
  EZP_FILE_MODE_MAX                    0640 (line 112)
      RECOMMENDED 0640 - Set EZP_DIR_MODE_MAX and EZP_FILE_MODE_MAX to the widest modes any directory and any fi...

The whole walk-through, with every option, the output of each case, the backup and --force rules, scripts, containers and troubleshooting: Setting up .htaccess and config.php from the console.

For developers #

• Code: kernel/classes/expsetupfilecopy.php (copy, backup, atomic write, php -l), kernel/classes/expconfigphpeditor.php (the token-based define() editor), kernel/classes/expconfigphpcatalogue.php (the settings documented in config.php-RECOMMENDED), the commands kernel/private/classes/commands/setupfiles.php and configphp.php, the entry points bin/php/setupfiles.php and bin/php/configphp.php.
• A config.php that does not compile would stop autoload.php. bin/php/console, bin/php/setupfiles.php and bin/php/configphp.php define EXP_CONFIG_PHP_TOLERATE first; for them alone autoload.php checks the file with the PHP parser and leaves it unread when it does not compile (EXP_CONFIG_PHP_SKIP holds the error). Every other entry point reads config.php as before.
• A new setting becomes known to the commands by documenting it in config.php-RECOMMENDED the same way as the others: a comment block (a heading underlined with dashes starts a section) followed by //define( 'NAME', value );.
• Tests: tests/tests/kernel/private/classes/commands/expSetupFilesAndConfigPhpCommandsTest.php (no database).
• Generated reference: exp:setupfiles, exp:configphp.

Related #

• Installation: getting the code, Serving the site
• Change settings from the command line: exp:ini, for the INI files in settings/
• The static cache generator, which .htaccess_root_static serves
• File modes