[DOC-CVS] [doc-en] master: Add warning for header_register_callback usage (#5760)

Author: Kevin Boyd (beryllium)
Committer: GitHub (web-flow)
Pusher: jordikroon
Date: 2026-08-14T09:11:42+02:00

Commit: https://github.com/php/doc-en/commit/abdc23836d3f42399028c1174961107e70ada52d
Raw diff: https://github.com/php/doc-en/commit/abdc23836d3f42399028c1174961107e70ada52d.diff

Add warning for header_register_callback usage (#5760)

* Add warning for header_register_callback usage

Added a warning about callback de-registration in header_register_callback.

Changed paths:
  M  reference/network/functions/header-register-callback.xml


Diff:

diff --git a/reference/network/functions/header-register-callback.xml b/reference/network/functions/header-register-callback.xml
index 04d5a9252079..1fccfc233790 100644
--- a/reference/network/functions/header-register-callback.xml
+++ b/reference/network/functions/header-register-callback.xml
@@ -21,6 +21,14 @@
    headers to be sent, and before any other output is sent, creating a window
    to manipulate the outgoing headers before being sent.
   </para>
+  <warning>
+    <simpara>
+      Callbacks are not stacked. Subsequent calls to <function>header_register_callback</function>
+      will silently de-register any existing <parameter>callback</parameter>, regardless of where
+      it was set. Be aware that dependencies may overwrite the callback.
+      Troubleshooting this scenario can be difficult.
+    </simpara>
+  </warning>
  </refsect1>
 
  <refsect1 role="parameters">