feat: support native ODText bookmarks

Serialize PHPWord point bookmarks as native ODF text bookmarks and add regression coverage and documentation.

Co-authored-by: Codex <noreply@openai.com>

Author: potofcoffee

docs/usage/elements/bookmark.md

@@ -0,0 +1,11 @@
+# Bookmark
+
+Bookmarks identify a position in a document so that fields and links can refer to it.
+
+``` php
+<?php
+
+$section->addBookmark('introduction');
+```
+
+The ODText writer serializes bookmarks as native ODF point bookmarks. Bookmark ranges and cross-reference fields are separate features.

mkdocs.yml

@@ -53,6 +53,7 @@ nav:
       - Chart: 'usage/elements/chart.md'
       - Checkbox: 'usage/elements/checkbox.md'
       - Comment: 'usage/elements/comment.md'
+      - Bookmark: 'usage/elements/bookmark.md'
       - Field: 'usage/elements/field.md'
       - Footnote & Endnote: 'usage/elements/note.md'
       - Formula: 'usage/elements/formula.md'

src/PhpWord/Writer/ODText/Element/Bookmark.php

@@ -0,0 +1,49 @@
+<?php
+
+/**
+ * This file is part of PHPWord - A pure PHP library for reading and writing
+ * word processing documents.
+ *
+ * PHPWord is free software distributed under the terms of the GNU Lesser
+ * General Public License as published by the Free Software Foundation.
+ *
+ * For the full copyright and license information, please read the LICENSE
+ * file that was distributed with this source code. For the full list of
+ * contributors, visit https://github.com/PHPOffice/PHPWord/contributors.
+ *
+ * @see         https://github.com/PHPOffice/PHPWord
+ *
+ * @license     http://www.gnu.org/licenses/lgpl.txt LGPL version 3
+ */
+
+namespace PhpOffice\PhpWord\Writer\ODText\Element;
+
+/**
+ * Bookmark element writer.
+ */
+class Bookmark extends AbstractElement
+{
+    /**
+     * Write bookmark element.
+     */
+    public function write(): void
+    {
+        $xmlWriter = $this->getXmlWriter();
+        $element = $this->getElement();
+        if (!$element instanceof \PhpOffice\PhpWord\Element\Bookmark) {
+            return;
+        }
+
+        if (!$this->withoutP) {
+            $xmlWriter->startElement('text:p');
+        }
+
+        $xmlWriter->startElement('text:bookmark');
+        $xmlWriter->writeAttribute('text:name', $element->getName());
+        $xmlWriter->endElement();
+
+        if (!$this->withoutP) {
+            $xmlWriter->endElement();
+        }
+    }
+}

tests/PhpWordTests/Writer/ODText/ElementTest.php

@@ -56,8 +56,44 @@ public function testUnmatchedElements(): void
         }
     }
 
+    /**
+     * Test bookmark element.
+     */
+    public function testBookmarkElement(): void
+    {
+        $phpWord = new PhpWord();
+        $section = $phpWord->addSection();
+        $section->addBookmark('test_bookmark');
+
+        $doc = TestHelperDOCX::getDocument($phpWord, 'ODText');
+
+        $path = '/office:document-content/office:body/office:text/text:section/text:p/text:bookmark';
+        self::assertTrue($doc->elementExists($path));
+        self::assertEquals('test_bookmark', $doc->getElementAttribute($path, 'text:name'));
+    }
+
+    /**
+     * Test multiple bookmarks and bookmarks in text runs.
+     */
+    public function testMultipleBookmarksAndNestedBookmarkElement(): void
+    {
+        $phpWord = new PhpWord();
+        $section = $phpWord->addSection();
+        $section->addBookmark('first_bookmark');
+        $section->addBookmark('bookmark_with_&');
+        $textRun = $section->addTextRun();
+        $textRun->addBookmark('nested_bookmark');
+
+        $doc = TestHelperDOCX::getDocument($phpWord, 'ODText');
+
+        $path = '/office:document-content/office:body/office:text/text:section//text:bookmark';
+        self::assertTrue($doc->elementExists("($path)[3]"));
+        self::assertEquals('first_bookmark', $doc->getElementAttribute("($path)[1]", 'text:name'));
+        self::assertEquals('bookmark_with_&', $doc->getElementAttribute("($path)[2]", 'text:name'));
+        self::assertEquals('nested_bookmark', $doc->getElementAttribute("($path)[3]", 'text:name'));
+    }
+
     // ODT Line Element not yet implemented
-    // ODT Bookmark not yet implemented
     // ODT Table with style name not yet implemented (Word test defective)
     // ODT Shape Elements not yet implemented
     // ODT Chart Elements not yet implemented