hphp/doc/ini.md

   1 # Using ini
   2
   3 ini usage in HHVM is fairly similar to that of php-src, albeit currently with
   4 some limitations and enhancements. For example, HHVM currently doesn't support
   5 per-dir ini settings (support coming soon), but it does support vector-based
   6 settings and wildcards for copying and symlinking values from other settings.
   7
   8 ## Common usage
   9
  10 Here is the typical format of an ini file (values not necessarily realistic):
  11
  12 ```
  13 hhvm.hot_func_count = 11
  14 hhvm.stats.slot_duration = 11
  15 hhvm.server.allowed_exec_cmds[] = "ls"
  16 hhvm.server.allowed_exec_cmds[]= "cp"
  17 hhvm.server.allowed_exec_cmds[]= "rm"
  18 hhvm.env_variables["MYBOOL"] = true
  19 hhvm.env_variables["MYINT"] = 5
  20 hhvm.env_variables["MYSTR"] = "Custom String"
  21 hhvm.env_variables["ANOTHERSTR"] = "Another String"
  22 hhvm.server_variables[] = "Key will be next available int"
  23 hhvm.server_variables[] = "Value will be next available string"
  24 hhvm.error_handling.notice_frequency = 1
  25 hhvm.error_handling.warning_frequency = 1
  26 hhvm.enable_obj_destruct_call = true
  27 hhvm.enable_xhp = true
  28 ```
  29
  30 ## Copying and Symlinking Settings
  31
  32 **NOTE**: This feature only currently work with core system settings. They
  33 don't yet work with extensions, `ini_set()`, etc.
  34
  35 You can also provide wildcards to settings signaling that you want to use the
  36 value of another setting for its value.
  37
  38 * `@`: Copy the value directly into this setting.
  39 * `:`: Symlink the value from the other setting to this setting. If the other
  40 setting changes, then this setting will change with it, and vice-versa.
  41
  42 To use this feature, use the form
  43
  44 ```
  45 hhvm.setting[any-sub-key | @ | :][...] = value | "hhvm.substitution-setting"
  46 ```
  47
  48 e.g.,
  49
  50 ```
  51 hhvm.a = 3
  52 hhvm.b[@] = "hhvm.a"
  53 hhvm.c[d][@] = "hhvm.a"
  54 ```
  55
  56 Here is a more complete example:
  57
  58 ```
  59 hhvm.hot_func_count = 11
  60 hhvm.stats.slot_duration[@] = "hhvm.hot_func_count"
  61 hhvm.server.allowed_exec_cmds[0] = "ls"
  62 hhvm.server.allowed_exec_cmds[1][@]= "hhvm.env_variables[MYSTR]"
  63 hhvm.server.allowed_exec_cmds[2][@]= "hhvm.env_variables[ANOTHERSTR]"
  64 hhvm.env_variables["MYBOOL"] = true
  65 hhvm.env_variables["MYINT"][:] = "hhvm.hot_func_count"
  66 hhvm.env_variables["MYSTR"] = "Custom String"
  67 hhvm.env_variables["ANOTHERSTR"] = "Another String"
  68 hhvm.server_variables[0] = "Key will be next available int"
  69 hhvm.server_variables[1][@] = "hhvm.server.allowed_exec_cmds[0]"
  70 hhvm.error_handling.notice_frequency = 1
  71 hhvm.error_handling.warning_frequency[:] = "hhvm.error_handling.notice_frequency"
  72 hhvm.enable_obj_destruct_call = true
  73 hhvm.enable_xhp[@]= "hhvm.enable_obj_destruct_call"
  74 ```
  75
  76 **NOTE**: If you using this feature with vector or map based settings where you
  77 can specify `[]` to indicate an in-order increment of a setting, you must
  78 specify explicit indices for them because they will be used to determine which values to be used when copying or symlinking.