Added missing CLI dependency (#1784)

* Added missing CLI dependency

- added examples documentation
- added monorepo validation to static analysis composer command
- added more comlumns to FakeRandomOrdersExtractor

* Updated dependencies

Author: norberttech

composer.json

@@ -402,6 +402,7 @@
         ],
         "test:monorepo": "tools/monorepo/vendor/bin/monorepo-builder validate",
         "static:analyze": [
+            "./tools/monorepo/vendor/bin/monorepo-builder validate",
             "@static:analyze:cs-fixer",
             "@static:analyze:phpstan",
             "@static:analyze:rector"

composer.lock

@@ -0,0 +1,253 @@
+# Examples
+
+This document provides comprehensive guidance for working with Flow PHP examples, including how to add new examples,
+update existing ones, and run them effectively.
+
+## Overview
+
+Flow PHP includes a comprehensive collection of executable examples organized by topic, demonstrating all major
+framework features. Each example is self-contained with isolated dependencies and serves as both documentation and
+integration testing.
+
+## Directory Structure
+
+Examples are organized hierarchically under `/examples/topics/` with the following structure:
+
+```
+examples/
+├── run.php              # Main execution script
+├── clean.php            # Cleanup utility
+└── topics/              # Topic-based organization
+    ├── aggregations/    # Data aggregation operations (8 examples)
+    ├── data_frame/      # DataFrame operations (7 examples)
+    ├── data_reading/    # Data input methods (13 examples)
+    ├── data_writing/    # Data output methods (9 examples)
+    ├── filesystem/      # Filesystem operations (4 examples)
+    ├── join/            # Data joining (2 examples)
+    ├── partitioning/    # Data partitioning (4 examples)
+    ├── schema/          # Schema management (4 examples)
+    ├── transformations/ # Data transformations (12 examples)
+    ├── types/           # Type system (2 examples)
+    └── window_functions/ # Window functions (1 example)
+```
+
+### Standard Example Structure
+
+Each example follows this consistent structure:
+
+```
+examples/topics/{topic}/{example}/
+├── code.php                    # Main executable script (required)
+├── composer.json               # Isolated dependencies (required)
+├── composer.lock               # Locked dependencies (generated)
+├── output.txt                  # Expected output (required)
+├── description.md              # Human-readable explanation (optional)
+├── priority.txt                # Numeric priority for ordering (optional)
+├── hidden.txt                  # Hide from website (optional)
+├── input/                      # Sample input data (optional)
+├── output/                     # Generated output files (optional)
+├── vendor/                     # Composer dependencies (generated)
+└── flow_php_example.zip        # Distribution archive (generated)
+```
+
+## Running Examples
+
+### Command Line Interface
+
+Use the main execution script to run examples:
+
+```bash
+# Run all examples
+./examples/run.php
+
+# Run specific topic
+./examples/run.php --topic=data_reading
+
+# Run specific example
+./examples/run.php --topic=data_reading --example=csv
+
+# Update dependencies instead of install
+./examples/run.php --composer-update
+
+# Generate distribution archives
+./examples/run.php --composer-archive
+```
+
+### Available Options
+
+- `--topic (-t)`: Run examples from a specific topic
+- `--example (-e)`: Run a specific example (requires --topic)
+- `--composer-update (-u)`: Update dependencies instead of install
+- `--composer-archive (-a)`: Generate ZIP archives for distribution
+
+### Integration with Build System
+
+Examples are integrated into the build process:
+
+```bash
+# Run examples as part of test suite
+composer test:examples
+
+# Run full test suite including examples
+composer test
+```
+
+Examples run automatically in CI/CD on changes to `examples/**` directory.
+
+## Adding New Examples
+
+### Step-by-Step Process
+
+1. **Choose Topic and Name**
+    - Use existing topics when possible
+    - Create new topics only for distinct feature areas
+    - Use descriptive, lowercase names with underscores
+
+2. **Create Directory Structure**
+   ```bash
+   mkdir -p examples/topics/{topic}/{example}
+   cd examples/topics/{topic}/{example}
+   ```
+
+3. **Create Required Files**
+
+   **`code.php`** - Main executable script:
+   ```php
+   <?php
+   declare(strict_types=1);
+
+   use function Flow\ETL\DSL\{data_frame, /* other functions */};
+   use function Flow\ETL\Adapter\[Adapter]\{/* adapter functions */};
+
+   require __DIR__ . '/vendor/autoload.php';
+
+   data_frame()
+       ->read(/* extractor */)
+       ->transform(/* transformations */)
+       ->write(/* loader */)
+       ->run();
+   ```
+
+   **`composer.json`** - Dependencies:
+   ```json
+   {
+     "name": "flow-php/examples",
+     "description": "Flow PHP - Examples",
+     "license": "MIT",
+     "type": "library",
+     "require": {
+       "flow-php/etl": "1.x-dev",
+       "flow-php/etl-adapter-[specific]": "1.x-dev"
+     },
+     "archive": {
+       "exclude": [".env", "vendor"]
+     }
+   }
+   ```
+
+   **`priority.txt`** - Numeric priority (1-99, lower = higher priority):
+   ```
+   10
+   ```
+
+4. **Add Optional Files**
+
+   **`description.md`** - Human-readable explanation:
+   ```markdown
+   # Example Title
+
+   Brief description of what this example demonstrates.
+
+   ## Key Features
+
+   - Feature 1
+   - Feature 2
+
+   ## Use Cases
+
+   When to use this pattern...
+   ```
+
+   **`input/`** directory - Sample data files if needed
+   **`hidden.txt`** - Empty file to hide from website
+
+5. **Test the Example**
+   ```bash
+   # Test locally
+   ./examples/run.php --topic={topic} --example={example}
+   ```
+
+## Updating Existing Examples
+
+### Common Update Scenarios
+
+1. **Code Changes**
+    - Edit `code.php` following existing patterns
+    - Test thoroughly with `./examples/run.php`
+    - Update `output.txt` if output changes
+
+2. **Dependency Updates**
+    - Modify `composer.json` as needed
+    - Run `./examples/run.php --composer-update --topic={topic} --example={example}` to refresh dependencies
+    - Commit both `composer.json` and `composer.lock`
+
+3. **Documentation Updates**
+    - Edit `description.md` for clarity
+    - Keep documentation concise and focused
+
+4. **Priority Changes**
+    - Modify `priority.txt` value (1-99)
+    - Lower numbers appear first in listings
+
+## Priority and Organization System
+
+### Priority System
+
+Examples use numeric priorities for ordering:
+
+- **Range**: 1-99 (lower numbers = higher priority)
+- **Default**: 99 if `priority.txt` doesn't exist
+- **Application**: Both topics and individual examples
+- **Display**: Lower priority numbers appear first
+
+### Visibility Control
+
+- **`hidden.txt`**: Empty file that hides examples from website
+- **Use cases**: Internal examples, development utilities, deprecated examples
+- **Current usage**: Applied to some sequence generator examples
+
+## Maintenance and Cleanup
+
+### Cleanup Operations
+
+Remove generated files and dependencies:
+
+```bash
+# Clean all examples
+./examples/clean.php
+
+# This removes:
+# - vendor/ directories
+# - flow_php_example.zip files
+```
+
+### Archive Generation
+
+Create distribution packages:
+
+```bash
+# Generate archives for all examples
+./examples/run.php --composer-archive
+
+# Archives are created as flow_php_example.zip in each example directory
+```
+
+## Integration with Website
+
+Examples are automatically integrated into the Flow PHP website:
+
+- **Dynamic content**: Website reads examples directly from filesystem
+- **Priority ordering**: Uses `priority.txt` for display order
+- **Visibility**: Respects `hidden.txt` files
+- **Multi-format**: Supports various output formats (txt, xml, csv, json)
+- **Code highlighting**: Automatic syntax highlighting for code blocks

documentation/examples.md

@@ -49,6 +49,8 @@ It creates a new instance of the `Flow\ETL\Flow` class, which is the main class
 
 [Data Frame Examples](/data_frame/#example)
 
+[Examples Documentation](/documentation/examples)
+
 ## Extraction - Reading
 
 The first step in creating a data processing pipeline is to read the data from a data source.

documentation/quick-start.md

@@ -44,6 +44,7 @@ public function test_sanitizing_request_fields() : void
 
         $record = $processor(['datetime' => new \DateTimeImmutable, 'channel' => 'http', 'level_name' => 'debug', 'message' => 'HTTP Request', 'context' => ['request' => $request]]);
 
+        /** @phpstan-ignore-next-line */
         $requestData = json_decode((string) $record['context']['request']['body'], true);
         \assert(\is_array($requestData));
 
@@ -87,6 +88,7 @@ public function test_sanitizing_response_fields() : void
 
         $record = $processor(['datetime' => new \DateTimeImmutable, 'channel' => 'http', 'level_name' => 'debug', 'message' => 'HTTP Response', 'context' => ['response' => $response]]);
 
+        /** @phpstan-ignore-next-line */
         $responseData = json_decode((string) $record['context']['response']['body'], true);
         \assert(\is_array($responseData));
 

src/bridge/monolog/http/tests/Flow/Bridge/Monolog/Http/Tests/Unit/PSR7ProcessorSanitizationTest.php

@@ -10,6 +10,7 @@
     "require": {
         "php": "~8.2.0 || ~8.3.0 || ~8.4.0",
         "symfony/console": "^5.4 || ^6.4 || ^7.0",
+        "symfony/uid": "^6.3 || ^7.0",
         "flow-php/etl": "self.version",
         "flow-php/etl-adapter-csv": "self.version",
         "flow-php/etl-adapter-parquet": "self.version",

src/cli/composer.json

@@ -104,7 +104,7 @@ public function definition() : Definition
 
     public function duplicate() : self
     {
-        return new self($this->name, $this->value ? $this->value->cloneNode(true) : null, $this->metadata);
+        return new self($this->name, type_optional(type_instance_of(\DOMElement::class))->assert($this->value ? $this->value->cloneNode(true) : null), $this->metadata);
     }
 
     public function is(Reference|string $name) : bool

src/core/etl/src/Flow/ETL/Row/Entry/XMLElementEntry.php

@@ -19,8 +19,10 @@ public static function schema() : Schema
     {
         return schema(
             uuid_schema('order_id'),
+            uuid_schema('seller_id'),
             datetime_schema('created_at'),
             datetime_schema('updated_at', true),
+            datetime_schema('cancelled_at', true),
             float_schema('discount', true),
             string_schema('email'),
             string_schema('customer'),
@@ -56,12 +58,32 @@ public function extract(FlowContext $context) : \Generator
             ['sku' => 'SKU_0005', 'name' => 'Product 5', 'price' => $faker->randomFloat(2, 0, 500)],
         ];
 
+        $sellers = [
+            $faker->uuid,
+            $faker->uuid,
+            $faker->uuid,
+            $faker->uuid,
+            $faker->uuid,
+        ];
+
         for ($i = 0; $i < $this->count; $i++) {
+
+            $createdAt = \DateTimeImmutable::createFromMutable($faker->dateTimeThisYear);
+            $cancelledAt = \random_int(1, 10) === 1 ? $createdAt->modify('+' . $faker->numberBetween(1, 5) . ' hours') : null;
+
+            if ($cancelledAt) {
+                $updatedAt = $cancelledAt;
+            } else {
+                $updatedAt = \random_int(1, 3) === 1 ? $createdAt->modify('+' . $faker->numberBetween(1, 3) . ' days') : null;
+            }
+
             yield array_to_rows(
                 [
                     'order_id' => $faker->uuid,
-                    'created_at' => $faker->dateTimeThisYear,
-                    'updated_at' => \random_int(0, 1) === 1 ? $faker->dateTimeThisMonth : null,
+                    'seller_id' => $sellers[\random_int(0, \count($sellers) - 1)],
+                    'created_at' => $createdAt,
+                    'updated_at' => $updatedAt,
+                    'cancelled_at' => $cancelledAt,
                     'discount' => \random_int(0, 1) === 1 ? $faker->randomFloat(2, 0, 50) : null,
                     'email' => $faker->email,
                     'customer' => $faker->firstName . ' ' . $faker->lastName,