Docs: add a page about zend_constant

Work towards #15954

docs/source/core/data-structures/index.rst

@@ -8,5 +8,6 @@
    zval
    reference-counting
    zend_string
+   zend_constant
 
 This section provides an overview of the core data structures used in php-src.

docs/source/core/data-structures/zend_constant.rst

@@ -0,0 +1,71 @@
+###############
+ zend_constant
+###############
+
+PHP constants (referring to non-class constants) are stored in a dedicated
+structure ``zend_constant``, which holds both the value of the constant and
+details for using it.
+
+************
+ definition
+************
+
+.. code:: c
+
+   typedef struct _zend_constant {
+       zval value;
+       zend_string *name;
+       zend_string *filename;
+   } zend_constant;
+
+The ``value`` field stores both the value itself and some metadata. The ``name``
+and ``filename`` store the name of the constant and the name of the file in
+which it was defined.
+
+******
+ value
+******
+
+The value of the constant is stored in the :doc:`./zval` ``value``. However,
+since the ``zval`` structure has extra space, for constants this is used to
+store both the number of the module that the constant was defined in, and a
+combination of the flags that affect the usage of the constant.
+
+This extra information is placed in the ``uint32_t`` field
+``value.u2.constant_flags``. 
+
+The bottom 16 bits are used to hold flags about the constant
+
+.. code:: c
+
+   #define CONST_PERSISTENT     (1<<0) /* Persistent */
+   #define CONST_NO_FILE_CACHE  (1<<1) /* Can't be saved in file cache */
+   #define CONST_DEPRECATED     (1<<2) /* Deprecated */
+   #define CONST_OWNED          (1<<3) /* constant should be destroyed together
+                                            with class */
+
+These bottom 16 bits can be accessed with the ``ZEND_CONSTANT_FLAGS()`` macro,
+which is given a ``zend_constant`` pointer as a parameter.
+
+On the other hand, the top 16 bits are used to store the number of the PHP
+module that registered the constant. For constants defined by the user, the
+module number stored will be ``PHP_USER_CONSTANT``. This module number can be
+accessed with the ``ZEND_CONSTANT_MODULE_NUMBER()`` macro, which is likewise
+given a ``zend_constant`` pointer as a parameter.
+
+******
+ name
+******
+
+The ``name`` holds a :doc:`zend_string` with the name of the constant, to allow
+searching for constants that have already been defined. This string is released
+when the constant itself is freed.
+
+******
+ filename
+******
+
+Finally, the ``filename`` holds another ``zend_string`` with the name of the
+file in which the constant was defined, or ``NULL`` if not defined userland
+code. This field provides the foundation for the PHP method
+``ReflectionConstant::getFileName()``.