[DOC-CVS] [doc-en] master: Document the Yar __info magic method and response id validation (#5807)

Author: Xinchen Hui (laruence)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-08-26T15:17:37+02:00

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

Document the Yar __info magic method and response id validation (#5807)

Document two behaviours that exist in the extension but were missing
from the manual:

- The __info magic method (since Yar 2.3.0): a protected method on the
  executor object that customises the service information page rendered
  on GET requests. Covered by a note and an example on
  Yar_Server::handle.
- Response transaction id validation (since Yar 2.4.0): the client
  rejects a response whose non-zero transaction id does not match the
  request it answers. Covered on Yar_Client_Protocol_Exception.

Changed paths:
  M  reference/yar/yar-client-protocol-exception.xml
  M  reference/yar/yar_server/handle.xml


Diff:

diff --git a/reference/yar/yar-client-protocol-exception.xml b/reference/yar/yar-client-protocol-exception.xml
index b46ead86b12c..6020b8001000 100644
--- a/reference/yar/yar-client-protocol-exception.xml
+++ b/reference/yar/yar-client-protocol-exception.xml
@@ -13,6 +13,14 @@
    <simpara>
     Thrown when the response from the RPC service violates the Yar protocol, for example an unsupported protocol address or a malformed response header (exception code <constant>YAR_ERR_PROTOCOL</constant>).
    </simpara>
+   <simpara>
+    As of Yar 2.4.0 this also includes a response whose transaction id
+    does not match the id of the request it answers. The client validates
+    the <literal>i</literal> field of each response; a response carrying
+    a different, non-zero transaction id (for example one misrouted by a
+    proxy) is rejected. Responses with a zero or missing transaction id
+    are still accepted for backward compatibility with older servers.
+   </simpara>
   </section>
 
   <section xml:id="yar-client-protocol-exception.synopsis">
diff --git a/reference/yar/yar_server/handle.xml b/reference/yar/yar_server/handle.xml
index 03076e507d9f..81d05acfc003 100644
--- a/reference/yar/yar_server/handle.xml
+++ b/reference/yar/yar_server/handle.xml
@@ -27,6 +27,16 @@
     <exceptionname>Yar_Server_Exception</exceptionname>.
    </simpara>
   </note>
+  <note>
+   <simpara>
+    As of Yar 2.3.0, the service information page can be customized by
+    defining a <literal>protected</literal> method named
+    <literal>__info</literal> on the executor object. When a GET request
+    arrives, Yar calls this method, passing it the markup of the page it
+    would otherwise render; if the method returns a &string;, that string
+    is sent to the client instead of the default page.
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -133,6 +143,33 @@ class API {
     }
 }
 
+$service = new Yar_Server(new API());
+$service->handle();
+?>
+]]>
+   </programlisting>
+  </example>
+  <example>
+   <title>Customizing the service information page with
+   <literal>__info</literal> (as of Yar 2.3.0)</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+class API {
+    public function some_method($parameter, $option = "foo") {
+        return "some_method";
+    }
+
+    /*
+     * Must be protected. It is called on GET requests with the markup of
+     * the page Yar would otherwise render, and its string return value is
+     * sent to the client instead.
+     */
+    protected function __info($markup) {
+        return "Hello world";
+    }
+}
+
 $service = new Yar_Server(new API());
 $service->handle();
 ?>