### Initial Project Setup

Source: https://github.com/flow-php/flow/blob/1.x/documentation/contributing/environment.md

Copy the distribution compose file, install dependencies, and start Docker services.

```shell
cp compose.yml.dist compose.yml
just install
docker compose up -d
```

--------------------------------

### Install Dependencies and Start Server

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/README.md

Installs project dependencies using Composer and starts the Symfony development server. Ensure Symfony CLI is installed.

```shell
composer install
symfony server:ca:install
symfony server:start -d
```

--------------------------------

### Creating Examples with Options

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/docs/examples.md

Provides a step-by-step guide on how to convert a standalone example into a 3-level structure with multiple options.

```APIDOC
## Creating Examples with Options

To convert a standalone example to one with options:

1. Create option subdirectories inside the example folder
2. Move `code.php`, `composer.json`, etc. into first option subdirectory
3. Remove `code.php` from example folder (critical!)
4. Add `priority.txt` to each option (optional, default: 99)
5. Create additional options as needed
6. Test navigation locally

Example conversion:
```bash
# Before: examples/topics/transformations/when/code.php
# After:  examples/topics/transformations/when/basic/code.php
#         examples/topics/transformations/when/with_else_when/code.php
```
```

--------------------------------

### Complete Flow Filesystem Configuration Example

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/bridges/symfony-filesystem-bundle.md

A comprehensive example demonstrating a single fstab setup with local, memory, and S3 filesystems, including telemetry enabled.

```yaml
# config/packages/flow_filesystem.yaml
flow_filesystem:
  fstabs:
    default:
      telemetry:
        enabled: true
        telemetry_service_id: app.flow_telemetry
        clock_service_id: app.system_clock
        options:
          trace_streams: true
          collect_metrics: true
      filesystems:
        file:
          type: file
        memory:
          type: memory
        aws-s3:
          type: aws_s3
          bucket: '%env(S3_BUCKET)%'
          client:
            region: '%env(AWS_REGION)%'
            access_key_id: '%env(AWS_ACCESS_KEY_ID)%'
            access_key_secret: '%env(AWS_SECRET_ACCESS_KEY)%'
          options:
            block_size: 6291456
```

--------------------------------

### Examples Service: Get Examples for Topic

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/docs/examples.md

Retrieves all visible examples for a specific topic, sorted by priority. It scans the topic directory, excluding specific files, reads priority files, sorts, and filters hidden examples.

```php
examples(string $topic): array<string>
```

--------------------------------

### Examples Service: Get Output

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/docs/examples.md

Retrieves the output of an example, looking for files like 'output.txt', 'output.xml', etc. It concatenates content if multiple files are found or returns single file content, mapping '.txt' to 'shell' type for highlighting.

```php
output(string $topic, string $example): ?Output
```

--------------------------------

### Examples Service: Get Topics

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/docs/examples.md

Retrieves all visible topics, sorted by priority. It scans the 'examples/topics/' directory, reads priority files, sorts, and filters hidden topics.

```php
topics(): array<string>
```

--------------------------------

### Examples Service Constructor

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/docs/examples.md

Initializes the Examples service with the absolute path to the examples directory.

```php
public function __construct(private readonly string $examplesPath)
```

--------------------------------

### Examples Service: Get Code

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/docs/examples.md

Returns the PHP code content for a given example, located at 'examples/topics/{$topic}/{$example}/code.php'.

```php
code(string $topic, string $example): string
```

--------------------------------

### Examples Service: Get Description

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/docs/examples.md

Returns the markdown description for an example, if the 'description.md' file exists in the example's directory.

```php
description(string $topic, string $example): ?string
```

--------------------------------

### Create .dev.vars file

Source: https://github.com/flow-php/flow/blob/1.x/terraform/cloudflare/workers/README.md

Use this command to copy the example .dev.vars file, which is essential for local development setup.

```bash
cd terraform/cloudflare/workers
cp .dev.vars.example .dev.vars
```

--------------------------------

### Setup with Honeycomb

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/bridges/telemetry-otlp-bridge.md

Configure telemetry to send data to Honeycomb using OTLP/HTTP transport with cURL. This example uses Protocol Buffers serialization and includes the Honeycomb API key in the headers.

```php
<?php

use function Flow\Telemetry\DSL\{
    telemetry,
    resource,
    tracer_provider,
    batching_span_processor,
};
use function Flow\Bridge\Telemetry\OTLP\DSL\{
    otlp_curl_transport,
    otlp_curl_options,
    otlp_protobuf_serializer,
    otlp_exporter,
};

$transport = otlp_curl_transport(
    endpoint: 'https://api.honeycomb.io',
    serializer: otlp_protobuf_serializer(),
    options: otlp_curl_options()
        ->withHeader('x-honeycomb-team', 'your-api-key'),
);

$telemetry = telemetry(
    resource(['service.name' => 'my-app']),
    tracer_provider(batching_span_processor(otlp_exporter($transport))),
);

```

--------------------------------

### Complete Sequence Creation Example

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/libs/postgresql/sequence-query-builder.md

Demonstrates a comprehensive CREATE SEQUENCE statement combining multiple options like data type, start value, increment, min/max values, cache, and cycle behavior.

```php
<?php

use function Flow\PostgreSql\DSL\create;

$query = create()->sequence('user_id_seq')
    ->asType('bigint')
    ->startWith(1)
    ->incrementBy(1)
    ->minValue(1)
    ->maxValue(1000000)
    ->cache(1)
    ->noCycle();

echo $query->toSql();
// CREATE SEQUENCE user_id_seq AS bigint START 1 INCREMENT 1 MINVALUE 1 MAXVALUE 1000000 CACHE 1 NO CYCLE
```

--------------------------------

### Examples Service: Get Composer JSON

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/docs/examples.md

Retrieves and formats the composer.json content for an example. It reads the file, decodes JSON, removes the 'archive' key if present, and re-encodes it with pretty-printing.

```php
composer(string $topic, string $example): string
```

--------------------------------

### Start Local Webserver with Symfony CLI

Source: https://github.com/flow-php/flow/blob/1.x/documentation/contributing/nix.md

Navigate to the web/landing directory and use the Symfony CLI to start the local webserver and its proxy.

```shell
cd web/landing
symfony proxy:start
symfony server:start -d
```

--------------------------------

### Directory Layout for 3-Level Examples

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/docs/examples.md

Illustrates the hierarchical structure for organizing examples with multiple options.

```APIDOC
## Directory Layout

```
examples/
  topics/
    transformations/           # Topic (Level 1)
      when/                    # Example (Level 2)
        priority.txt           # Optional: Example priority (controls order in topic)
        basic/                 # Option (Level 3)
          code.php             # Required: main code
          composer.json        # Required: dependencies
          composer.lock        # Generated
          description.md       # Optional: option description
          output.txt           # Optional: option output
          priority.txt         # Optional: controls option order
          hidden.txt           # Optional: hides option from navigation
          vendor/              # Generated by composer
        with_else_when/        # Option (Level 3)
          code.php
          composer.json
          description.md
          output.txt
          priority.txt
```
```

--------------------------------

### Install PG Query Extension with PIE

Source: https://github.com/flow-php/flow/blob/1.x/documentation/installation/packages/pg-query-ext.md

Use the PIE installer to install the flow-php/pg-query-ext PHP extension. Ensure you have PIE installed.

```bash
pie install flow-php/pg-query-ext
```

--------------------------------

### Standalone Usage Example

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/bridges/symfony-postgresql-cache-bridge.md

Demonstrates how to create and use the FlowPostgreSqlCacheAdapter for standalone cache operations. It includes setting up the necessary PostgreSQL table and performing basic cache set and get operations.

```php
use Flow\Bridge\Symfony\PostgreSQLCache\{CacheCatalogProvider, FlowPostgreSqlCacheAdapter};
use function Flow\PostgreSql\DSL\{pgsql_client, pgsql_connection_dsn};

$params = pgsql_connection_dsn(getenv('DATABASE_URL'));

// Create the table once (or manage it via your migration tool of choice).
// The setup client below is unrelated to the connection the adapter owns.
$setup = pgsql_client($params);
foreach ((new CacheCatalogProvider())->get()->get('public')->table('cache_items')->toSql() as $sql) {
    $setup->execute($sql);
}
$setup->close();

$cache = new FlowPostgreSqlCacheAdapter($params, namespace: 'app', defaultLifetime: 3600);

$item = $cache->getItem('greeting');

if (!$item->isHit()) {
    $item->set('hello world');
    $item->expiresAfter(600);
    $cache->save($item);
}

echo $cache->getItem('greeting')->get();

```

--------------------------------

### Install ext-protobuf for Performance

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/libs/postgresql.md

For optimal performance, install the `ext-protobuf` PHP extension using PECL. While the library functions without it using a pure PHP implementation, the native extension offers significant speed improvements.

```bash
pecl install protobuf

```

--------------------------------

### Standalone Usage Example

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/bridges/symfony-filesystem-cache-bridge.md

Demonstrates how to instantiate and use the FlowFilesystemCacheAdapter for standalone cache operations. This example uses a native local filesystem.

```php
use Flow\Bridge\Symfony\FilesystemCache\FlowFilesystemCacheAdapter;
use Flow\Filesystem\Local\NativeLocalFilesystem;
use Flow\Filesystem\Path;

$cache = new FlowFilesystemCacheAdapter(
    filesystem: new NativeLocalFilesystem(),
    directory: Path::from('/var/cache/app'),
    namespace: 'app',
    defaultLifetime: 3600,
);

$item = $cache->getItem('greeting');

if (!$item->isHit()) {
    $item->set('hello world');
    $item->expiresAfter(600);
    $cache->save($item);
}

echo $cache->getItem('greeting')->get();
```

--------------------------------

### New 'options()' Service Method

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/docs/examples.md

This new method returns all visible options for an example, sorted by priority. It handles cases where an example might not have options.

```php
options(string $topic, string $example): array<string>
```

--------------------------------

### Install Arrow Extension using Precompiled Binaries

Source: https://github.com/flow-php/flow/blob/1.x/documentation/installation/packages/arrow-ext.md

Steps to install the Arrow extension by downloading a precompiled binary, copying it to the PHP extensions directory, and enabling it via an .ini file.

```bash
# Unzip the archive
unzip php_arrow-*.zip

# Copy to your PHP extensions directory
cp arrow.so $(php -r "echo ini_get('extension_dir');")

# Enable it
echo "extension=arrow" > $(php -r "echo PHP_CONFIG_FILE_SCAN_DIR;")/arrow.ini

# Verify
php -m | grep arrow
```

--------------------------------

### Install Arrow Extension using PIE

Source: https://github.com/flow-php/flow/blob/1.x/documentation/installation/packages/arrow-ext.md

A simple command to install the Arrow extension using the PIE package manager.

```bash
pie install flow-php/arrow-ext
```

--------------------------------

### Install Flow PHP and Adapters

Source: https://github.com/flow-php/flow/blob/1.x/documentation/introduction.md

Install the core Flow PHP package along with the CSV and JSON adapters using Composer.

```bash
composer require flow-php/etl flow-php/etl-adapter-csv flow-php/etl-adapter-json
```

--------------------------------

### Flow CLI Configuration Example

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/cli/docs.md

Example of a .flow.php configuration file to set an execution ID for Flow CLI commands.

```php
<?php

use function Flow\ETL\DSL\config_builder;

return config_builder()
    ->id('execution-id');
```

--------------------------------

### Benchmark Output Example

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/libs/snappy.md

Example console output from the Snappy performance benchmark script, showing the time taken for both the Flow PHP implementation and the PHP extension.

```console
$ php benchmark_snappy.php
Starting Benchmark

Snappy Flow time: 6.6838178634644
Snappy PHP Extension time: 0.31190991401672

```

--------------------------------

### Complete Materialized View Creation Example

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/libs/postgresql/view-query-builder.md

A comprehensive example demonstrating the creation of a materialized view with various options including schema, columns, storage type, tablespace, and data population control.

```php
<?php

use function Flow\PostgreSql\DSL\{create, select};

$query = create()->materializedView('analytics.user_stats')
    ->ifNotExists()
    ->columns('user_id', 'order_count', 'total_spent')
    ->using('heap')
    ->as(select('id', 'count(*)', 'sum(total)')->from('users'))
    ->tablespace('analytics_ts')
    ->withNoData();

echo $query->toSql();
// CREATE MATERIALIZED VIEW IF NOT EXISTS analytics.user_stats (user_id, order_count, total_spent)
//   USING heap TABLESPACE analytics_ts AS SELECT id, count(*), sum(total) FROM users WITH NO DATA
```

--------------------------------

### Example Conversion Bash Script

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/docs/examples.md

This bash command illustrates the process of converting a standalone example to a 3-level structure by moving code files into option subdirectories.

```bash
# Before: examples/topics/transformations/when/code.php
# After:  examples/topics/transformations/when/basic/code.php
#         examples/topics/transformations/when/with_else_when/code.php
```

--------------------------------

### Download Button in Twig

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/docs/examples.md

Provides a direct download link for the pre-built example ZIP file. The URL is constructed using the current topic and example.

```twig
<a href="https://raw.githubusercontent.com/flow-php/flow/refs/heads/1.x/examples/topics/{{ currentTopic }}/{{ currentExample }}/flow_php_example.zip">
    Download
</a>
```

--------------------------------

### Install Protobuf Serializer Dependency

Source: https://github.com/flow-php/flow/blob/1.x/documentation/installation/packages/telemetry-otlp-bridge.md

Install the google/protobuf package if you plan to use Protobuf serialization with transports like Curl+Protobuf or gRPC.

```bash
# For Protobuf serializer (used by Curl+Protobuf or gRPC transports)
composer require google/protobuf
```

--------------------------------

### Sequence Creation with START WITH

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/libs/postgresql/sequence-query-builder.md

Specifies the initial value for the sequence.

```php
<?php

use function Flow\PostgreSql\DSL\create;

$query = create()->sequence('user_id_seq')
    ->startWith(100);

echo $query->toSql();
// CREATE SEQUENCE user_id_seq START 100
```

--------------------------------

### Install HTTP Client Implementation

Source: https://github.com/flow-php/flow/blob/1.x/documentation/installation/packages/azure-sdk.md

Install a PSR-18 compatible HTTP client implementation along with PSR-7 support. This is required by the Azure SDK library.

```bash
composer require symfony/http-client nyholm/psr7
```

--------------------------------

### Install Filesystem Package

Source: https://github.com/flow-php/flow/blob/1.x/documentation/installation/packages/filesystem.md

Install the flow-php/filesystem package using Composer. Ensure you replace `--FLOW_PHP_VERSION--` with your project's compatible Flow PHP version.

```bash
composer require flow-php/filesystem:~--FLOW_PHP_VERSION--
```

--------------------------------

### Setup Development Environment

Source: https://github.com/flow-php/flow/blob/1.x/documentation/contributing/rust.md

Enter the Nix shell with the Rust toolchain, clang, libclang, and PHP dev headers. This is required before building the extension.

```bash
nix-shell --arg with-arrow-ext false --arg with-rust true
```

--------------------------------

### Batching Span Processor Example

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/libs/telemetry.md

Demonstrates how to configure and use a batching span processor. This processor buffers spans until a specified batch size is reached before exporting them, optimizing performance for production environments. It shows the creation of the processor and an example of flushing the buffer.

```php
<?php

use function Flow\Telemetry\DSL\batching_span_processor;
use function Flow\Telemetry\DSL\console_exporter;

$processor = batching_span_processor(
    console_exporter(),
    batchSize: 512
);

// Spans are buffered until 512 are collected, then exported together
// Call flush() to export immediately regardless of batch size
$processor->flush();

```

--------------------------------

### Complete PostgreSQL Function Creation Example

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/libs/postgresql/function-procedure-query-builder.md

A comprehensive example of creating a PostgreSQL function with options like OR REPLACE, arguments with defaults, return type, language, immutability, parallel safety, strictness, and the function body.

```php
<?php

use function Flow\PostgreSql\DSL\{create, func_arg, column_type_numeric};
use Flow\PostgreSql\QueryBuilder\Schema\Function\ParallelSafety;

$query = create()->function('calculate_discount')
    ->orReplace()
    ->arguments(
        func_arg(column_type_numeric())->named('price'),
        func_arg(column_type_numeric())->named('discount_percent')->default('10')
    )
    ->returns('numeric')
    ->language('sql')
    ->immutable()
    ->parallel(ParallelSafety::SAFE)
    ->strict()
    ->as('SELECT price - (price * discount_percent / 100)');

```

--------------------------------

### Logging Basic Example

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/libs/telemetry.md

Demonstrates how to create a logger instance and emit logs with structured data at different severity levels.

```php
<?php

$logger = $telemetry->logger('my-service', '1.0.0');

$logger->info('Order processed successfully', [
    'order_id' => '12345',
    'customer_id' => 'cust-789',
    'total' => 99.99,
]);

$logger->error('Payment failed', [
    'order_id' => '12345',
    'error_code' => 'CARD_DECLINED',
]);

$logger->debug('Cache hit', ['key' => 'user:123', 'ttl' => 3600]);

```

--------------------------------

### Symfony PostgreSQL Bundle Configuration

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/bridges/symfony-postgresql-bundle.md

Example configuration for the Symfony PostgreSQL Bundle, including database connection details, telemetry settings, messenger integration, cache pools, and migration setup.

```yaml
flow_postgresql:
  connections:
    default:
      dsn: '%env(DATABASE_URL)%'

      telemetry:
        service_id: "flow.telemetry"
        trace_queries: true
        trace_transactions: true
        collect_metrics: true
        log_queries: false
        max_query_length: 1000

  messenger:
    enabled: true

  cache:
    pools:
      app:
        table_name: cache_app
        default_lifetime: 3600

  migrations:
    enabled: true
    directory: "%kernel.project_dir%/migrations"
    namespace: "App\\Migrations"
    table_name: "flow_migrations"
    table_schema: "public"
    all_or_nothing: false
    generate_rollback: true

  catalog_providers:
    - catalog:
        schemas:
          - name: "public"
            tables:
              - name: "users"
                columns:
                  - name: "id"
                    type: { name: "int4", schema: "pg_catalog" }
                    nullable: false
                  - name: "email"
                    type: { name: "varchar", schema: "pg_catalog" }
                    nullable: false
                  - name: "created_at"
                    type: { name: "timestamptz", schema: "pg_catalog" }
                    nullable: false

```

--------------------------------

### Build Documentation

Source: https://github.com/flow-php/flow/blob/1.x/documentation/contributing/environment.md

Generate API and DSL documentation. `just docs` should be run after modifying `functions.php` files.

```shell
just docs
just docs-api
```

--------------------------------

### Setup with Grafana Cloud

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/bridges/telemetry-otlp-bridge.md

Configure telemetry to send data to Grafana Cloud using OTLP/HTTP transport with cURL. This example uses Protocol Buffers serialization and includes authorization headers.

```php
<?php

use function Flow\Telemetry\DSL\{
    telemetry,
    resource,
    tracer_provider,
    batching_span_processor,
};
use function Flow\Bridge\Telemetry\OTLP\DSL\{
    otlp_curl_transport,
    otlp_curl_options,
    otlp_protobuf_serializer,
    otlp_exporter,
};

$transport = otlp_curl_transport(
    endpoint: 'https://otlp-gateway-prod-eu-west-0.grafana.net/otlp',
    serializer: otlp_protobuf_serializer(),
    options: otlp_curl_options()
        ->withHeader('Authorization', 'Basic ' . base64_encode('instance-id:api-key')),
);

$telemetry = telemetry(
    resource(['service.name' => 'my-app']),
    tracer_provider(batching_span_processor(otlp_exporter($transport))),
);

```

--------------------------------

### Start Nix Development Shell

Source: https://github.com/flow-php/flow/blob/1.x/documentation/contributing/nix.md

Enter the Nix development shell for the project. This command downloads all necessary dependencies. For full isolation, use the --pure flag.

```bash
nix-shell
```

```bash
nix-shell --pure
```

--------------------------------

### Basic Telemetry Setup with Memory Providers

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/libs/telemetry.md

Initialize Telemetry with memory providers for testing purposes. This allows inspection of collected spans, metrics, and logs after operations.

```php
<?php

use function Flow\Telemetry\DSL\{
    telemetry,
    resource,
    tracer_provider,
    meter_provider,
    logger_provider,
    memory_span_processor,
    memory_metric_processor,
    memory_log_processor,
};

$resource = resource([
    'service.name' => 'test-service',
    'service.version' => '1.0.0',
]);

$spanProcessor = memory_span_processor();
$metricProcessor = memory_metric_processor();
$logProcessor = memory_log_processor();

$telemetry = telemetry(
    $resource,
    tracer_provider($spanProcessor),
    meter_provider($metricProcessor),
    logger_provider($logProcessor),
);

// Get instrumented components
$tracer = $telemetry->tracer('my-component');
$meter = $telemetry->meter('my-component');
$logger = $telemetry->logger('my-component');

// Use telemetry...
$span = $tracer->span('operation');
$tracer->complete($span);

$meter->createCounter('events', 'count')->add(1);

$logger->info('Something happened');

// Inspect collected data
$spans = $spanProcessor->endedSpans();
$metrics = $metricProcessor->collectedMetrics();
$logs = $logProcessor->collectedLogs();

```

--------------------------------

### Load Rows into PSR Logger

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/adapters/logger.md

Use the PsrLoggerLoader to load rows into a PSR Logger interface. Ensure the 'fig/log-test' package is installed. This example demonstrates logging a single row with specific error level and message.

```php
<?php

$logger = new TestLogger();

$loader = new PsrLoggerLoader($logger, 'row log', LogLevel::ERROR);

$loader->load(new Rows(
    Row::create(
        new Row\Entry\IntegerEntry('id', 12345),
        Row\Entry\StringEntry::lowercase('name', 'Norbert')
    )
));

$this->assertTrue($logger->hasErrorRecords());
$this->assertTrue($logger->hasError('row log'));

```

--------------------------------

### Initialize Azure Blob Service SDK (Basic)

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/libs/azure-sdk.md

This snippet shows the minimum configuration required to start using the Azure Blob Service SDK by providing the account name, container name, and account key for authorization.

```php
<?php

use function Flow\Azure\SDK\DSL\azure_blob_service;
use function Flow\Azure\SDK\DSL\azure_blob_service_config;
use function Flow\Azure\SDK\DSL\azure_shared_key_authorization_factory;

$sdk = azure_blob_service(
    azure_blob_service_config($account, $container),
    azure_shared_key_authorization_factory($account, $accountKey),
);
```

--------------------------------

### Example Navigation in Twig

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/docs/examples.md

Renders a horizontal navigation bar for all examples within the current topic. Links to specific examples. The active example is highlighted.

```twig
<nav>
    <ul class="flex whitespace-nowrap overflow-auto py-4">
        {% for example in examples %}
            <li>
                <a href="{{ path('example', {topic: currentTopic, example: example}) }}#example">
                    {{ example|humanize }}
                </a>
            </li>
        {% endfor %}
    </ul>
</nav>
```

--------------------------------

### Default EXPLAIN Configuration

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/libs/postgresql/client-explain.md

Execute a query and collect actual timings, buffer usage, and other details using the default EXPLAIN configuration (ANALYZE, BUFFERS, TIMING, JSON format).

```php
<?php

// Default: ANALYZE with BUFFERS, TIMING, and FORMAT JSON
$plan = $client->explain($query);

```

--------------------------------

### Examples Service API

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/docs/examples.md

API endpoints provided by the Examples Service for retrieving and organizing code examples.

```APIDOC
## GET /api/examples/topics

### Description
Retrieves a list of all visible topics, sorted by priority.

### Method
GET

### Endpoint
/api/examples/topics

### Response
#### Success Response (200)
- **topics** (array<string>) - An array of topic names.

#### Response Example
```json
{
  "topics": [
    "data_reading",
    "data_writing",
    "transformations"
  ]
}
```
```

```APIDOC
## GET /api/examples/{topic}

### Description
Retrieves a list of all visible examples for a given topic, sorted by priority.

### Method
GET

### Endpoint
/api/examples/{topic}

### Parameters
#### Path Parameters
- **topic** (string) - Required - The name of the topic to retrieve examples for.

### Response
#### Success Response (200)
- **examples** (array<string>) - An array of example names for the specified topic.

#### Response Example
```json
{
  "examples": [
    "csv",
    "json",
    "parquet"
  ]
}
```
```

```APIDOC
## GET /api/examples/{topic}/{example}/code

### Description
Retrieves the PHP code for a specific example.

### Method
GET

### Endpoint
/api/examples/{topic}/{example}/code

### Parameters
#### Path Parameters
- **topic** (string) - Required - The name of the topic.
- **example** (string) - Required - The name of the example.

### Response
#### Success Response (200)
- **code** (string) - The PHP code content of the example.

#### Response Example
```php
<?php

// Example code content...
```
```

```APIDOC
## GET /api/examples/{topic}/{example}/composer

### Description
Retrieves the composer.json content for a specific example as a formatted JSON string.

### Method
GET

### Endpoint
/api/examples/{topic}/{example}/composer

### Parameters
#### Path Parameters
- **topic** (string) - Required - The name of the topic.
- **example** (string) - Required - The name of the example.

### Response
#### Success Response (200)
- **composer_json** (string) - The formatted JSON content of composer.json.

#### Response Example
```json
{
    "require": {
        "php": ">=8.1",
        "flow-php/flow": "*"
    }
}
```
```

```APIDOC
## GET /api/examples/{topic}/{example}/description

### Description
Retrieves the markdown description for a specific example.

### Method
GET

### Endpoint
/api/examples/{topic}/{example}/description

### Parameters
#### Path Parameters
- **topic** (string) - Required - The name of the topic.
- **example** (string) - Required - The name of the example.

### Response
#### Success Response (200)
- **description** (string|null) - The markdown description content, or null if not found.

#### Response Example
```markdown
This example demonstrates how to read CSV data.
```
```

```APIDOC
## GET /api/examples/{topic}/{example}/output

### Description
Retrieves the output of running a specific example.

### Method
GET

### Endpoint
/api/examples/{topic}/{example}/output

### Parameters
#### Path Parameters
- **topic** (string) - Required - The name of the topic.
- **example** (string) - Required - The name of the example.

### Response
#### Success Response (200)
- **output** (object) - An object containing the output content and its type.
  - **content** (string) - The output content.
  - **type** (string) - The type of the output (e.g., 'shell', 'json', 'xml', 'csv').

#### Response Example
```json
{
  "content": "Processing complete.",
  "type": "shell"
}
```
```

--------------------------------

### Install HTTP Adapter Package

Source: https://github.com/flow-php/flow/blob/1.x/documentation/installation/packages/etl-adapter-http.md

Install the flow-php/etl-adapter-http package using Composer. Ensure you use the correct version for your Flow PHP installation.

```bash
composer require flow-php/etl-adapter-http:~--FLOW_PHP_VERSION--
```

--------------------------------

### Complete CREATE EXTENSION Example

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/libs/postgresql/extension-query-builder.md

Demonstrates a comprehensive CREATE EXTENSION statement combining multiple options: IF NOT EXISTS, schema, version, and CASCADE.

```php
<?php

use function Flow\PostgreSql\DSL\create;

$query = create()->extension('postgis')
    ->ifNotExists()
    ->schema('extensions')
    ->version('3.0')
    ->cascade();

echo $query->toSql();
// CREATE EXTENSION IF NOT EXISTS postgis SCHEMA extensions VERSION "3.0" CASCADE
```

--------------------------------

### Install Symfony Filesystem Cache Bridge

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/bridges/symfony-filesystem-cache-bridge.md

Install the bridge using Composer. Ensure you use the correct version for your Flow PHP installation.

```bash
composer require flow-php/symfony-filesystem-cache-bridge:~--FLOW_PHP_VERSION--
```

--------------------------------

### Complete Monolog OTLP Export Example

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/bridges/monolog-telemetry-bridge.md

Demonstrates setting up Telemetry with OTLP export and integrating it with a Monolog logger. Logs are sent to an OTLP collector and optionally to a file.

```php
<?php

use Monolog\Logger as MonologLogger;
use Monolog\Handler\StreamHandler;
use Monolog\Level;
use function Flow\Telemetry\DSL\{
    telemetry,
    resource,
    logger_provider,
    batching_log_processor,
};
use function Flow\Bridge\Telemetry\OTLP\DSL\{
    otlp_curl_transport,
    otlp_json_serializer,
    otlp_exporter,
};
use function Flow\Bridge\Monolog\Telemetry\DSL\telemetry_handler;

// Set up Telemetry with OTLP export
$resource = resource([
    'service.name' => 'order-service',
    'service.version' => '1.0.0',
    'deployment.environment' => 'production',
]);

$transport = otlp_curl_transport(
    endpoint: 'http://otel-collector:4318',
    serializer: otlp_json_serializer(),
);

$telemetry = telemetry(
    $resource,
    loggerProvider: logger_provider(
        batching_log_processor(otlp_exporter($transport))
    ),
);

$telemetry->registerShutdownFunction();

// Create Monolog logger with Telemetry handler
$logger = $telemetry->logger('order-service');
$monolog = new MonologLogger('orders');
$monolog->pushHandler(telemetry_handler($logger));

// Optionally, also log to a file
$monolog->pushHandler(new StreamHandler('/var/log/app.log', Level::Debug));

// Use Monolog as usual
$monolog->info('Order created', ['order_id' => 12345, 'amount' => 99.99]);
$monolog->warning('Inventory low', ['product_id' => 789, 'remaining' => 5]);

try {
    // ... payment processing
} catch (\Exception $e) {
    $monolog->error('Payment failed', [
        'order_id' => 12345,
        'exception' => $e,
    ]);
}

```

--------------------------------

### Install Symfony PostgreSQL Session Bridge

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/bridges/symfony-postgresql-session-bridge.md

Install the bridge using Composer. Ensure you use the correct version for your Flow PHP installation.

```bash
composer require flow-php/symfony-postgresql-session-bridge:~--FLOW_PHP_VERSION--
```

--------------------------------

### XML Data Example

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/adapters/xml.md

This is an example of an XML file structure that can be processed by the XMLExtractor.

```xml
<root>
    <items>
        <item><id>1</id></item>
        <item><id>2</id></item>
        <item><id>3</id></item>
        <item><id>4</id></item>
        <item><id>5</id></item>
        <item><id>6</id></item>
    </items>
</root>
```

--------------------------------

### Example Pipeline Definition

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/cli/docs.md

Provides an example of a `pipeline.php` file that defines a data processing pipeline using Flow-PHP's DataFrame API. This example demonstrates reading data from an array and collecting it.

```php
<?php
return df()
    ->read(from_array([
        ['id' => 1, 'name' => 'User 01', 'active' => true],
        ['id' => 2, 'name' => 'User 02', 'active' => false],
        ['id' => 3, 'name' => 'User 03', 'active' => true],
    ]))
    ->collect()
    ->write(to_output());
```

--------------------------------

### Install PHPUnit Bridge

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/bridges/symfony-postgresql-bundle.md

Command to install the PHPUnit PostgreSQL bridge for testing purposes.

```bash
composer require --dev flow-php/phpunit-postgresql-bridge:~--FLOW_PHP_VERSION--
```

--------------------------------

### Install AWS S3 Bridge

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/bridges/symfony-filesystem-bundle.md

Install the necessary bridge package to enable AWS S3 filesystem integration.

```bash
composer require flow-php/filesystem-async-aws-bridge
```

--------------------------------

### New 'example_option' Controller Route

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/docs/examples.md

This route handles the display of a specific option within a 3-level example structure. It passes relevant data to the template.

```php
#[Route('/{topic}/{example}/{option}/', name: 'example_option', priority: -150)]
```

--------------------------------

### Initialize Terraform

Source: https://github.com/flow-php/flow/blob/1.x/terraform/cloudflare/README.md

Run this command to initialize your Terraform working directory. It downloads the necessary providers and sets up the backend.

```bash
terraform init
```

--------------------------------

### URL Structure Comparison

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/docs/examples.md

Compares the URL patterns for standalone (2-level) examples versus examples with options (3-level).

```APIDOC
## URL Structure

### 2-Level (Standalone)

```
/{topic}/                    # Shows first example in topic
/{topic}/{example}/          # Shows the example
```

### 3-Level (With Options)

```
/{topic}/                           # Redirects to first option of first example
/{topic}/{example}/                 # Redirects to first option
/{topic}/{example}/{option}/        # Shows specific option
```
```

--------------------------------

### Install PostgreSQL Query Extension

Source: https://github.com/flow-php/flow/blob/1.x/documentation/installation/packages/etl-adapter-postgresql.md

Install the PostgreSQL query extension for SQL parsing and query building. This is a suggested extension.

```bash
# For SQL parsing and query building
pie install flow-php/pg-query-ext
```

--------------------------------

### Verify Build with PHP Development Server

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/README.md

Starts a local PHP development server to verify the built static content. Access the application via https://localhost:9000.

```shell
php -S localhost:9000 -t build
```

--------------------------------

### CREATE INDEX with Different Access Methods

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/libs/postgresql/index-query-builder.md

Demonstrates creating indexes using various PostgreSQL access methods like B-tree, Hash, GIN, GiST, SP-GiST, and BRIN.

```php
<?php

use function Flow\PostgreSql\DSL\{create, index_method_btree, index_method_hash, index_method_gin, index_method_gist, index_method_spgist, index_method_brin};

// B-tree (default, good for equality and range queries)
$query = create()->index('idx_users_email')
    ->on('users')
    ->using(index_method_btree())
    ->columns('email');

// Hash (good for equality comparisons only)
$query = create()->index('idx_users_email')
    ->on('users')
    ->using(index_method_hash())
    ->columns('email');

// GIN (good for array values, full-text search, jsonb)
$query = create()->index('idx_documents_content')
    ->on('documents')
    ->using(index_method_gin())
    ->columns('content');

// GiST (good for geometric data, full-text search)
$query = create()->index('idx_locations_point')
    ->on('locations')
    ->using(index_method_gist())
    ->columns('point');

// SP-GiST (good for non-balanced data like phone numbers)
$query = create()->index('idx_users_phone')
    ->on('users')
    ->using(index_method_spgist())
    ->columns('phone');

// BRIN (good for large tables with naturally ordered data)
$query = create()->index('idx_events_timestamp')
    ->on('events')
    ->using(index_method_brin())
    ->columns('created_at');
```

--------------------------------

### Add Row Index with Custom Name and Start

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/core/transformations.md

Adds a row index column with a custom name and starting value.

```php
use function Flow\ETL\DSL\{df, from_array, add_row_index};
use Flow\ETL\Transformation\AddRowIndex\StartFrom;

// Custom column name and start from 1
df()
    ->read(from_array([/* ... */]))
    ->with(add_row_index('row_number', StartFrom::ONE))
    ->write(to_output())
    ->run();
```

--------------------------------

### Initialize AWS S3 Filesystem

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/bridges/filesystem-async-aws-bridge.md

Instantiates the AWS S3 filesystem using provided bucket, region, access key ID, and secret. This setup is necessary before mounting the filesystem.

```php
use function Flow\Filesystem\Bridge\AsyncAWS\DSL\{aws_s3_client, aws_s3_filesystem};

$aws = aws_s3_filesystem(
    $_ENV['AWS_S3_BUCKET'],
    aws_s3_client([
        'region' => $_ENV['AWS_S3_REGION'],
        'accessKeyId' => $_ENV['AWS_S3_KEY'],
        'accessKeySecret' => $_ENV['AWS_S3_SECRET'],
    ])
);

$fstab = fstab($aws);
```

--------------------------------

### Build API documentation

Source: https://github.com/flow-php/flow/blob/1.x/documentation/contributing/guidelines.md

Execute this command to build the API documentation using PHPDoc.

```bash
just docs-api
```

--------------------------------

### Install Parquet Dependencies

Source: https://github.com/flow-php/flow/blob/1.x/src/lib/parquet/resources/python/README.md

Installs required Python dependencies for Parquet data generation using pip within a virtual environment.

```shell
python3 -m venv parquet
source parquet/bin/activate
pip install -r requirements.txt
```

--------------------------------

### Install Doctrine DBAL Adapter

Source: https://github.com/flow-php/flow/blob/1.x/documentation/installation/packages/etl-adapter-doctrine.md

Install the flow-php/etl-adapter-doctrine package using Composer. Ensure you use the correct version for your PHP environment.

```bash
composer require flow-php/etl-adapter-doctrine:~--FLOW_PHP_VERSION--
```

--------------------------------

### Generate Migration from Schema Diff

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/bridges/symfony-postgresql-bundle.md

Compares the current database to catalog providers and generates migration SQL automatically. Use `--from-empty-schema` for initial setup or `--drop-if-exists` to emit `IF EXISTS` on DROP statements.

```bash
php bin/console flow:migrations:diff
```

```bash
php bin/console flow:migrations:diff --drop-if-exists
```

--------------------------------

### URI Resolution Examples

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/bridges/symfony-filesystem-bundle.md

Demonstrates how path arguments are resolved as full URIs. When a protocol is omitted, the local filesystem is assumed.

```bash
bin/console flow:filesystem:ls ./reports          # → file:///<cwd>/reports
```

```bash
bin/console flow:filesystem:ls /var/log           # → file:///var/log
```

```bash
bin/console flow:filesystem:ls memory://reports   # explicit protocol
```

--------------------------------

### Verify PHP Installation in Nix Shell

Source: https://github.com/flow-php/flow/blob/1.x/documentation/contributing/nix.md

Check the path to the PHP executable within the Nix shell to confirm its installation and version.

```shell
type php
```

--------------------------------

### Install Azure Blob Storage Bridge

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/bridges/symfony-filesystem-bundle.md

Install the necessary bridge package to enable Azure Blob Storage filesystem integration.

```bash
composer require flow-php/filesystem-azure-bridge
```

--------------------------------

### Install Symfony PostgreSQL Cache Bridge

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/bridges/symfony-postgresql-cache-bridge.md

Install the bridge using Composer. Ensure you use the correct Flow PHP version.

```bash
composer require flow-php/symfony-postgresql-cache-bridge:~--FLOW_PHP_VERSION--
```

--------------------------------

### Display Help for schema:format Command

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/cli/docs.md

Use this command to display detailed help information for the `schema:format` command. This includes a description, usage instructions, arguments, and available options for schema formatting.

```shell
flow schema:format --help
```

--------------------------------

### Custom AST Traversal with NodeVisitor

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/libs/postgresql.md

Illustrates how to traverse a SQL query's Abstract Syntax Tree (AST) using a custom `NodeVisitor`. This example counts the number of column references in a query.

```php
<?php

use Flow\PostgreSql\AST\NodeVisitor;
use Flow\PostgreSql\Protobuf\AST\ColumnRef;

use function Flow\PostgreSql\DSL\sql_parse;

class ColumnCounter implements NodeVisitor
{
    public int $count = 0;

    public static function nodeClasses(): array
    {
        return [ColumnRef::class];
    }

    public function enter(object $node): ?int
    {
        $this->count++;
        return null;
    }

    public function leave(object $node): ?int
    {
        return null;
    }
}

$query = sql_parse('SELECT id, name, email FROM users');

$counter = new ColumnCounter();
$query->traverse($counter);

echo $counter->count; // 3

```

--------------------------------

### Install PHPStan Types Bridge

Source: https://github.com/flow-php/flow/blob/1.x/src/bridge/phpstan/types/README.md

Install the extension using Composer. This command adds the necessary package to your project's development dependencies.

```bash
composer require --dev flow-php/phpstan-types-bridge
```

--------------------------------

### Install PHPUnit PostgreSQL Bridge

Source: https://github.com/flow-php/flow/blob/1.x/documentation/installation/packages/phpunit-postgresql-bridge.md

Install the package using Composer. Replace --FLOW_PHP_VERSION-- with your project's PHP version.

```bash
composer require flow-php/phpunit-postgresql-bridge:~--FLOW_PHP_VERSION--
```

--------------------------------

### Build Docker Image

Source: https://github.com/flow-php/flow/blob/1.x/documentation/contributing/environment.md

Build the Docker image and load it into the local registry.

```shell
just docker
```

--------------------------------

### Using Query Builder

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/libs/postgresql/client-fetching.md

Demonstrates how to use the Query Builder to construct SQL queries programmatically, which can then be passed to fetch methods.

```APIDOC
## Using Query Builder

### Description
All fetch methods accept both raw SQL strings and Query Builder objects. This section shows how to construct queries using the Query Builder.

### Request Example
```php
<?php

use function Flow\PostgreSql\DSL\{
    pgsql_client, pgsql_connection,
    select, col, table, eq, param, asc
};

$client = pgsql_client(pgsql_connection('host=localhost dbname=mydb'));

// Build query
$query = select(col('id'), col('name'), col('email'))
    ->from(table('users'))
    ->where(eq(col('active'), param(1)))
    ->orderBy(asc(col('name')))
    ->limit(10);

// Execute with parameters
$users = $client->fetchAll($query, [true]);
```
```

--------------------------------

### Install Symfony PostgreSQL Messenger Bridge

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/bridges/symfony-postgresql-messenger-bridge.md

Install the bridge package using Composer. This package is intended to be used with the Symfony PostgreSQL Bundle.

```bash
composer require flow-php/symfony-postgresql-messenger-bridge:~--FLOW_PHP_VERSION--
```

--------------------------------

### Run Pipeline Command Help

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/cli/docs.md

Displays help information for the `pipeline:run` command, outlining its usage, arguments, and options for executing data processing pipelines.

```shell
$ flow pipeline:run --help
```

--------------------------------

### Modified 'example' Controller Route

Source: https://github.com/flow-php/flow/blob/1.x/web/landing/docs/examples.md

This route is modified to detect if an example has options and redirects to the first option if it does, ensuring a seamless user experience.

```php
$options = $this->examples->options($topic, $example);
if (count($options) > 0) {
    return $this->redirectToRoute('example_option', [
        'topic' => $topic,
        'example' => $example,
        'option' => current($options),
    ]);
}
```

--------------------------------

### Build and Run PHPT Tests

Source: https://github.com/flow-php/flow/blob/1.x/documentation/contributing/rust.md

Combines building the extension and running the PHPT test suite in a single command.

```bash
nix-shell --arg with-arrow-ext false --arg with-rust true --run "cd src/extension/arrow-ext && make build && make test"
```

--------------------------------

### Install Flow PHP ETL Core

Source: https://github.com/flow-php/flow/blob/1.x/documentation/installation/packages/etl.md

Use Composer to install the flow-php/etl package. Ensure you replace --FLOW_PHP_VERSION-- with the appropriate version.

```bash
composer require flow-php/etl:~--FLOW_PHP_VERSION--
```

--------------------------------

### Display Help for db:table:list Command

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/cli/docs.md

Use this command to display detailed help information for the `db:table:list` command. This includes a description, usage instructions, and available options.

```shell
flow db:table:list --help
```

--------------------------------

### Install Monolog Logger Implementation

Source: https://github.com/flow-php/flow/blob/1.x/documentation/installation/packages/etl-adapter-logger.md

Install Monolog, a popular PSR-3 compatible logger implementation, using Composer. This is required by the ETL logger adapter.

```bash
composer require monolog/monolog
```

--------------------------------

### Create a Parquet Reader

Source: https://github.com/flow-php/flow/blob/1.x/documentation/components/libs/parquet.md

Instantiate a new Parquet reader. This uses the adaptive engine by default. Ensure you have the necessary 'use' statement.

```php
use Flow\Parquet\Reader;

$reader = new Reader();
```