extensions MINFO() additions

Author: Julien Pauli

Book/php7/extensions_design.rst

@@ -13,7 +13,9 @@ Contents:
 
     extensions_design/php_lifecycle.rst
     extensions_design/extension_skeleton.rst
-    extensions_design/zend_extensions.rst
+    extensions_design/php_functions.rst
     extensions_design/globals_management.rst
+    extensions_design/extension_infos.rst
     extensions_design/ini_settings.rst
-    extensions_design/php_functions.rst
+    extensions_design/zend_extensions.rst
+

Book/php7/extensions_design/extension_infos.rst

@@ -0,0 +1,99 @@
+Publishing extension informations
+=================================
+
+Extensions can publish informations asked by ``phpinfo()`` or the Reflection API. Let's see that together.
+
+This chapter won't be too long as there is really no difficulty.
+
+MINFO() hook
+------------
+
+Everything takes place in the ``MINFO()`` hook you declared, if you declared one.  If you declared none, then the engine 
+will run a default function to print informations about your extension. That function will only print the version of 
+your extension and the :doc:`INI entries <ini_settings>` you eventually declared. If you want to hook into such 
+process, you must declare an ``MINFO()`` :doc:`hook <php_lifecycle>` in your extension structure.
+
+.. note:: Everything takes place in `ext/standard/info.c <https://github.com/php/php-src/blob/
+          ce64b82ebb2ac87e53cb85c312eafc8c5c37b112/ext/standard/info.c>`_ , you may read that file. Printing 
+          information about PHP extensions is done by the engine by calling `php_info_print_module() 
+          <https://github.com/php/php-src/blob/ce64b82ebb2ac87e53cb85c312eafc8c5c37b112/ext/standard/info.c#L139>`_
+
+Here is a simple ``MINFO()`` example::
+
+    #include "php/main/SAPI.h"
+    #include "ext/standard/info.h"
+
+    PHP_MINFO_FUNCTION(pib)
+    {
+        time_t t;
+        char cur_time[32];
+
+        time(&t);
+        php_asctime_r(localtime(&t), cur_time);
+
+        php_info_print_table_start();
+            php_info_print_table_colspan_header(2, "PHPInternalsBook");
+            php_info_print_table_row(2, "Current time", cur_time);
+        php_info_print_table_end();
+
+        php_info_print_box_start(0);
+            if (!sapi_module.phpinfo_as_text) {
+                php_write(PIB_HTML, strlen(PIB_HTML));
+            } else {
+                php_write(PIB_TXT, strlen(PIB_TXT));
+            }
+        php_info_print_box_end();
+    }
+
+    zend_module_entry pib_module_entry = {
+        STANDARD_MODULE_HEADER,
+        "pib",
+        NULL, /* Function entries */
+        NULL, /* Module init */
+        NULL, /* Module shutdown */
+        NULL, /* Request init */
+        NULL, /* Request shutdown */
+        PHP_MINFO(pib), /* Module information */
+        "0.1", /* Replace with version number for your extension */
+        STANDARD_MODULE_PROPERTIES
+    };
+
+.. image:: ./images/php_minfo.png
+   :align: center
+
+What you basically have to do is to deal with ``php_info_print_*()`` API, that allows to print into the output stream 
+that is generated. If you want to print some raw informations, a simple ``php_write()`` is enough. ``php_write()`` just 
+writes what you pass as argument onto the SAPI output stream, whereas ``php_info_print_*()`` API does as well, but 
+before formats the content using HTML *table-tr-td* tags if the output is expected to be HTML, or simple spaces if not.
+
+Like you can see, you need to include *ext/standard/info.h* to access the ``php_info_print_*()`` API, and you will need 
+*php/main/SAPI.h* to access the ``sapi_module`` symbol. That symbol is global, it represents the current *SAPI* used by 
+the PHP process. The ``phpinfo_as_text`` field inform if you are going to write in a "Web" SAPI like *php-fpm* f.e, or 
+in a "text" one, like *php-cli*.
+
+What will trigger your ``MINFO()`` hook are :
+
+* Calls to userland ``phpinfo()`` function
+* ``php -i``, ``php-cgi -i``, ``php-fpm -i``. More generaly ``<SAPI_binary> - i``
+* ``php --ri`` or userland ``ReflectionExtension::info()``
+
+.. note:: Take care of the output formating. Probe for ``sapi_module.phpinfo_as_text`` if you need to change between 
+          text and HTML formatting. You don't know how your extensions' infos will be called by userland.
+
+If you need to display your INI settings, just call for the ``DISPLAY_INI_ENTRIES()`` macro into your ``MINFO()``. This 
+macro resolves to `display_ini_entries() 
+<https://github.com/php/php-src/blob/4903f044d3a65de5b1c457d9eb618c9e247f7086/main/php_ini.c#L167>`_.
+
+A note about the Reflection API
+-------------------------------
+
+The Reflection heavilly uses your ``zend_module_entry`` structure. For example, when you call 
+``ReflectionExtension::getVersion()``, the API just reads the version field of your ``zend_module_entry`` structure.
+
+Same to discover functions, your ``zend_module_entry`` has got a ``const struct _zend_function_entry *functions`` member 
+which is used to register PHP functions.
+
+Basically, the PHP userland Reflection API just reads your ``zend_module_entry`` structure and publishes those 
+informations. It may also use your ``module_number`` to gather back informations your extension registered at different 
+locations against the engine. For example, ``ReflectionExtension::getINIentries()`` or 
+``ReflectionExtension::getClasses()`` use this.

Book/php7/extensions_design/globals_management.rst

@@ -198,7 +198,7 @@ Let's zero our random value::
         PHP_MODULE_GLOBALS(pib),
         PHP_GINIT(pib),
         PHP_GSHUTDOWN(pib),
-        NULL, /* MINFO() */
+        NULL, /* PRSHUTDOWN() */
         STANDARD_MODULE_PROPERTIES_EX
     };
 
@@ -367,15 +367,20 @@ Here is the patched example introducing true globals, we just show the diff abou
     static zend_string *more, *less;
     static zend_ulong max = 100;
 
+    static void register_persistent_string(char *str, zend_string **result)
+    {
+        *result = zend_string_init(str, strlen(str), 1);
+        zend_string_hash_val(*result);
+        
+        GC_FLAGS(*result) |= IS_INTERNED;
+    }
+
     PHP_MINIT_FUNCTION(pib)
     {
         char *pib_max;
 
-        more = zend_string_init("more", strlen("more"), 1);
-        less = zend_string_init("less", strlen("less"), 1);
-
-        GC_FLAGS(more) |= IS_STR_INTERNED;
-        GC_FLAGS(less) |= IS_STR_INTERNED;
+        register_persistent_string("more", &more);
+        register_persistent_string("less", &less);
 
         if (pib_max = getenv("PIB_RAND_MAX")) {
             if (!strchr(pib_max, '-')) {
@@ -421,9 +426,10 @@ What happened here is that we created two :doc:`zend_string <../internal_types/s
 and ``less``. Those strings don't need to be created and destroyed anytime they are used like it was done before. Those 
 are immutable strings that can be allocated once and reused anytime needed, as soon as they stay immutable 
 (aka : read-only). We initialize those two strings in ``MINIT()`` using a persistent allocation in 
-``zend_string_init()``, and we tell the zval garbage collector those strings are interned so that it will never ever 
-try to destroy them (however it could need to copy them if they were used as part of a write operation, such as a 
-concatenation). Obviously we don't forget to destroy such strings in ``MSHUTDOWN()``.
+``zend_string_init()``, we precompute their hash now (instead of having the very first request doing it), and we tell 
+the zval garbage collector those strings are interned so that it will never ever try to destroy them (however it could 
+need to copy them if they were used as part of a write operation, such as a concatenation). Obviously we don't forget 
+to destroy such strings in ``MSHUTDOWN()``.
 
 Then in ``MINIT()`` we probe for a ``PIB_RAND_MAX`` environment and use it as the maximum range value for our random 
 number pick. As we use an unsigned integer and we know ``strtoull()`` won't complain about negative numbers (and thus