adjust docs, mark DOMLettersIterator as internal

CHANGELOG.md

@@ -2,7 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
-## [3.0.0-beta] - 2023-10-29
+## [3.0.0] - TBD
+This version is a complete reworked version of utils bundle. 
+The goal was to have a non-inversive bundle of useful helpers for contao.
+This version will no longer add asset to your installation, do not dispatch curious caching events or similar.
+
+The main changes are:
+- All classic util classes and aliases are removed. Only the ones accessible via the `Utils` service are available.
+- All deprecated services and functions are removed.
+- Nearly all twig filters were dropped.
+- No more bundled assets. You install the asset component still as yarn dependency.
+
+More specific changes, but not limited to:
+- Changed: bundle class name is now `HeimrichHannotUtilsBundle`
 - Changed: DcaUtil::getDcaFields() array options now throw error if not of type array
 - Removed: ContainerUtil::isBundleActive()
 - Removed: UrlUtil::removeQueryStringParameterToUrl()

README.md

@@ -5,7 +5,7 @@
 ![example branch parameter](https://github.com/heimrichhannot/contao-utils-bundle/actions/workflows/ci.yml/badge.svg?branch=v3)
 [![Coverage Status](https://coveralls.io/repos/github/heimrichhannot/contao-utils-bundle/badge.svg?branch=v3)](https://coveralls.io/github/heimrichhannot/contao-utils-bundle?branch=v3)
 
-> Hi, you're looking on a very new version of utils bundle, version 3! If you're looking for version 2, please check the [v2 branch](https://github.com/heimrichhannot/contao-utils-bundle/tree/v2).
+> Hi, you're looking on a very new version of utils bundle, version 3! See [CHANGELOG.md](CHANGELOG.md) for more information! If you're looking for version 2, please check the [v2 branch](https://github.com/heimrichhannot/contao-utils-bundle/tree/v2).
 
 Utils Bundle is a collection of many small helper to solve repeating task. 
 At the center there is a utils service allow access to all util function. 
@@ -122,4 +122,15 @@ Returns an anonymized email address. max.muster@example.org will be max.****@exa
 
 ```twig
 {{ user.email|anonymize_email }}
-```
+```
+
+## Notes
+
+### Backwards Compatibility Promise
+
+We try our best to keep this bundle backwards compatible and follow the principle of [semantic versioning](https://semver.org/).
+
+Following aspects are not covered by BC promise:
+- Using Utils classes direct instead from Utils service. This is not officially supported and may break your application due internal changes.
+- Classes marked as `@internal` or `@experimental`
+- 

src/Dom/DOMLettersIterator.php

@@ -1,4 +1,4 @@
-<?php
+<?php /** @noinspection PhpComposerExtensionStubsInspection */
 
 /*
  * Copyright (c) 2021 Heimrich & Hannot GmbH
@@ -11,7 +11,6 @@
 use DOMDocument;
 use DOMElement;
 use DOMNode;
-use InvalidArgumentException;
 use Iterator;
 
 /**
@@ -29,6 +28,8 @@
  *
  * @author porneL http://pornel.net
  * @license Public Domain
+ *
+ * @internal
  */
 final class DOMLettersIterator implements Iterator
 {
@@ -37,26 +38,17 @@ final class DOMLettersIterator implements Iterator
     private $offset;
     private $key;
     private $letters;
-    /**
-     * @var \SplQueue
-     */
-    private $queue;
+    private \SplQueue $queue;
 
     /**
      * expects DOMElement or DOMDocument (see DOMDocument::load and DOMDocument::loadHTML).
-     *
-     * @param DOMDocument|DOMElement $el
      */
-    public function __construct(DOMNode $el)
+    public function __construct(DOMDocument|DOMElement $el)
     {
         if ($el instanceof DOMDocument) {
             $this->start = $el->documentElement;
         } else {
-            if ($el instanceof DOMElement) {
-                $this->start = $el;
-            } else {
-                throw new InvalidArgumentException('Invalid arguments, expected DOMElement or DOMDocument');
-            }
+            $this->start = $el;
         }
         $this->queue = new \SplQueue();
     }
@@ -68,23 +60,21 @@ public function __construct(DOMNode $el)
      *
      * @return DOMElement[]|int[]
      */
-    public function currentTextPosition()
+    public function currentTextPosition(): array
     {
         return [$this->current, $this->offset, $this->queue->bottom()];
     }
 
     /**
      * Returns DOMElement that is currently being iterated or NULL if iterator has finished.
-     *
-     * @return DOMElement
      */
-    public function currentElement()
+    public function currentElement(): ?DOMElement
     {
         return $this->current ? $this->current->parentNode : null;
     }
 
     // Implementation of Iterator interface
-    public function key()
+    public function key(): mixed
     {
         return $this->key;
     }
@@ -141,7 +131,7 @@ public function next(): void
         $this->next();
     }
 
-    public function current()
+    public function current(): mixed
     {
         if ($this->current) {
             return $this->letters[$this->offset];
@@ -150,12 +140,12 @@ public function current()
         return null;
     }
 
-    public function valid()
+    public function valid(): bool
     {
         return (bool) $this->current;
     }
 
-    public function rewind()
+    public function rewind(): void
     {
         $this->offset = -1;
         $this->letters = [];