/doc/core/: document `zend_string` APIs by LamentXU123 · Pull Request #21642 · php/php-src

LamentXU123 · 2026-04-05T13:33:31Z

This PR added (and also fixed) some internal APIs concerning zend_string, cc @iluuu1994 as we privately talk about the doc work before.

LamentXU123

Just commenting for easier reviewing

LamentXU123 · 2026-04-05T13:36:33Z

   -  -  Function/Macro [#persistent]_
      -  Description

-   -  -  ``ZSTR_INIT(s, p)``


I think the original doc is wrong. This should be ZSTR_INIT_LITERAL. Is it?

LamentXU123 · 2026-04-05T13:38:41Z

      -  Same as ``zend_string_concat2``, but for three character buffers.

   -  -  ``ZSTR_EMPTY_ALLOC()``
-      -  Gets an immutable, empty string. This does not allocate memory.


Return would be better in case of Get in functions

LamentXU123 · 2026-04-05T13:40:05Z

      -  Decreases the reference count and frees the string if it goes to 0.

-   -  -  ``zend_string_dup(s, p)``
-      -  Creates a true copy of the string in a new allocation, except if the string is interned.


How does this function related to reference counting? Shouldn't it be in the "create/allocate" section?

LamentXU123 · 2026-04-05T13:41:24Z


   -  -  ``ZSTR_HASH``
      -  ``Z_STRHASH[_P]``
-      -  Computes the string has if it hasn't already been, and returns it.


not sure if this fix is right, but the original one is wrong.

LamentXU123 · 2026-04-05T13:42:28Z

 API
 *****

-The string API is defined in ``Zend/zend_string.h``. It provides a number of functions for creating


It do provide other functions except just for creating new strings?

LamentXU123 · 2026-04-05T13:43:00Z

+hashing, and interning helpers.

-.. list-table:: ``zend_string`` creation
+.. list-table:: Creation and allocation APIs


Just to make things more accurate here

iluuu1994

Honestly, I wonder of how much use listing all functions and macros is. I think the docs should mainly focus on explaining concepts and core functions. Once you grasp that, you'll understand all the variations.

If we want to document these functions, maybe we should see if we can document them in-source instead and export the synopses somehow?

Anyway, I don't object but I think the wording could be improved.

Also: Yes, I started reviewing this in April. 😄

iluuu1994 · 2026-04-06T15:33:26Z

-The string API is defined in ``Zend/zend_string.h``. It provides a number of functions for creating
-new strings.
+The string API is defined in ``Zend/zend_string.h``. It contains creation, resizing, comparison,
+hashing, and interning helpers.


I'd avoid the term helper, it's not clearly defined. Please keep the term function. E.g.:

It provides functions for creating, resizing, comparing, hashing and interning strings.

iluuu1994 · 2026-09-19T21:36:43Z

+      -  Allocates a new string of length ``l`` without initializing its contents.
+
+   -  -  ``zend_string_safe_alloc(n, m, l, p)``
+      -  Allocates ``n * m + l`` bytes of payload with overflow checks.


Payload seems like the wrong term, it implies data rather than storage. "A string of length n * m + l" might work better.

iluuu1994 · 2026-09-19T21:42:24Z

         memory.

+   -  -  ``ZSTR_MAX_OVERHEAD``
+      -  Maximum allocator/header overhead used by ``zend_string``.


Do we need to document this macro? It's barely used and the description isn't very good. Alternatively:

Maximum number of bytes added to some raw string buffer to form for a zend_string allocation.

iluuu1994 · 2026-09-19T21:45:18Z

+
+      -  Changes the size of the string. If the string has a reference count greater than 1 or if
+         the string is interned, a new string is created. You must always use the return value of
+         this function, as the original array may have been moved to a new location in memory.


Suggested change

this function, as the original array may have been moved to a new location in memory.

this function, as the original string may have been moved to a new location in memory.

iluuu1994 · 2026-09-19T21:46:16Z

+      -  Resizes a string to ``n * m + l`` bytes with overflow checks. Allocates a string of length
+         ``n * m + l``. This function is commonly useful for encoding changes.


This is odd wording, with two conflicting sentences.

iluuu1994 · 2026-09-19T21:55:21Z

+         also returns the original string. This makes code more readable in practice.
+
+   -  -  ``zend_string_delref(s)``
+      -  Decrements the reference count of a non-interned string.


Should clarify to only use this when you're certain that the refcount >1, which is rare.

iluuu1994 · 2026-09-19T21:55:51Z

-      -  Creates a true copy of the string in a new allocation, except if the string is interned.
+   -  -  ``zend_string_release_ex(s, p)``
+      -  Like ``zend_string_release()``, but allows you to specify whether the passed string is
+         persistent or non-persistent. If it is persistent, ``p`` should be ``0``.


Suggested change

persistent or non-persistent. If it is persistent, ``p`` should be ``0``.

persistent or non-persistent. If it is persistent, ``p`` should be ``false``.

iluuu1994 · 2026-09-19T21:56:20Z


-   -  -  ``zend_string_realloc(s, l, p)``
+      -  Frees a non-interned string directly. The caller must ensure it is no longer shared.
+         Requires refcount 1 or immutable.You should avoid using these functions, as it is easy to


Suggested change

Requires refcount 1 or immutable.You should avoid using these functions, as it is easy to

Requires refcount 1 or immutable. You should avoid using these functions, as it is easy to

iluuu1994 · 2026-09-19T21:56:34Z

+      -  Frees a non-interned string directly. The caller must ensure it is no longer shared.
+         Requires refcount 1 or immutable.You should avoid using these functions, as it is easy to
+         introduce critical bugs when some API changes from returning new strings to reusing
+         existing ones.


Awkward wording.

iluuu1994 · 2026-09-19T21:58:14Z

+   -  -  ``zend_string_equals(s1, s2)``
+      -  Full equality check for two ``zend_string`` values.
+   -  -  ``zend_string_equal_content(s1, s2)``
+      -  Full equality check assuming both arguments are ``zend_string`` pointers.


This does not explain the difference to zend_string_equals(). zend_string_equals() includes a fast pointer equality test.

LamentXU123 · 2026-09-21T10:14:27Z

Thanks for reviewing! I am far from a native English user so yeah some wording might be bad.

Co-authored-by: Ilija Tovilo <1752683+iluuu1994@users.noreply.github.com>

LamentXU123 commented Apr 5, 2026

View reviewed changes

alecpl reviewed Apr 6, 2026

View reviewed changes

Comment thread docs/source/core/data-structures/zend_string.rst

iluuu1994 reviewed Sep 19, 2026

View reviewed changes

LamentXU123 force-pushed the doc-1 branch from aee05a4 to 524a1b3 Compare September 21, 2026 10:15

LamentXU123 and others added 7 commits September 21, 2026 18:17

Update zend_string.rst

a6ec04e

small fixes

0342c10

fix doc ci

8f55901

adjust sequence

17ee1f9

Update zend_string.rst

409874b

Update zend_string.rst

e01a001

feedback

a364b50

Co-authored-by: Ilija Tovilo <1752683+iluuu1994@users.noreply.github.com>

LamentXU123 force-pushed the doc-1 branch from 524a1b3 to a364b50 Compare September 21, 2026 10:20

LamentXU123 requested a review from iluuu1994 September 25, 2026 19:21

	this function, as the original array may have been moved to a new location in memory.
	this function, as the original string may have been moved to a new location in memory.

		- Resizes a string to ``n * m + l`` bytes with overflow checks. Allocates a string of length
		``n * m + l``. This function is commonly useful for encoding changes.

	persistent or non-persistent. If it is persistent, ``p`` should be ``0``.
	persistent or non-persistent. If it is persistent, ``p`` should be ``false``.

	Requires refcount 1 or immutable.You should avoid using these functions, as it is easy to
	Requires refcount 1 or immutable. You should avoid using these functions, as it is easy to

Conversation

LamentXU123 commented Apr 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

LamentXU123 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LamentXU123 Apr 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LamentXU123 Apr 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

iluuu1994 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LamentXU123 commented Sep 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

LamentXU123 commented Apr 5, 2026 •

edited

Loading

LamentXU123 Apr 5, 2026 •

edited

Loading

LamentXU123 Apr 5, 2026 •

edited

Loading