Add XSLTProcessor::registerPHPFunctionNS and DOMXPath::registerPhpFun…

…ctionNS (#4129) Co-authored-by: Gina Peter Banyard <girgias@php.net>
php · Feb 22, 2025 · 5677887 · 5677887
1 parent 1d4f5d1
commit 5677887
Show file tree

Hide file tree

Showing 4 changed files with 304 additions and 0 deletions.
diff --git a/reference/dom/domxpath/registerphpfunctionns.xml b/reference/dom/domxpath/registerphpfunctionns.xml
@@ -0,0 +1,158 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<refentry xml:id="domxpath.registerphpfunctionns" xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+  <refname>DOMXPath::registerPhpFunctionNS</refname>
+  <refpurpose>Register a PHP functions as namespaced XPath function</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis role="DOMXPath">
+   <modifier>public</modifier> <type>void</type><methodname>DOMXPath::registerPhpFunctionNS</methodname>
+   <methodparam><type>string</type><parameter>namespaceURI</parameter></methodparam>
+   <methodparam><type>string</type><parameter>name</parameter></methodparam>
+   <methodparam><type>callable</type><parameter>callable</parameter></methodparam>
+  </methodsynopsis>
+  <simpara>
+   This method enables the ability to use a PHP function as a namespaced XPath function
+   inside XPath expressions.
+  </simpara>
+
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>namespaceURI</parameter></term>
+    <listitem>
+     <simpara>
+      The URI of the namespace.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>name</parameter></term>
+    <listitem>
+     <simpara>
+      The local function name inside the namespace.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>callable</parameter></term>
+    <listitem>
+     <simpara>
+      The PHP function to call when the XPath function gets called within the XPath expression.
+      When a node list is passed as parameter to the callback,
+      they are arrays containing the matched DOM nodes.
+     </simpara>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <simpara>
+   &return.void;
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title>Register a namespaced XPath function and call it from the XPath expression</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$xml = <<<EOB
+<books>
+<book>
+ <title>PHP Basics</title>
+ <author>Jim Smith</author>
+ <author>Jane Smith</author>
+</book>
+<book>
+ <title>PHP Secrets</title>
+ <author>Jenny Smythe</author>
+</book>
+<book>
+ <title>XML basics</title>
+ <author>Joe Black</author>
+</book>
+</books>
+EOB;
+
+$doc = new DOMDocument;
+$doc->loadXML($xml);
+
+$xpath = new DOMXPath($doc);
+
+// Register the my: namespace (required)
+$xpath->registerNamespace("my", "urn:my.ns");
+
+// Register PHP functions (no restrictions)
+$xpath->registerPHPFunctionNS(
+    'urn:my.ns',
+    'substring',
+    fn (array $arg1, int $start, int $length) => substr($arg1[0]->textContent, $start, $length)
+);
+
+// Call substr function on the book title
+$nodes = $xpath->query('//book[my:substring(title, 0, 3) = "PHP"]');
+
+echo "Found {$nodes->length} books starting with 'PHP':\n";
+foreach ($nodes as $node) {
+   $title  = $node->getElementsByTagName("title")->item(0)->nodeValue;
+   $author = $node->getElementsByTagName("author")->item(0)->nodeValue;
+   echo "$title by $author\n";
+}
+
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+Found 2 books starting with 'PHP':
+PHP Basics by Jim Smith
+PHP Secrets by Jenny Smythe
+]]>
+   </screen>
+  </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>DOMXPath::registerNamespace</methodname></member>
+   <member><methodname>DOMXPath::query</methodname></member>
+   <member><methodname>DOMXPath::evaluate</methodname></member>
+   <member><methodname>XSLTProcessor::registerPHPFunctions</methodname></member>
+   <member><methodname>XSLTProcessor::registerPHPFunctionNS</methodname></member>
+  </simplelist>
+ </refsect1>
+
+</refentry>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/dom/versions.xml b/reference/dom/versions.xml
@@ -197,6 +197,7 @@
  <function name="domxpath::query" from="PHP 5, PHP 7, PHP 8"/>
  <function name="domxpath::registernamespace" from="PHP 5, PHP 7, PHP 8"/>
  <function name="domxpath::registerphpfunctions" from="PHP 5 &gt;= 5.3.0, PHP 7, PHP 8"/>
+ <function name="domxpath::registerphpfunctionns" from="PHP &gt;= 8.4.0"/>
  <function name="domxpath::quote" from="PHP 8 &gt;= 8.4.0"/>
 
  <function name="dom_import_simplexml" from="PHP 5, PHP 7, PHP 8"/>

diff --git a/reference/xsl/versions.xml b/reference/xsl/versions.xml
@@ -11,6 +11,7 @@
  <function name="XSLTProcessor::hasExsltSupport" from="PHP 5 &gt;= 5.0.4, PHP 7, PHP 8"/>
  <function name="XSLTProcessor::importStylesheet" from="PHP 5, PHP 7, PHP 8"/>
  <function name="XSLTProcessor::registerPhpFunctions" from="PHP 5 &gt;= 5.0.4, PHP 7, PHP 8"/>
+ <function name="XSLTProcessor::registerPhpFunctionNS" from="PHP &gt;= 8.4.0"/>
  <function name="XSLTProcessor::removeParameter" from="PHP 5, PHP 7, PHP 8"/>
  <function name="XSLTProcessor::setParameter" from="PHP 5, PHP 7, PHP 8"/>
  <function name="XSLTProcessor::setProfiling" from="PHP &gt;= 5.3.0, PHP 7, PHP 8"/>

diff --git a/reference/xsl/xsltprocessor/registerphpfunctionns.xml b/reference/xsl/xsltprocessor/registerphpfunctionns.xml
@@ -0,0 +1,144 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<refentry xml:id="xsltprocessor.registerphpfunctionns" xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+  <refname>XSLTProcessor::registerPHPFunctionNS</refname>
+  <refpurpose>Register a PHP function as namespaced XSLT function</refpurpose>
+ </refnamediv>
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis role="XSLTProcessor">
+   <modifier>public</modifier> <type>void</type><methodname>XSLTProcessor::registerPHPFunctionNS</methodname>
+   <methodparam><type>string</type><parameter>namespaceURI</parameter></methodparam>
+   <methodparam><type>string</type><parameter>name</parameter></methodparam>
+   <methodparam><type>callable</type><parameter>callable</parameter></methodparam>
+  </methodsynopsis>
+  <simpara>
+   This method enables the ability to use a PHP function as a namespaced XSLT functions within XSL stylesheets.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>namespaceURI</parameter></term>
+    <listitem>
+     <simpara>
+      The URI of the namespace.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>name</parameter></term>
+    <listitem>
+     <simpara>
+      The local function name inside the namespace.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>callable</parameter></term>
+    <listitem>
+     <simpara>
+      The PHP function to call when the XSL function gets called within the stylesheet.
+      When a node list is passed as parameter to the callback,
+      the argument becomes an array containing the matched dom nodes.
+     </simpara>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <simpara>
+   &return.void;
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title>Simple PHP Function call from a stylesheet</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$xml = <<<EOB
+<allusers>
+<user>
+ <uid>bob</uid>
+</user>
+<user>
+ <uid>joe</uid>
+</user>
+</allusers>
+EOB;
+$xsl = <<<EOB
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet version="1.0"
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    xmlns:my="urn:my.ns">
+<xsl:output method="html" encoding="utf-8" indent="yes"/>
+<xsl:template match="allusers">
+ <html><body>
+   <h2><xsl:value-of select="my:count(user/uid)" /> users</h2>
+   <table>
+   <xsl:for-each select="user">
+     <tr>
+      <td>
+       <xsl:value-of select="my:uppercase(string(uid))"/>
+      </td>
+     </tr>
+   </xsl:for-each>
+   </table>
+ </body></html>
+</xsl:template>
+</xsl:stylesheet>
+EOB;
+$xmldoc = new DOMDocument();
+$xmldoc->loadXML($xml);
+$xsldoc = new DOMDocument();
+$xsldoc->loadXML($xsl);
+
+$proc = new XSLTProcessor();
+$proc->registerPHPFunctionNS('urn:my.ns', 'uppercase', strtoupper(...));
+$proc->registerPHPFunctionNS('urn:my.ns', 'count', fn (array $arg1) => count($arg1));
+$proc->importStyleSheet($xsldoc);
+echo $proc->transformToXML($xmldoc);
+?>
+]]>
+   </programlisting>
+  </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>DOMXPath::registerPhpFunctionNS</methodname></member>
+   <member><methodname>DOMXPath::registerPhpFunctions</methodname></member>
+   <member><methodname>XSLTProcessor::registerPhpFunctions</methodname></member>
+  </simplelist>
+ </refsect1>
+
+</refentry>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->