exp:ini

Available since Exponential 6.0.15 (in development, not in a release yet).

Summary

Read and change INI settings in every scope: get, set, add, rem, clear, toggle, copy, move, where, list, scopes

Usage

./console exp:ini [options]
php bin/php/ini.php [options]

Help

The output of ./console help exp:ini (the script run with --help), without the standard options:

exp:ini: read and change the settings of every scope from the command line

Usage: exp:ini <action> <arguments> [options]          (php bin/php/ini.php ...)

Actions:
  get      Show the value in effect, or the value one scope's file gives
             exp:ini get <file>/<Block>/<Variable>[<key>] [scope]
  set      Set a variable (Variable=value) or a hash entry (Variable[key]=value) in one scope
             exp:ini set <file>/<Block>/<Variable> <value> <scope>
  add      Append a value to an array (Variable[]=value) in one scope
             exp:ini add <file>/<Block>/<Variable>[] <value> <scope>
  rem      Remove a variable, one array value or one hash entry from one scope (alias: remove)
             exp:ini rem <file>/<Block>/<Variable> <scope>
  clear    Write the array reset line Variable[] in one scope (earlier files' values are dropped)
             exp:ini clear <file>/<Block>/<Variable>[] <scope>
  toggle   Flip a switch in one scope: enabled<->disabled, true<->false, yes<->no, 1<->0
             exp:ini toggle <file>/<Block>/<Variable> <scope>
  copy     Copy a setting from one scope to another (a whole array as reset line + values)
             exp:ini copy <file>/<Block>/<Variable>[<key>] <from-scope> <to-scope>
  move     Move a block, or every block of a file, from one scope to another (e.g. into an extension)
             exp:ini move <file>[/<Block>] <from-scope> <to-scope> [--only=<Variable,...>] [--keep-target] [--force]
  move-all Move every INI file of a scope into another scope (e.g. a siteaccess into an extension)
             exp:ini move-all <from-scope> <to-scope> [--files=site,content,...] [--keep-target] [--force] [--create-extension] [--activate] [--dry-run]
  where    List every file that sets a variable, in load order, and the value in effect
             exp:ini where <file>/<Block>/<Variable> [siteaccess]
  list     List the blocks of a file, or the variables of a block (in effect or in one scope)
             exp:ini list <file>[/<Block>] [scope]
  scopes   List the scopes this installation has and the directory each writes
             exp:ini scopes [kind]
  actions  List the actions: built-in and registered by extensions in ini.ini
  remove   = rem

Setting syntax (the .ini suffix is optional):
  site.ini/SiteSettings/SiteName      site.ini:SiteSettings.SiteName      "site.ini [SiteSettings] SiteName"
  .../Variable[]        an array (add, rem <value>, clear)
  .../Variable[key]     a hash entry (set, get, rem)
  A value that starts with "-": put "--" before it; what follows is taken as it is:
    exp:ini set site.ini/MySettings/Offset -- -1 global

Scopes (exp:ini scopes lists those of this installation):
  global (= override)                  settings/override/<file>.ini.append.php
  siteaccess:<sa> (or bare <sa>)       settings/siteaccess/<sa>/<file>.ini.append.php
  extension:<ext>                      extension/<ext>/settings/<file>.ini.append.php
  extension:<ext>:siteaccess:<sa>      extension/<ext>/settings/siteaccess/<sa>/<file>.ini.append.php
  default                              settings/<file>.ini, refused unless --allow-default
  and the scopes of providers registered in ini.ini [IniCommandSettings] ScopeProviders[]

Options:
  --dry-run          show the diff of the change and write nothing
  --json             print one JSON object: ok, code, action, message, warnings, data
  --show-secrets     show the values of Password, Secret, Token, Salt, ...Key variables (masked otherwise)
  --allow-default    allow writing the default scope, the kernel's shipped settings/<file>.ini
  --clear-cache      clear the ini cache after a write (the default)
  --no-clear-cache   do not clear the ini cache after a write
  --backup           copy the file to var/backup/ini/<timestamp>/ before writing (the default)
  --no-backup        write without a backup copy
  --create           create a missing file and block (the default for set, add, clear, toggle, copy)
  --no-create        refuse to create a missing file (rem never creates one)
  --root=<dir>       work on the settings tree of another installation root (a copy, a checkout); the ini cache is not cleared
  --keep-target      move: a variable both blocks have keeps the target's value (the source's wins by default)
  --only             move: only these variables of the block, comma separated
  --files            move-all: only these files, comma separated (site,content,...)
  --force            move: keep a move although a value in effect changed (it is rolled back otherwise)
  --create-extension move: create the target extension (extension.xml, ezinfo.php, settings/) when it does not exist
  --activate         move: activate the target extension (ActiveExtensions[] in global, ActiveAccessExtensions[] for a siteaccess target)
  -s <siteaccess>    the siteaccess whose settings are in effect (get, where, list)
  --allow-root-user  needed when run as root, as for every script

Files are written line by line: comments, blank lines and the order stay; a changed file keeps its
owner, group and mode, a new one gets those of its settings directory; the write is atomic and a
backup goes to var/backup/ini/<timestamp>/ first. After a write the ini cache is cleared.

Exit codes: 0 done (or nothing to change), 1 usage error, 2 not found, 3 refused, 4 write failed

Examples:
  exp:ini set site.ini/SiteSettings/SiteName "My site" global
  exp:ini rem site.ini/SiteSettings/SiteName siteaccess:admin
  exp:ini toggle site.ini/ContentSettings/ViewCaching global          enabled <-> disabled
  exp:ini toggle site.ini/TemplateSettings/Debug siteaccess:admin     true <-> false
  exp:ini add site.ini/ExtensionSettings/ActiveExtensions[] myext global --dry-run
  exp:ini where site.ini/SiteSettings/SiteName
  exp:ini get site.ini/DatabaseSettings/Password global              ******** (--show-secrets)
  exp:ini move site.ini/DebugSettings global extension:mysite --create-extension --activate --dry-run
  exp:ini move-all siteaccess:admin extension:mysite:siteaccess:admin --dry-run
  exp:ini help <action>

Extending: an extension adds an action with Actions[<name>]=<class> and a scope provider with
ScopeProviders[]=<class> in extension/<ext>/settings/ini.ini.append.php. Guide: doc/eng-us/bc/6.0/console-exp-ini.md

Standard options

Every script also takes the standard options of the script framework: --help, --quiet, --siteaccess, --debug, --colors, --no-colors, --logfiles, --no-logfiles, --verbose and --allow-root-user.

Source

bin/php/ini.php, kernel/private/classes/commands/ini.php

See also

Generated example: exp:ini

Added to the reference for Exponential 6.0.15.