Document Dom\Attr methods

php · Dec 2, 2024 · c35be53 · c35be53
1 parent 5afc2f6
commit c35be53
Show file tree

Hide file tree

Showing 5 changed files with 263 additions and 6 deletions.
diff --git a/reference/dom/dom/attr/isid.xml b/reference/dom/dom/attr/isid.xml
@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xml:id="dom-attr.isid" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <refnamediv>
+  <refname>Dom\Attr::isId</refname>
+  <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('domattr.isid')/db:refnamediv/db:refpurpose)">
+   <xi:fallback/>
+  </xi:include>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis role="Dom\\Attr">
+   <modifier>public</modifier> <type>bool</type><methodname>Dom\Attr::isId</methodname>
+   <void/>
+  </methodsynopsis>
+  <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('domattr.isid')/db:refsect1[@role='description']/db:para[1])">
+   <xi:fallback/>
+  </xi:include>
+  <simpara>
+   According to the DOM standard this requires a DTD which defines the
+   attribute ID to be of type ID. You need to validate your document by
+   passing <constant>LIBXML_DTDVALID</constant> to the parse method.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  &no.function.parameters;
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('domattr.isid')/db:refsect1[@role='returnvalues']/*)">
+   <xi:fallback/>
+  </xi:include>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title>Dom\Attr::isId() Example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+// We need to validate our document before referring to the id
+$doc = Dom\XMLDocument::createFromFile('book.xml', LIBXML_DTDVALID);
+
+// We retrieve the attribute named id of the chapter element
+$attr = $doc->getElementsByTagName('chapter')->item(0)->getAttributeNode('id');
+
+var_dump($attr->isId()); // bool(true)
+
+?>
+]]>
+   </programlisting>
+  </example>
+ </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/dom/attr/rename.xml b/reference/dom/dom/attr/rename.xml
@@ -0,0 +1,176 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xml:id="dom-attr.rename" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>Dom\Attr::rename</refname>
+  <refpurpose>Changes the qualified name or namespace of an attribute</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis role="Dom\\Attr">
+   <modifier>public</modifier> <type>void</type><methodname>Dom\Attr::rename</methodname>
+   <methodparam><type class="union"><type>string</type><type>null</type></type><parameter>namespaceURI</parameter></methodparam>
+   <methodparam><type>string</type><parameter>qualifiedName</parameter></methodparam>
+  </methodsynopsis>
+  <simpara>
+   This method changes the qualified name or namespace of an attribute.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>namespaceURI</parameter></term>
+     <listitem>
+      <simpara>
+       The new namespace <acronym>URI</acronym> of the attribute.
+      </simpara>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>qualifiedName</parameter></term>
+     <listitem>
+      <simpara>
+       The new qualified name of the attribute.
+      </simpara>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.void;
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <variablelist>
+   <varlistentry>
+    <term><classname>DOMException</classname> with code <constant>Dom\NAMESPACE_ERR</constant></term>
+    <listitem>
+     <simpara>
+      Raised if there is an error with the namespace, as determined by
+      <parameter>qualifiedName</parameter>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><classname>DOMException</classname> with code <constant>Dom\INVALID_MODIFICATION_ERR</constant></term>
+    <listitem>
+     <simpara>
+      Raised if there already exists an attribute in the element with the same
+      qualified name.
+     </simpara>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example xml:id="dom-attr.rename.example.basic">
+   <title><methodname>Dom\Attr::rename</methodname> example to change both the namespace and qualified name</title>
+   <simpara>
+    This changes the qualified name of <literal>my-attr</literal> to
+    <literal>my-new-attr</literal> and also changes its namespace to
+    <literal>urn:my-ns</literal>.
+   </simpara>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$doc = Dom\XMLDocument::createFromString('<root my-attr="value"/>');
+
+$root = $doc->documentElement;
+$attribute = $root->attributes['my-attr'];
+$attribute->rename('urn:my-ns', 'my-new-attr');
+
+echo $doc->saveXml();
+
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<root xmlns:ns1="urn:my-ns" ns1:my-new-attr="value"/>
+]]>
+   </screen>
+  </example>
+  <example xml:id="dom-attr.rename.example.only-name">
+   <title><methodname>Dom\Attr::rename</methodname> example to change only the qualified name</title>
+   <simpara>
+    This only changes the qualified name of <literal>my-attr</literal>
+    and keeps the namespace <acronym>URI</acronym> the same.
+   </simpara>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$doc = Dom\XMLDocument::createFromString('<root my-attr="value"/>');
+
+$root = $doc->documentElement;
+$attribute = $root->attributes['my-attr'];
+$attribute->rename($attribute->namespaceURI, 'my-new-attr');
+
+echo $doc->saveXml();
+
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<root my-new-attr="value"/>
+]]>
+   </screen>
+  </example>
+ </refsect1>
+
+ <refsect1 role="notes">
+  &reftitle.notes;
+  <note>
+   <simpara>
+    It is sometimes necessary to change
+    the qualified name and namespace <acronym>URI</acronym> together in one
+    step to not break any namespace rules.
+   </simpara>
+  </note>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>Dom\Element::rename</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/dom/dom-attr.xml b/reference/dom/dom/dom-attr.xml
@@ -158,6 +158,6 @@
 
  </partintro>
 
-<!-- &reference.dom.dom.entities.attr; -->
+ &reference.dom.dom.entities.attr;
 
 </reference>
diff --git a/reference/dom/domattr/isid.xml b/reference/dom/domattr/isid.xml
@@ -31,9 +31,9 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   &return.success;
-  </para>
+  <simpara>
+   Returns &true; if this attribute is a defined ID, &false; otherwise.
+  </simpara>
  </refsect1>
  <refsect1 role="examples">
   &reftitle.examples;
@@ -44,11 +44,11 @@
 <![CDATA[
 <?php
 
-$doc = new DomDocument;
+$doc = new DOMDocument;
 
 // We need to validate our document before referring to the id
 $doc->validateOnParse = true;
-$doc->Load('book.xml');
+$doc->load('book.xml');
 
 // We retrieve the attribute named id of the chapter element
 $attr = $doc->getElementsByTagName('chapter')->item(0)->getAttributeNode('id');

diff --git a/reference/dom/versions.xml b/reference/dom/versions.xml
@@ -229,6 +229,9 @@
  <function name="dom\tokenlist" from="PHP 8 &gt;= 8.4.0"/>
  <function name="dom\xmldocument" from="PHP 8 &gt;= 8.4.0"/>
  <function name="dom\xpath" from="PHP 8 &gt;= 8.4.0"/>
+
+ <function name="dom\attr::isid" from="PHP 8 &gt;= 8.4.0"/>
+ <function name="dom\attr::rename" from="PHP 8 &gt;= 8.4.0"/>
 </versions>
 <!-- Keep this comment at the end of the file
 Local variables: