From 6ddd47d8ba75853c1ff75cf45483f0ef161e4449 Mon Sep 17 00:00:00 2001 From: Daniel Scherzer Date: Fri, 6 Dec 2024 13:35:13 -0800 Subject: [PATCH 1/2] Docs: add a page about zend_constant Work towards #15954 --- docs/source/core/data-structures/index.rst | 1 + .../core/data-structures/zend_constant.rst | 71 +++++++++++++++++++ 2 files changed, 72 insertions(+) create mode 100644 docs/source/core/data-structures/zend_constant.rst diff --git a/docs/source/core/data-structures/index.rst b/docs/source/core/data-structures/index.rst index 327e025b92c7..8fcb860f686b 100644 --- a/docs/source/core/data-structures/index.rst +++ b/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. diff --git a/docs/source/core/data-structures/zend_constant.rst b/docs/source/core/data-structures/zend_constant.rst new file mode 100644 index 000000000000..caddbd78350a --- /dev/null +++ b/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()``. From c3cd4d83c716b4b532492ac80675b8f67014cfef Mon Sep 17 00:00:00 2001 From: Daniel Scherzer Date: Fri, 6 Dec 2024 13:38:16 -0800 Subject: [PATCH 2/2] Fix formatting --- .../core/data-structures/zend_constant.rst | 53 ++++++++----------- 1 file changed, 23 insertions(+), 30 deletions(-) diff --git a/docs/source/core/data-structures/zend_constant.rst b/docs/source/core/data-structures/zend_constant.rst index caddbd78350a..a4245d6e3c13 100644 --- a/docs/source/core/data-structures/zend_constant.rst +++ b/docs/source/core/data-structures/zend_constant.rst @@ -2,9 +2,8 @@ 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. +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 @@ -18,21 +17,18 @@ details for using it. 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. +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. +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``. +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 @@ -44,28 +40,25 @@ The bottom 16 bits are used to hold flags about the constant #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. +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. +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. +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()``. +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()``.