Ini Settings fixes

Author: Julien Pauli

Book/php7/extensions_design/ini_settings.rst

@@ -28,7 +28,7 @@ the default value the extension designer gives to the API.
           is the one given by the extension developer, not the other way around.
 
 The default value we are talking about here is called the **"master value"**. You may recall it from a ``phpinfo()`` 
-output, right ?:
+output, right ?
 
 .. image:: ./images/php_extensions_ini.png
    :align: center
@@ -68,23 +68,27 @@ Into the engine, an INI setting is represented by a ``zend_ini_entry`` structure
         int module_number;
     };
 
-Nothing really strong in such a structure. Setting's ``name`` and ``value`` are the most commonly used fields. Note 
-however that the value is a string (as :doc:`zend_string <../internal_types/strings/zend_strings>`) and nothing else.
-Then, like we detailed in the introduction chapter above, we find the ``orig_value``, ``orig_modified``, ``modifiable`` 
-and ``modified`` fields which are related to the modification of the setting's value. The setting must keep in memory 
-its original value (as "master value"). ``modifiable`` tells if the setting is actually modifable, and must have one of 
-the values you should be aware of from PHP userland : ``ZEND_INI_USER``, ``ZEND_INI_PERDIR``, ``ZEND_INI_SYSTEM`` or 
-``ZEND_INI_ALL``. ``modified`` is set to one anytime the setting has been modified during a request so that the engine 
-knows at request shutdown that it must restore that INI setting value to its master value for the next request to treat.
-
-Then come two handlers: ``on_modify()`` is called whenever the current setting's value is modified, like f.e using a call 
-to ``ini_set()`` (but not only). We'll focus deeper on ``on_modify()`` later, but think of it as being a 
-*validator function* (f.e if the setting is expected to represent an integer, you may validate the values you'll be 
-given against integers). It also serve as a memory bridge to update global values, we'll get back on that later as well.
-
-``diplayer()`` is less useful, and you usually don't pass any. ``displayer()`` is about how to display your setting. 
-F.e, you may remember that PHP tends to display *On* for boolean values of *true*/*yes*/*on*/*1* etc. That's the 
-``displayer()`` job : turn the current value into a "displayed" value.
+Nothing really strong in such a structure.
+
+* Setting's ``name`` and ``value`` are the most commonly used fields. Note 
+  however that the value is a string (as :doc:`zend_string *<../internal_types/strings/zend_strings>`) and nothing else.
+* Then, like we detailed in the introduction chapter above, we find the ``orig_value``, ``orig_modified``, ``modifiable`` 
+  and ``modified`` fields which are related to the modification of the setting's value. The setting must keep in memory 
+  its original value (as "master value").
+* ``modifiable`` tells if the setting is actually modifable, and must pick some 
+  values from ``ZEND_INI_USER``, ``ZEND_INI_PERDIR``, ``ZEND_INI_SYSTEM`` or 
+  ``ZEND_INI_ALL``, those may be flagued together and are detailed `in the PHP manual 
+  <http://php.net/configuration.changes.modes>`_.
+* ``modified`` is set to one anytime the setting has been modified during a request so that the engine knows at request 
+  shutdown that it must restore that INI setting value to its master value for the next request to treat.
+* ``on_modify()`` is a handler called whenever the current setting's value is modified, like f.e using a call 
+  to ``ini_set()`` (but not only). We'll focus deeper on ``on_modify()`` later, but think of it as being a 
+  *validator function* (f.e if the setting is expected to represent an integer, you may validate the values you'll be 
+  given against integers). It also serve as a memory bridge to update global values, we'll get back on that later as 
+  well.
+* ``diplayer()`` is less useful, and you usually don't pass any. ``displayer()`` is about how to display your setting. 
+  F.e, you may remember that PHP tends to display *On* for boolean values of *true*/*yes*/*on*/*1* etc. That's the 
+  ``displayer()`` job : turn the current value into a "displayed" value.
 
 You will also need to deal with this structure ``zend_ini_entry_def``::
 
@@ -109,7 +113,10 @@ an INI setting against the engine. The engine reads a ``zend_ini_entry_def``, an
 Registering and using INI entries
 ---------------------------------
 
-INI settings are persistent through requests. They can change their value during a request (runtime), but they'll go back 
+Registration
+************
+
+INI settings are persistent through requests. They may change their value at runtime during a request, but they'll go back 
 to original value at request shutdown. Thus, registering INI settings is done once for all, in ``MINIT()`` hook of your 
 extension.
 
@@ -132,6 +139,13 @@ for previous chapter about random number picking and guessing, once again only s
     {
         DISPLAY_INI_ENTRIES();
     }
+    
+    PHP_MSHUTDOWN_FUNCTION(pib)
+    {
+        UNREGISTER_INI_ENTRIES();
+
+        return SUCCESS;
+    }
 
 That was the easiest INI declaration, we won't keep it as-is but the steps are trivial : you declare a 
 ``zend_ini_entry_def[]`` vector using ``PHP_INI_BEGIN`` and ``PHP_INI_END`` macros. In the middle, you add your 
@@ -140,17 +154,24 @@ takes only four parameters : the name of the entry to register, its default valu
 file scanning (see above chapter for details), the modification level, ``PHP_INI_ALL`` says "everywhere". We did not 
 play with validator yet, and passed NULL.
 
-Now, the new *"pib.rnd_max"* INI setting is declared - as *PHP_INI_ALL* - that means that the user may play with its 
-value using ``ini_set()`` and ``ini_get()`` mainly.
+In ``MINIT`` hook , we use the ``REGISTER_INI_ENTRIES`` macro which does its describing job whereas its counter-part 
+``UNREGISTER_INI_ENTRIES`` is used at module shutdown to free the allocated resources.
 
-We did not forget to display that INI setting as part of our extension informations, using ``DISPLAY_INI_ENTRIES()``. 
+Now, the new *"pib.rnd_max"* INI setting is declared - as ``PHP_INI_ALL`` - that means that the user may modify its 
+value using ``ini_set()`` (and read it back with ``ini_get()``).
+
+We did not forget to display those INI settings as part of our extension informations, using ``DISPLAY_INI_ENTRIES()``. 
 Forgetting this in the declaration of the ``MINFO()`` hook will lead to our INI settings being hidden from the user in 
 the information page (``phpinfo()``). Have a look at the :doc:`extension informations chapter <extension_infos>` if 
 you need.
 
-On your part as extension developper, we may now need to read that value ourselves. The simplest way to do this is to 
-use macros that will look for the value into the main array retaining all the INI settings, find it, and return it as 
-the type we'll ask for. We are provided several macros depending on what C type we want to be given back.
+Usage
+*****
+
+On your part as extension developper, we may now need to read INI settings values by yourself. The simplest way to do 
+this into your extension is to use macros that will look for the value into the main array retaining all the INI 
+settings, find it, and return it as the type you'll ask for. We are provided several macros depending on what C type 
+we want to be given back.
 
 ``INI_INT(val)``, ``INI_FLT(val)``, ``INI_STR(val)``, ``INI_BOOL(val)`` all four macros will look for the provided 
 value from the INI settings array and return it (if found) with a cast to the type you ask.
@@ -180,15 +201,15 @@ previous above lines is far from being optimal.
 There are two problems that will get solved at the same time by using the 'advanced' INI settings API :
 
 * Everytime we want to read our value, a lookup into the main INI settings table is needed, as well as a cast to the 
-  right type, often.
+  right type (often). Those operations cost some CPU cycles.
 * We did not provide any validator, thus the user could alter our setting and put anything he wants to as a value.
 
-Welcome globals update memory bridge.
+The solution is to use an ``on_modify()`` validator and a memory bridge to update a global variable.
 
 By using the advanced INI settings management API, we can tell the engine to register our settings just normally, but 
 we can also instruct it to update a global of our taste everytime the INI setting value is changed. Hence, whenever we 
 will want to read back our value, we'll just need to read our global. This will provide a boost in performance in the 
-case we need to read the INI setting value often, as a hashtable lookup won't be needed anymore.
+case we need to read the INI setting value often, as a hashtable lookup and a cast operation won't be needed anymore.
 
 .. note:: You will need to feel comfortable with globals to continue reading the chapter. Global space management is 
           treated :doc:`into its own chapter <globals_management>`.
@@ -227,25 +248,25 @@ declares a ``pib_globals`` symbol of such a type.
           ``max_rnd`` member into the ``zend_pib_globals`` structure, to be able to update that part of memory whenever the 
           *'pib.rnd_max'* will get changed.
 
-The validator used here, ``onUpdateLongGEZero()``, is a default validator that exists in PHP and validates the value 
-against a long greater than or equal to zero. The validator is needed for the global to be updated, as such a job is 
-done into the validator.
+The ``on_modify()`` validator used here, ``onUpdateLongGEZero()``, is a default validator that exists in PHP and 
+validates the value against a long greater than or equal to zero. The validator is needed for the global to be updated, 
+as such a job is done into the validator.
 
 Now, to read back our INI setting value, we just need to read the value of our ``max_rnd`` global::
 
     php_printf("The value is : %lu", PIB_G(max_rnd));
 
 And we are done.
 
-Let's go to see the validator now. The validator has two goals :
+Let's go to see the validator now (``on_modify()`` handler). The validator has two goals :
 
 * Validate the passed value
 * Update the global if the validation succeeds
 
-The validator is only called when the INI setting is set or modified, whenever this step happens.
+The validator is only called when the INI setting is set or modified (written to), whenever this step happens.
 
-.. warning:: If you want the global to be updated with the INI setting value, you'll need a validator. Such a mechanism 
-             is not magicaly performed by the engine, but must be done explicitly into the validator
+.. warning:: If you want the global variable to be updated with the INI setting value, you'll need a validator. Such a 
+             mechanism is not magicaly performed by the engine, but must be done explicitly into the validator.
 
 Let's see the ``onUpdateLongGEZero()`` source code::
 
@@ -276,8 +297,8 @@ Let's see the ``onUpdateLongGEZero()`` source code::
 
 Like you can see, there is nothing complex. Your validator is given the ``new_value`` and must validate against it. 
 Remember that ``new_value`` is of type :doc:`zend_string * <../internal_types/strings/zend_strings>`. The 
-``onUpdateLongGEZero()`` takes the value as a long and checks it is >=0. One must return SUCCESS from the validator if 
-OK and FAILURE if not.
+``onUpdateLongGEZero()`` takes the value as a long and checks if it is a positive integer. One must return ``SUCCESS`` 
+from the validator if everything went right and ``FAILURE`` if not.
 
 Then comes the part to update the global. ``mh_arg`` variables are used to carry any type of information to your 
 validator.
@@ -290,7 +311,7 @@ is accessed differently if you are using ZTS mode or not. More informations abou
 :doc:`can be found here <globals_management>`.
 
 ``mh_arg1`` is passed the computed offset of your global member (``max_rnd`` for us), and you must slice the memory 
-yourself to get a pointer to it. Taht's why we stored ``mh_arg2`` as a generic ``char *`` pointer and casted 
+yourself to get a pointer to it. That's why we stored ``mh_arg2`` as a generic ``char *`` pointer and casted 
 ``mh_arg1`` to ``size_t``.
 
 Then, you simply update the content with the validated value by writing into the pointer. ``mh_arg3`` is unused actually.
@@ -332,19 +353,19 @@ for example::
         STD_PHP_INI_ENTRY("pib.rnd_max", "100", PHP_INI_ALL, onUpdateMaxRnd, max_rnd, zend_pib_globals, pib_globals)
     PHP_INI_END()
 
-.. note:: It is safe to write to an unsigned long from a long, as soon as the ranges are checked, which the validator 
+.. note:: It is safe to write to an *unsigned long* from a *long*, as soon as the ranges are checked, which the validator 
           does.
 
 Now, if the user wants to modify the setting and pass a wrong value that does not validate, ``ini_set()`` simply will 
-return FALSE to the userland, and will not modify the value:
+return false to the userland, and will not modify the value:
 
 .. code-block:: php
 
-    ini_set('pib.rnd_max', 2048);
+    ini_set('pib.rnd_max', 2048); /* returns false as 2048 is > 1000 */
     
-In the opposite case, ``ini_set()`` returns the old value and modifies the value. The new provided value becomes the 
-current "local" value whereas the default preceding value stays as the "master value". ``phpinfo()`` or ``ini_get_all()`` 
-detail such values. Example:
+In the opposite case, ``ini_set()`` returns the old value and modifies current the value. The new provided value becomes
+ the current "local" value whereas the default preceding value stays as the "master value". ``phpinfo()`` or 
+ ``ini_get_all()`` detail such values. Example:
 
 .. code-block:: php
 
@@ -376,17 +397,18 @@ For example, for our tiny example, the validator we designed is called three tim
 
 Keep also in mind that the value accessor is checked against by ``ini_set()``. If we would have designed a 
 ``PHP_INI_SYSTEM`` setting, then the user would not have been able to modify it using ``ini_set()``, as ``ini_set()`` 
-uses ``PHP_INI_USER`` as accessor. The mismatch would then have benn detected soon and the validator would not have 
-been called.
+uses ``PHP_INI_USER`` as accessor. The mismatch would then have been detected and the validator would not have 
+been called by the engine in such a case.
 
 If you need to change the INI setting value into your extension at runtime, the internal call is 
 ``zend_alter_ini_entry()``, this is what userland ``ini_set()`` uses.
 
 Using a displayer
 -----------------
 
-The last thing you need to know about INI settings is the ``displayer()`` callback. That one is triggered any time the 
-userland asks to "see" your INI setting value, that is through the usage of ``phpinfo()`` or ``php --ri``.
+The last thing you need to know about INI settings is the ``displayer()`` callback. It is less used in practice, it is 
+triggered any time the userland asks to "print" your INI setting value, that is through the usage of 
+``phpinfo()`` or ``php --ri``.
 
 If you provide no displayer, a default one will be used. See it::
 
@@ -395,7 +417,7 @@ If you provide no displayer, a default one will be used. See it::
     Directive => Local Value => Master Value
     pib.rnd_max => 120 => 120
 
-The default displayer takes the INI setting value (which, as a reminder, is of type ``zend_string \*``), and simply 
+The default displayer takes the INI setting value (which, as a reminder, is of type ``zend_string *``), and simply 
 displays it. If no value were found or the value were the empty string, then it displays the string "no value".
 
 To take hand on such a process, we must declare a ``displayer()`` callback that will be called. Let's try to represent