Add documentation and examples for Fast Forward Iterators

- Migrated to PHP 8.3+.
- Introduced a new documentation section for iterators, detailing core iterator classes and their functionalities.
- Created a "Getting Started" guide with installation instructions and a quickstart example.
- Added usage patterns and real-world use cases for various iterators, including chunking, sliding windows, unique filtering, and lookahead/lookbehind.
- Updated examples to reflect new iterator functionalities and improved code clarity.
- Enhanced copyright information in example files to reflect the updated year and added relevant links.
- Added Unit Tests.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

Author: coisa

.docheader

@@ -4,7 +4,10 @@
  * This source file is subject to the license that is bundled
  * with this source code in the file LICENSE.
  *
- * @link      https://github.com/php-fast-forward/iterators
  * @copyright Copyright (c) 2025-%year% Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
  * @license   https://opensource.org/licenses/MIT MIT License
+ *
+ * @see       https://github.com/php-fast-forward/iterators
+ * @see       https://github.com/php-fast-forward
+ * @see       https://datatracker.ietf.org/doc/html/rfc2119
  */

.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+  - package-ecosystem: "composer"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "Composer"
+      include: "scope"
+    labels:
+      - "composer"
+      - "dependencies"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "GitHub Actions"
+      include: "scope"
+    labels:
+      - "github-actions"
+      - "continuous-integration"

.github/workflows/reports.yml

@@ -0,0 +1,17 @@
+name: "Fast Forward Reports"
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  reports:
+    uses: php-fast-forward/dev-tools/.github/workflows/reports.yml@main
+    secrets: inherit

.github/workflows/tests.yml

@@ -0,0 +1,15 @@
+name: "Fast Forward Test Suite"
+
+on:
+  push:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  tests:
+    uses: php-fast-forward/dev-tools/.github/workflows/tests.yml@main
+    secrets: inherit

.github/workflows/wiki.yml

@@ -0,0 +1,17 @@
+name: "Fast Forward Wiki Update"
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  wiki:
+    uses: php-fast-forward/dev-tools/.github/workflows/wiki.yml@main
+    secrets: inherit

.gitignore

@@ -1,5 +1,7 @@
 .idea/
+.vscode/
 public/
+tmp/
 vendor/
 composer.lock
 *.cache

.gitmodules

@@ -0,0 +1,3 @@
+[submodule ".github/wiki"]
+	path = .github/wiki
+	url = git@github.com:php-fast-forward/iterators.wiki.git

.php-cs-fixer.php

@@ -1,10 +1,13 @@
 # FastForward\Iterators
 
-[![PHP Version](https://img.shields.io/badge/php-7.4%20%7C%208.0%2B-blue.svg)](https://www.php.net/)
+[![PHP Version](https://img.shields.io/badge/php-8.3%2B-blue.svg)](https://www.php.net/)
 [![License](https://img.shields.io/github/license/php-fast-forward/iterators)](https://opensource.org/licenses/MIT)
 
-A robust and optimized library for advanced PHP Iterators.  
-Enhance your PHP applications with high-performance iterators, supporting lookahead, peeking, filtering, grouping, and more.
+A robust and optimized library for advanced PHP Iterators.
+
+Enhance your PHP applications with high-performance iterators: lookahead, peeking, filtering, grouping, chunking, and more.
+
+---
 
 ## ✨ Features
 
@@ -19,14 +22,77 @@ Enhance your PHP applications with high-performance iterators, supporting lookah
 Install via Composer:
 
 ```bash
-composer require fast-forward/iterators
+composer require php-fast-forward/iterators
 ```
 
-## 🛠 Usage
+**Requirements:** PHP 8.3 or higher
+
+## 🚀 Quickstart
+
+```php
+use FastForward\Iterator\ChunkedIteratorAggregate;
+
+$data = range(1, 10);
+$chunked = new ChunkedIteratorAggregate($data, 3);
+foreach ($chunked as $chunk) {
+	print_r($chunk);
+}
+```
+
+**Expected output:**
+
+```
+Array
+(
+	[0] => 1
+	[1] => 2
+	[2] => 3
+)
+Array
+(
+	[0] => 4
+	[1] => 5
+	[2] => 6
+)
+Array
+(
+	[0] => 7
+	[1] => 8
+	[2] => 9
+)
+Array
+(
+	[0] => 10
+)
+```
+
+## 🛠 Usage Patterns
+
+All iterators and utilities are available under the `FastForward\Iterator` namespace. Simply require Composer's autoloader:
+
+```php
+require_once 'vendor/autoload.php';
+use FastForward\Iterator\ChunkedIteratorAggregate;
+use FastForward\Iterator\SlidingWindowIteratorIterator;
+// ...
+```
+
+You can chain, compose, and adapt iterators for a wide variety of data processing tasks.
+
+## 📚 Documentation & Examples
+
+- 📖 [Full Documentation](https://github.com/php-fast-forward/iterators/tree/main/docs)
+- 🧑‍💻 [Examples Directory](https://github.com/php-fast-forward/iterators/tree/main/examples)
+  - Each file demonstrates a specific iterator or pattern:
+	- [chunked-iterator-aggregate.php](https://github.com/php-fast-forward/iterators/blob/main/examples/chunked-iterator-aggregate.php)
+	- [sliding-window-iterator-iterator.php](https://github.com/php-fast-forward/iterators/blob/main/examples/sliding-window-iterator-iterator.php)
+	- [unique-iterator-iterator.php](https://github.com/php-fast-forward/iterators/blob/main/examples/unique-iterator-iterator.php)
+	- [lookahead-iterator.php](https://github.com/php-fast-forward/iterators/blob/main/examples/lookahead-iterator.php)
+	- ...and more!
 
-This package provides various iterator utilities under the `FastForward\Iterator` namespace.
+## 🤝 Contributing
 
-Check out the [`examples/`](https://github.com/php-fast-forward/iterators/tree/main/examples) directory for hands-on usage of each iterator.
+Contributions, bug reports and suggestions are welcome! Please open an issue or pull request on [GitHub](https://github.com/php-fast-forward/iterators).
 
 ## 🧑‍💻 Author
 

README.md

@@ -23,13 +23,10 @@
         "source": "https://github.com/php-fast-forward/iterators"
     },
     "require": {
-        "php": "^8.1"
+        "php": "^8.3"
     },
     "require-dev": {
-        "coisa/php-cs-fixer": "^2.1",
-        "infection/infection": "^0.29",
-        "phpstan/phpstan": "^2.1",
-        "phpunit/phpunit": "^9.6 || ^10.5 || ^11.5"
+        "fast-forward/dev-tools": "dev-main"
     },
     "minimum-stability": "stable",
     "autoload": {
@@ -42,25 +39,26 @@
     },
     "config": {
         "allow-plugins": {
-            "infection/extension-installer": true
+            "ergebnis/composer-normalize": true,
+            "fast-forward/dev-tools": true,
+            "phpdocumentor/shim": true,
+            "phpro/grumphp": true
+        },
+        "platform": {
+            "php": "8.3.0"
         },
         "sort-packages": true
     },
     "extra": {
         "branch-alias": {
             "dev-main": "1.x-dev"
+        },
+        "grumphp": {
+            "config-default-path": "vendor/fast-forward/dev-tools/grumphp.yml"
         }
     },
     "scripts": {
-        "cs-check": "php-cs-fixer fix --dry-run --diff",
-        "cs-fix": "php-cs-fixer fix",
-        "mutation-testing": "infection --threads=4",
-        "pre-commit": [
-            "@cs-check",
-            "@static-analysis",
-            "@tests"
-        ],
-        "static-analysis": "phpstan analyse --level 5 src",
-        "tests": "phpunit --testdox"
+        "dev-tools": "dev-tools",
+        "dev-tools:fix": "@dev-tools --fix"
     }
 }