===============
LIBRARY RULES
===============
From library maintainers:
- Configure the bundle through environment variables: AWS_REGION, RDS_IAM_USERNAME, RDS_SECRET_ARN. A null or empty value disables the corresponding mode.
- Keep the regular DoctrineBundle connection configuration. The bundle does not replace it.
- Reuse database connections through FrankenPHP worker mode or RDS Proxy before you enable IAM authentication under a high connection rate.

### Full IAM Setup Example

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/credential-modes.md

Comprehensive example covering configuration files and environment variables for a full IAM setup.

```yaml
# config/packages/rds_auth.yaml
rds_auth:
    region: '%env(AWS_REGION)%'
    iam_username: '%env(RDS_IAM_USERNAME)%'
    cache_pool: rds_credentials

# config/packages/doctrine.yaml
doctrine:
    dbal:
        driver: pdo_pgsql
        host: '%env(RDS_HOST)%'
        port: '%env(int:RDS_PORT)%'
        dbname: '%env(RDS_DATABASE)%'
        user: 'app_user'
        password: 'dummy'

# config/packages/cache.yaml
framework:
    cache:
        pools:
            rds_credentials:
                adapter: cache.adapter.apcu

# .env.prod
AWS_REGION=us-west-2
RDS_HOST=db.example.com
RDS_PORT=5432
RDS_DATABASE=myapp
RDS_IAM_USERNAME=app_user
```

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

### Full Master-Password Setup Example

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/credential-modes.md

Complete configuration example including bundle settings, Doctrine DBAL setup, and environment variables.

```yaml
# config/packages/rds_auth.yaml
rds_auth:
    region: '%env(AWS_REGION)%'
    secret_arn: '%env(RDS_SECRET_ARN)%'
    cache_pool: null

# config/packages/doctrine.yaml
doctrine:
    dbal:
        driver: pdo_pgsql
        host: '%env(RDS_HOST)%'
        port: '%env(int:RDS_PORT)%'
        dbname: '%env(RDS_DATABASE)%'
        user: '%env(RDS_USERNAME)%'
        password: '%env(RDS_PASSWORD)%'
        sslmode: require

# .env.prod (or injected by ECS, Elastic Beanstalk, Kubernetes)
AWS_REGION=us-east-1
RDS_HOST=db.example.com
RDS_PORT=5432
RDS_DATABASE=myapp
RDS_USERNAME=postgres
RDS_PASSWORD=<secret-value-at-deployment-time>
RDS_SECRET_ARN=arn:aws:secretsmanager:us-east-1:123456789012:secret:rds!prod-cluster-secret-xyz
```

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

### Configure Local Development Environment

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/credential-modes.md

Example setup for local development using static credentials and local database host.

```yaml
# config/packages/doctrine.yaml
doctrine:
    dbal:
        driver: pdo_pgsql
        host: '%env(DB_HOST)%'
        port: '%env(int:DB_PORT)%'
        dbname: '%env(DB_NAME)%'
        user: '%env(DB_USER)%'
        password: '%env(DB_PASSWORD)%'

# .env.local
AWS_REGION=us-west-2
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp
DB_USER=myuser
DB_PASSWORD=localpassword
```

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

### Example configuration flow

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/bundle-class.md

Demonstrates the internal configuration process for the bundle.

```php
// Typical configuration flow; the bundle handles this internally
$bundle = new RdsAuthBundle();
$definition = new DefinitionConfigurator();
$bundle->configure($definition);
// Results in configuration array like:
// [
//     'region' => 'us-east-1',
//     'iam_username' => 'app_user',
//     'secret_arn' => null,
//     'cache_pool' => 'cache.app',
//     'connections' => []
// ]
```

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

### Install Redis

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/installation.md

Commands to install or run Redis on various platforms.

```bash
# Docker
docker run -d -p 6379:6379 redis:latest

# Ubuntu/Debian
sudo apt-get install redis-server

# macOS
brew install redis
```

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

### Full Configuration File

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/installation.md

Example of a complete configuration file defining all available options.

```yaml
# config/packages/rds_auth.yaml
rds_auth:
    region: '%env(AWS_REGION)%'
    iam_username: '%env(default::RDS_IAM_USERNAME)%'
    secret_arn: '%env(default::RDS_SECRET_ARN)%'
    cache_pool: cache.app
    connections: []
```

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

### Example loadExtension execution

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/bundle-class.md

Illustrates how the loadExtension method processes configuration to register services and tags.

```php
// This method is called automatically during container compilation
// with merged configuration from config files and environment variables.
// If config is:
// [
//     'region' => 'us-west-2',
//     'iam_username' => 'app_user',
//     'secret_arn' => null,
//     'cache_pool' => 'cache.app',
//     'connections' => []
// ]
// 
// Then three services are registered and middleware is tagged
// with 'doctrine.middleware' (no connection attribute).
```

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

### Generate Middleware Tags

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/scoped-connections.md

Examples of how the bundle generates tags for empty versus non-empty connection configurations.

```php
$middleware->tag('doctrine.middleware');  // No connection attribute
```

```php
$middleware->tag('doctrine.middleware', ['connection' => 'primary']);
$middleware->tag('doctrine.middleware', ['connection' => 'replica']);
```

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

### Environment-Specific Authentication Configuration

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/credential-modes.md

Examples of setting environment variables to trigger different authentication modes for local, staging, and production environments.

```bash
# Local: no env vars set
$ symfony console doctrine:schema:validate
# Uses static password from .env.local

# Staging
$ AWS_REGION=ap-southeast-2 RDS_IAM_USERNAME=app_user symfony server:start
# Uses IAM authentication with token

# Production (ECS task definition, Kubernetes secrets, etc.)
AWS_REGION=us-east-1
RDS_SECRET_ARN=arn:aws:secretsmanager:...
# Uses master-password refresh
```

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

### Environment Configuration

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/installation.md

Various environment variable setups for different authentication strategies and development needs.

```bash
# .env or deployment configuration
AWS_REGION=us-west-2
```

```bash
AWS_REGION=us-west-2
RDS_IAM_USERNAME=app_user
```

```bash
AWS_REGION=us-west-2
RDS_SECRET_ARN=arn:aws:secretsmanager:us-west-2:123456789012:secret:rds!db-abc123
RDS_PASSWORD=<current-secret-value>
```

```bash
# .env.local
AWS_REGION=us-west-2
# RDS_IAM_USERNAME and RDS_SECRET_ARN left unset
# Middleware is present but inactive
```

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

### Install the bundle via Composer

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/README.md

Use this command to add the bundle to your Symfony project dependencies.

```bash
composer require tacticmedia/rds-auth-bundle
```

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

### Install APCu Extension

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/installation.md

Commands to install the APCu PHP extension on various operating systems.

```bash
# Ubuntu/Debian
sudo apt-get install php-apcu

# macOS with Homebrew
brew install php@8.4 && pecl install apcu

# RHEL/CentOS
sudo yum install php-pecl-apcu
```

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

### Configure IAM Authentication DBAL Parameters

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/dbal-parameters.md

Example configuration for a Doctrine DBAL connection using IAM authentication.

```yaml
doctrine:
    dbal:
        driver: pdo_pgsql
        host: db.example.com
        port: 5432
        user: dummy_user
        password: dummy_password
        sslmode: prefer
```

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

### Test Code Integration

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/types-and-imports.md

Example of testing the RDS Auth driver within a KernelTestCase.

```php
use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
use Doctrine\Bundle\DoctrineBundle\Registry;
use Doctrine\DBAL\Connection;
use TacticMedia\RdsAuth\RdsAuthDriver;

class MyTest extends KernelTestCase
{
    public function test(): void
    {
        self::bootKernel();
        
        $registry = self::getContainer()->get('doctrine');
        $connection = $registry->getConnection();
        
        if ($connection->getDriver() instanceof RdsAuthDriver) {
            // Middleware is active
        }
    }
}
```

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

### Retrieve rds_auth.middleware from container

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/services.md

Example of accessing the middleware service from the kernel container.

```php
$kernel = self::bootKernel();
$container = $kernel->getContainer();
$middleware = $container->get('rds_auth.middleware');
```

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

### Configure Token Caching

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/credential-modes.md

Setup for the cache pool used to store temporary authentication tokens.

```yaml
rds_auth:
    cache_pool: rds_credentials

framework:
    cache:
        pools:
            rds_credentials:
                adapter: cache.adapter.apcu
```

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

### Retrieve rds_auth.password_provider from container

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/services.md

Example of accessing the password provider service from the kernel container.

```php
$kernel = self::bootKernel();
$container = $kernel->getContainer();
$passwordProvider = $container->get('rds_auth.password_provider');
```

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

### Configure IAM Auth for Primary and Replica

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/scoped-connections.md

Example configuration applying IAM authentication to multiple RDS instances while excluding a reporting database.

```yaml
rds_auth:
    iam_username: app_iam
    connections: ['primary', 'replica']

doctrine:
    dbal:
        default_connection: primary
        connections:
            primary:
                driver: pdo_pgsql
                host: '%env(RDS_PRIMARY_HOST)%'
                user: dummy  # Overridden by IAM
            replica:
                driver: pdo_pgsql
                host: '%env(RDS_REPLICA_HOST)%'
                user: dummy  # Overridden by IAM
            reporting:
                driver: pdo_mysql
                host: '%env(REPORTING_DB_HOST)%'
                user: '%env(REPORTING_DB_USER)%'
                password: '%env(REPORTING_DB_PASSWORD)%'
```

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

### Configure Master-Password Refresh DBAL Parameters

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/dbal-parameters.md

Example configuration for a Doctrine DBAL connection using Secrets Manager for password rotation.

```yaml
doctrine:
    dbal:
        driver: pdo_pgsql
        host: db.example.com
        port: 5432
        user: postgres
        password: injected_secret_value
```

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

### Configure IAM Auth for Specific Connections

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/scoped-connections.md

Example configuration where only the default connection uses IAM authentication while others use static credentials.

```yaml
rds_auth:
    iam_username: '%env(RDS_IAM_USERNAME)%'
    connections: ['default']

doctrine:
    dbal:
        default_connection: default
        connections:
            default:
                driver: pdo_pgsql
                host: '%env(RDS_HOST)%'
                user: app_iam
            cache:
                driver: pdo_redis
                host: '%env(REDIS_HOST)%'
            legacy:
                driver: pdo_mysql
                host: '%env(LEGACY_DB_HOST)%'
                user: legacy_user
                password: '%env(LEGACY_DB_PASSWORD)%'
```

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

### Configure Redis Cache Pool in Symfony

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/installation.md

Setup the Redis cache pool within Symfony framework and rds_auth configuration.

```yaml
# config/packages/cache.yaml
framework:
    cache:
        default: redis
        pools:
            rds_credentials:
                adapter: cache.adapter.redis
                provider: 'redis://localhost:6379'

# config/packages/rds_auth.yaml
rds_auth:
    cache_pool: rds_credentials
```

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

### Bootstrap the Kernel

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/testing-guide.md

Boots the kernel defined by getKernelClass(). Options like debug are passed to the kernel.

```php
self::bootKernel(['debug' => false]);
```

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

### Configure Initial No-Middleware DBAL Parameters

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/dbal-parameters.md

Initial YAML configuration for a development environment without middleware intervention.

```yaml
doctrine:
    dbal:
        driver: pdo_pgsql
        host: localhost
        port: 5432
        dbname: development
        user: dev_user
        password: dev_password
        charset: utf8mb4
```

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

### Configure Initial IAM DBAL Parameters

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/dbal-parameters.md

Initial YAML configuration for a PostgreSQL connection before IAM middleware processing.

```yaml
doctrine:
    dbal:
        driver: pdo_pgsql
        host: prod-db.example.com
        port: 5432
        dbname: production
        user: temp_user
        password: temp_password
        sslmode: prefer
        charset: utf8mb4
```

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

### Configure Standard Framework Pool

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/cache-behavior.md

Sets up the default application cache using the filesystem adapter.

```yaml
framework:
    cache:
        app: cache.adapter.filesystem
```

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

### Configure All Connections

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/scoped-connections.md

Default behavior where the middleware applies to all configured DBAL connections.

```yaml
rds_auth:
    connections: []
```

```yaml
rds_auth:
    region: '%env(AWS_REGION)%'
    iam_username: '%env(RDS_IAM_USERNAME)%'
```

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

### Run project tests and quality assurance

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/INDEX.md

Use these composer commands to execute the test suite, generate coverage reports, or run the full quality assurance pipeline.

```bash
composer test                    # All tests
composer test-coverage          # Tests with coverage reports
vendor/bin/phpunit --filter testName  # Single test
composer qa                      # All checks (rector, cs, stan, test)
```

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

### Configure Initial Master-Password DBAL Parameters

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/dbal-parameters.md

Initial YAML configuration for a PostgreSQL connection using a master password.

```yaml
doctrine:
    dbal:
        driver: pdo_pgsql
        host: prod-db.example.com
        port: 5432
        dbname: production
        user: postgres
        password: 'injected_secret_123'  # Set at startup
        charset: utf8mb4
```

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

### Default Configuration

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/installation.md

Shows the default behavior when no configuration file is provided.

```yaml
# No config/packages/rds_auth.yaml needed
# Defaults:
# - region: %env(AWS_REGION)%
# - iam_username: %env(default::RDS_IAM_USERNAME)%
# - secret_arn: %env(default::RDS_SECRET_ARN)%
# - cache_pool: cache.app
# - connections: []
```

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

### Configure APCu Cache Pool in Symfony

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/installation.md

Setup the APCu cache pool within Symfony framework and rds_auth configuration.

```yaml
# config/packages/cache.yaml
framework:
    cache:
        pools:
            rds_credentials:
                adapter: cache.adapter.apcu

# config/packages/rds_auth.yaml
rds_auth:
    cache_pool: rds_credentials
```

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

### Import RdsAuthBundle

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/types-and-imports.md

Import path for the bundle class.

```php
use TacticMedia
dsAuthBundle
dsAuthBundle;
```

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

### Minimal Configuration File

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/installation.md

The region parameter is mandatory for the bundle configuration.

```yaml
rds_auth:
    region: '%env(AWS_REGION)%'
```

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

### Import RdsSecretPasswordProvider

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/types-and-imports.md

Import path for the secret password provider.

```php
use TacticMedia\RdsAuth\RdsSecretPasswordProvider;
```

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

### Define configuration method signature

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/bundle-class.md

The configure method accepts a DefinitionConfigurator to build the bundle's configuration tree.

```php
public function configure(DefinitionConfigurator $definition): void
```

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

### Project File Structure

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/INDEX.md

Visual representation of the documentation directory layout.

```text
/workspace/home/output/
├── INDEX.md                      ← You are here
├── overview.md                   ← Start here
├── installation.md               ← Then read this
├── configuration.md              ← Then this
├── credential-modes.md           ← And this
├── examples-and-recipes.md       ← Real code examples
├── bundle-class.md               ← API reference
├── services.md                   ← Service reference
├── middleware-integration.md      ← Architecture
├── dbal-parameters.md            ← Detailed behavior
├── cache-behavior.md             ← Cache details
├── scoped-connections.md         ← Connection filtering
├── types-and-imports.md          ← Type reference
└── testing-guide.md              ← Testing reference
```

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

### Implement Connection Scoping in loadExtension

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/scoped-connections.md

Logic for tagging the middleware based on the presence of configured connections.

```php
// From src/RdsAuthBundle.php, lines 81-89
if ([] === $config['connections']) {
    // Empty connections list: apply to all
    $middleware->tag('doctrine.middleware');
    return;
}

// Non-empty connections list: apply per connection
foreach ($config['connections'] as $connection) {
    $middleware->tag('doctrine.middleware', ['connection' => $connection]);
}
```

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

### Run Test Suite Commands

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/testing-guide.md

Commands to execute the test suite using composer or phpunit.

```bash
composer test
# or
vendor/bin/phpunit
```

```bash
vendor/bin/phpunit tests/RdsAuthBundleTest.php
```

```bash
vendor/bin/phpunit --filter testWrapsTheDefaultConnection
```

```bash
composer test-coverage
# Generates coverage/html/ and coverage/clover.xml
```

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

### Standard Bundle Application Imports

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/types-and-imports.md

Common imports for bootstrapping, configuration, and service usage within the application.

```php
// Bootstrap
use TacticMedia\RdsAuthBundle\RdsAuthBundle;

// Configuration
return [
    TacticMedia\RdsAuthBundle\RdsAuthBundle::class => ['all' => true],
];

// Using services
use TacticMedia\RdsAuth\RdsIamTokenProvider;
use TacticMedia\RdsAuth\RdsSecretPasswordProvider;
use TacticMedia\RdsAuth\RdsAuthMiddleware;

// Testing middleware
use TacticMedia\RdsAuth\RdsAuthDriver;

// Database access
use Doctrine\Bundle\DoctrineBundle\Registry;
use Doctrine\DBAL\Connection;
```

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

### Configure host and port

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/dbal-parameters.md

Host and port parameters remain unchanged by the middleware.

```yaml
doctrine:
    dbal:
        host: db.example.com
        port: 5432

# Both remain unchanged in all modes
# Middleware uses host/port to construct the token signature
```

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

### Register the Bundle in config/bundles.php

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/docs/installation.md

Add the bundle class to the returned array in your bundles configuration file to enable it.

```php
return [
    // ...
    TacticMedia\RdsAuthBundle\RdsAuthBundle::class => ['all' => true],
];
```

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

### Execute Development Testing Workflow

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/testing-guide.md

Common commands for running tests, checking quality gates, and generating coverage reports.

```bash
# Run specific test
vendor/bin/phpunit --filter testName

# Run all tests
composer test

# Check all quality gates
composer qa  # rector + cs + stan + test

# Check with coverage
composer test-coverage
```

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

### Import RdsIamTokenProvider

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/types-and-imports.md

Import path for the IAM token provider.

```php
use TacticMedia\RdsAuth\RdsIamTokenProvider;
```

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

### Import RdsAuthMiddleware

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/types-and-imports.md

Import path for the middleware class.

```php
use TacticMedia\RdsAuth\RdsAuthMiddleware;
```

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

### Configure PostgreSQL SSL mode

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/dbal-parameters.md

Demonstrates how the middleware enforces sslmode in IAM mode.

```yaml
# Original config
doctrine:
    dbal:
        sslmode: prefer

# After middleware (IAM mode)
sslmode: require

# Original config
doctrine:
    dbal:
        sslmode: require

# After middleware (IAM mode)
sslmode: require  # No change, already set correctly
```

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

### Implement TestKernel Base Class

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/testing-guide.md

Extends the base Kernel with MicroKernelTrait to allow inline configuration of bundles and container services for testing.

```php
// tests/Support/TestKernel.php
class TestKernel extends Kernel
{
    use MicroKernelTrait;

    public function registerBundles(): iterable
    {
        yield new FrameworkBundle();
        yield new DoctrineBundle();
        yield new RdsAuthBundle();
    }

    public function getCacheDir(): string
    {
        return sys_get_temp_dir().'/rds-auth-bundle-tests/'.self::VERSION.'/'.str_replace('\', '_', static::class).'/cache';
    }

    public function getLogDir(): string
    {
        return sys_get_temp_dir().'/rds-auth-bundle-tests/'.self::VERSION.'/'.str_replace('\', '_', static::class).'/log';
    }

    protected function configureContainer(ContainerConfigurator $container): void
    {
        $container->extension('framework', [
            'secret' => 'test',
            'test' => true,
        ]);
        $container->extension('doctrine', [
            'dbal' => ['url' => 'sqlite:///:memory:'],
        ]);
        $container->extension('rds_auth', []);
    }

    protected function configureRoutes(RoutingConfigurator $routes): void
    {
    }
}
```

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

### Import ContainerConfigurator

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/types-and-imports.md

Provides the fluent interface for service configuration in loadExtension.

```php
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
```

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

### Verify Universal Middleware Application

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/middleware-integration.md

Demonstrates that a connection driver is wrapped in RdsAuthDriver when no specific connection is targeted.

```php
// When a connection is created, DoctrineBundle finds all
// doctrine.middleware tags without a connection attribute
// and applies them universally.
$connection = $registry->getConnection('default');
$driver = $connection->getDriver(); // Wrapped in RdsAuthDriver
```

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

### Enable Caching

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/cache-behavior.md

Configures the bundle to use a specific PSR-6 cache pool service.

```yaml
rds_auth:
    cache_pool: cache.app
```

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

### Import RdsAuthDriver

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/types-and-imports.md

Import path for the driver class.

```php
use TacticMedia\RdsAuth\RdsAuthDriver;
```

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

### Run Static Analysis and Code Quality Tools

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/testing-guide.md

Commands for executing PHPStan, PHP-CS-Fixer, and Rector to maintain code quality.

```bash
composer stan
```

```bash
composer cs
```

```bash
composer rector
```

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

### Register Middleware for All Connections

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/middleware-integration.md

Applies the middleware to all DBAL connections when the connections configuration is empty.

```php
if ([] === $config['connections']) {
    $middleware->tag('doctrine.middleware');
    return;
}
```

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

### Default Bundle Configuration

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/docs/configuration.md

The default configuration file for the bundle, utilizing environment variables for dynamic settings.

```yaml
# config/packages/rds_auth.yaml
rds_auth:
    region: '%env(AWS_REGION)%'
    iam_username: '%env(default::RDS_IAM_USERNAME)%'   # null or empty disables IAM authentication
    secret_arn: '%env(default::RDS_SECRET_ARN)%'       # null or empty disables the master-password refresh
    cache_pool: cache.app                              # null disables caching
    connections: []                                    # empty applies to every DBAL connection
```

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

### Documentation Hierarchy Visualization

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/README.md

A visual representation of the documentation structure and dependency flow.

```text
What (overview)
  ↓
Why/When (credential modes, caching, scoping)
  ↓
How (installation, configuration)
  ↓
What code (services, bundle class, types)
  ↓
Example code (examples-and-recipes)
  ↓
Detailed behavior (parameters, middleware integration)
  ↓
Testing (testing-guide)
```

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

### Configure database driver

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/dbal-parameters.md

The driver configuration remains unchanged as the middleware wraps the existing driver.

```yaml
doctrine:
    dbal:
        driver: pdo_pgsql

# Remains pdo_pgsql; the middleware wraps this driver
# The connection's getDriver() returns RdsAuthDriver, not pdo_pgsql
```

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

### Test Token Provider Service

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/testing-guide.md

Retrieves the token provider service from the container to verify its instance type. Requires a booted kernel environment.

```php
public function testTokenProvider(): void
{
    self::bootKernel();
    
    $tokenProvider = self::getContainer()->get('rds_auth.token_provider');
    self::assertInstanceOf(RdsIamTokenProvider::class, $tokenProvider);
}
```

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

### Import ContainerBuilder

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/types-and-imports.md

Used for building and compiling the service container.

```php
use Symfony\Component\DependencyInjection\ContainerBuilder;
```

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

### Define Doctrine DBAL Connection Parameters

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/credential-modes.md

Standard Doctrine configuration using environment variables for static password authentication.

```yaml
doctrine:
    dbal:
        driver: pdo_pgsql
        host: '%env(RDS_HOST)%'
        port: '%env(int:RDS_PORT)%'
        dbname: '%env(RDS_DATABASE)%'
        user: '%env(RDS_USERNAME)%'
        password: '%env(RDS_PASSWORD)%'
```

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

### Create Test Base Class

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/testing-guide.md

Extends KernelTestCase to provide a testing environment for the bundle, including custom kernel class registration and connection verification.

```php
// From tests/RdsAuthBundleTest.php
use Symfonyundlerameworkbundle	est	estcase;

final class RdsAuthBundleTest extends KernelTestCase
{
    protected static function getKernelClass(): string
    {
        return TestKernel::class;
    }

    protected function tearDown(): void
    {
        parent::tearDown();
        restore_exception_handler();
    }

    public function testWrapsTheDefaultConnection(): void
    {
        self::bootKernel(['debug' => false]);
        
        $connection = $this->connection();
        self::assertInstanceOf(RdsAuthDriver::class, $connection->getDriver());
        self::assertEquals(1, $connection->fetchOne('SELECT 1'));
    }

    private function connection(): Connection
    {
        $registry = self::getContainer()->get('doctrine');
        $connection = $registry->getConnection();
        return $connection;
    }
}
```

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

### Configure Multiple Specific Connections

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/scoped-connections.md

Apply the middleware to a subset of multiple connections while excluding others.

```yaml
rds_auth:
    connections: ['primary', 'replica', 'analytics']

doctrine:
    dbal:
        connections:
            primary:
                driver: pdo_pgsql
                host: '%env(RDS_PRIMARY_HOST)%'
                dbname: app
            replica:
                driver: pdo_pgsql
                host: '%env(RDS_REPLICA_HOST)%'
                dbname: app
            analytics:
                driver: pdo_pgsql
                host: '%env(RDS_ANALYTICS_HOST)%'
                dbname: analytics
            cache:
                driver: pdo_sqlite
                path: '%kernel.cache_dir%/queries.db'
```

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

### Import Doctrine Connection

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/types-and-imports.md

Import the DBAL Connection class for use in tests and application code.

```php
use Doctrine\DBAL\Connection;
```

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

### Configure password authentication modes

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/dbal-parameters.md

Shows configuration for IAM mode and Master-password mode.

```yaml
# IAM mode
rds_auth:
    iam_username: app_iam
# DBAL password becomes: (generated token, e.g., "EwVCOSFzdHMuMj...")

# Master-password mode
rds_auth:
    secret_arn: 'arn:aws:secretsmanager:...'
# DBAL password on first attempt: (from config)
# DBAL password on retry: (from Secrets Manager)
```

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

### Configure Filesystem Cache Pool

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/cache-behavior.md

Configures a filesystem-based cache pool for single-instance environments.

```yaml
framework:
    cache:
        pools:
            rds_credentials:
                adapter: cache.adapter.filesystem

rds_auth:
    cache_pool: rds_credentials
```

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

### Bundle Not Found Error

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/installation.md

Indicates the bundle class is not recognized by the application.

```text
Class "TacticMedia\RdsAuthBundle\RdsAuthBundle" not found
```

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

### Import DefinitionConfigurator

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/types-and-imports.md

Required for implementing the fluent interface in configuration trees.

```php
use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator;
```

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

### Handle Non-Existent Connections

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/scoped-connections.md

Demonstrates that the middleware tags connections even if they are missing from the Doctrine configuration, resulting in no effect for those specific connections.

```yaml
rds_auth:
    connections: ['primary', 'nonexistent']

doctrine:
    dbal:
        connections:
            primary:
                driver: pdo_pgsql
                host: '%env(RDS_HOST)%'
```

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

### Configure TestKernel

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/testing-guide.md

Doctrine and RDS Auth configuration for the default TestKernel.

```php
$container->extension('doctrine', [
    'dbal' => ['url' => 'sqlite:///:memory:'],
]);
```

```php
$container->extension('rds_auth', []);
// Uses all defaults:
// - region: %env(AWS_REGION)%
// - iam_username: %env(default::RDS_IAM_USERNAME)%
// - secret_arn: %env(default::RDS_SECRET_ARN)%
// - cache_pool: cache.app
// - connections: []
```

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

### Run development and testing commands

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/docs/testing.md

Use these Composer scripts to manage dependencies, execute PHPUnit tests, run static analysis, and perform code style checks.

```bash
composer install
composer test                                  # PHPUnit
vendor/bin/phpunit tests/RdsAuthBundleTest.php # one test file
vendor/bin/phpunit --filter testWrapsTheDefaultConnection
composer test-coverage                         # HTML and clover reports in coverage/
composer stan                                  # PHPStan level 8 over src and tests
composer cs                                    # php-cs-fixer (@auto, @PhpCsFixer, @Symfony)
composer rector
composer qa                                    # rector, cs, stan, test in sequence
```

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

### Testing a new cache adapter configuration

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/testing-guide.md

Defines a custom kernel to configure the container and a test class to verify the RDS auth driver and database connection.

```php
// tests/Support/RedisTestKernel.php
final class RedisTestKernel extends TestKernel
{
    protected function configureContainer(ContainerConfigurator $container): void
    {
        $container->extension('framework', [
            'secret' => 'test',
            'test' => true,
            'cache' => [
                'default' => 'redis',
                'pools' => [
                    'redis' => ['adapter' => 'cache.adapter.redis'],
                ],
            ],
        ]);
        $container->extension('doctrine', [
            'dbal' => ['url' => 'sqlite:///:memory:'],
        ]);
        $container->extension('rds_auth', [
            'cache_pool' => 'redis',
        ]);
    }
}

// tests/RedisTest.php
final class RedisTest extends KernelTestCase
{
    protected static function getKernelClass(): string
    {
        return RedisTestKernel::class;
    }

    protected function tearDown(): void
    {
        parent::tearDown();
        restore_exception_handler();
    }

    public function testRedisCache(): void
    {
        self::bootKernel(['debug' => false]);
        
        $connection = self::getContainer()->get('doctrine')->getConnection();
        self::assertInstanceOf(RdsAuthDriver::class, $connection->getDriver());
        self::assertEquals(1, $connection->fetchOne('SELECT 1'));
    }
}
```

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

### Configure Cache in Test Kernel

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/cache-behavior.md

Enable the framework's in-memory cache within a test kernel to simulate production behavior during testing.

```php
// tests/Support/TestKernel.php
protected function configureContainer(ContainerConfigurator $container): void
{
    $container->extension('framework', [
        'secret' => 'test',
        'test' => true,  // Uses in-memory cache for testing
    ]);
    // ...
    $container->extension('rds_auth', [
        'cache_pool' => 'cache.app',
    ]);
}
```

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

### Import Doctrine Middleware

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/types-and-imports.md

Import the Middleware interface for Doctrine DBAL.

```php
use Doctrine\DBAL\Middleware;
```

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

### Import and Use Doctrine Registry

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/types-and-imports.md

Import the Registry class to access configured connections and entity managers.

```php
use Doctrine\Bundle\DoctrineBundle\Registry;
```

```php
$registry = $container->get('doctrine');
$connection = $registry->getConnection('default');
```

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

### View Master-Password Connection Attempt Parameters

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/dbal-parameters.md

Parameter state during the first connection attempt before any authentication failure.

```text
user: postgres
password: 'injected_secret_123'
# All parameters unchanged
```

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

### Import AbstractBundle

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/types-and-imports.md

Use this base class when defining a Symfony bundle.

```php
use Symfony\Component\HttpKernel\Bundle\AbstractBundle;
```

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

### Log Connection Details

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/examples-and-recipes.md

Logs the current driver class, middleware status, and connection parameters using a PSR-3 logger.

```php
use Psr\Log\LoggerInterface;

class ConnectionLogger
{
    public function __construct(
        private Registry $doctrine,
        private LoggerInterface $logger,
    ) {}

    public function logConnectionState(): void
    {
        $connection = $this->doctrine->getConnection();
        $driver = $connection->getDriver();
        
        $this->logger->info('Connection state', [
            'driver_class' => $driver::class,
            'using_rds_auth' => $driver instanceof RdsAuthDriver,
            'host' => $connection->getParams()['host'] ?? null,
            'dbname' => $connection->getParams()['dbname'] ?? null,
        ]);
    }
}
```

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

### Instantiate rds_auth.token_provider

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/services.md

Service definition as performed in the bundle extension.

```php
$services->set('rds_auth.token_provider', RdsIamTokenProvider::class)
    ->args([$config['region']])
;
```

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

### Environment Variable Configuration

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/examples-and-recipes.md

Define environment variables for local development and production environments.

```bash
AWS_REGION=us-west-2
RDS_HOST=localhost
RDS_PORT=5432
RDS_DATABASE=myapp
RDS_IAM_USERNAME=
```

```bash
AWS_REGION=us-west-2
RDS_HOST=prod-db.example.com
RDS_PORT=5432
RDS_DATABASE=myapp
RDS_IAM_USERNAME=app
```

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

### Execute a Database Query

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/testing-guide.md

Verifies that queries execute successfully through the wrapped driver.

```php
$result = $connection->fetchOne('SELECT 1');
self::assertEquals(1, $result);
```

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

### Constructor for RdsAuthMiddleware

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/types-and-imports.md

Constructor signature for the Doctrine DBAL middleware.

```php
public function __construct(
    RdsIamTokenProvider $tokenProvider,
    RdsSecretPasswordProvider $passwordProvider,
    ?string $iamUsername,
    ?string $secretArn,
    ?CacheItemPoolInterface $cachePool
)
```

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

### Configure No-Cache Test Kernel

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/examples-and-recipes.md

Sets up a test kernel with the cache pool explicitly disabled for testing scenarios without caching.

```php
final class NoCacheTestKernel extends TestKernel
{
    protected function configureContainer(ContainerConfigurator $container): void
    {
        $container->extension('framework', [
            'secret' => 'test',
            'test' => true,
        ]);
        $container->extension('doctrine', [
            'dbal' => ['url' => 'sqlite:///:memory:'],
        ]);
        $container->extension('rds_auth', [
            'cache_pool' => null,
        ]);
    }
}
```

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

### Verify bundle registration with PHPUnit

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/installation.md

A kernel test to ensure the middleware is present and the database driver is correctly configured as an RdsAuthDriver.

```php
use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
use TacticMedia\RdsAuth\RdsAuthDriver;

class BundleTest extends KernelTestCase
{
    public function testBundleIsRegistered(): void
    {
        self::bootKernel();
        
        $container = self::getContainer();
        self::assertTrue($container->has('rds_auth.middleware'));
        
        $doctrine = $container->get('doctrine');
        $connection = $doctrine->getConnection();
        self::assertInstanceOf(RdsAuthDriver::class, $connection->getDriver());
    }
}
```

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

### Define Environment Variables

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/examples-and-recipes.md

Set the required environment variables for AWS and database connectivity.

```bash
AWS_REGION=us-east-1
RDS_HOST=prod-db.example.com
RDS_PORT=5432
RDS_DATABASE=myapp
RDS_USERNAME=postgres
RDS_PASSWORD=<secret-injected-at-startup>
RDS_SECRET_ARN=arn:aws:secretsmanager:us-east-1:123456789012:secret:rds!prod-cluster-secret-xyz
```

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

### Verify bundle services via Symfony Console

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/installation.md

Use the debug command to confirm that the bundle services are correctly registered in the container.

```bash
# List all services
symfony console debug:container rds_auth

# Output should show:
# rds_auth.token_provider
# rds_auth.password_provider
# rds_auth.middleware
```

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

### Configure Doctrine DBAL for Production

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/docs/doctrine-dbal.md

Use individual parameters instead of a DSN to avoid issues with special characters in RDS passwords.

```yaml
# config/packages/doctrine.yaml
when@prod:
    doctrine:
        dbal:
            driver: pdo_pgsql
            host: '%env(RDS_HOST)%'
            port: '%env(int:RDS_PORT)%'
            dbname: '%env(RDS_DATABASE)%'
            user: '%env(RDS_USERNAME)%'
            password: '%env(RDS_PASSWORD)%'
            server_version: '%env(RDS_SERVER_VERSION)%'
            sslmode: require
```

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

### Configure database name

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/dbal-parameters.md

The database name parameter remains unchanged.

```yaml
doctrine:
    dbal:
        dbname: myapp

# Remains myapp in all modes
```

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

### Configure ScopedTestKernel

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/testing-guide.md

Doctrine and RDS Auth configuration for testing connection scoping.

```php
$container->extension('doctrine', [
    'dbal' => [
        'default_connection' => 'covered',
        'connections' => [
            'covered' => ['url' => 'sqlite:///:memory:'],
            'plain' => ['url' => 'sqlite:///:memory:'],
        ],
    ],
]);
```

```php
$container->extension('rds_auth', [
    'connections' => ['covered'],
]);
```

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

### Querying the current user

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/dbal-parameters.md

Demonstrates how the current user reflects the modified connection parameters after the middleware has processed the configuration.

```php
$connection = $doctrine->getConnection();
$user = $connection->fetchOne('SELECT current_user');

// In IAM mode, current_user is the iam_username from config
// In static mode, current_user is the user from config
```

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

### Execute Database Queries

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/examples-and-recipes.md

Standard Doctrine DBAL usage remains unchanged as the bundle handles authentication automatically.

```php
class ProductRepository
{
    public function __construct(
        private Connection $connection,
    ) {}

    public function findAll(): array
    {
        return $this->connection->fetchAllAssociative(
            'SELECT * FROM products'
        );
    }
}
```

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

### Cache Pool Not Found Error

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/installation.md

Occurs when the configured cache pool is missing or not enabled.

```text
The cache pool "cache.app" does not exist
```

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

### Configure Doctrine DBAL for RDS

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/examples-and-recipes.md

Set up the Doctrine connection to use the RDS Auth Bundle credentials.

```yaml
doctrine:
    dbal:
        driver: pdo_pgsql
        host: '%env(RDS_HOST)%'
        port: '%env(int:RDS_PORT)%'
        dbname: '%env(RDS_DATABASE)%'
        user: app  # Will be overridden by iam_username
        password: dummy  # Will be overridden by IAM token
        sslmode: require
        charset: utf8
```

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

### Verify Targeted Middleware Application

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/middleware-integration.md

Demonstrates that only specified connections are wrapped in RdsAuthDriver, while others remain unchanged.

```php
$primary = $registry->getConnection('primary');
$primaryDriver = $primary->getDriver(); // Wrapped in RdsAuthDriver

$cache = $registry->getConnection('cache');
$cacheDriver = $cache->getDriver(); // NOT wrapped; uses configured driver
```

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

### Service Not Available Error

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/installation.md

Occurs when the bundle's services are not loaded into the container.

```text
Service "rds_auth.middleware" not found
```

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

### Configure IAM Authentication for Production

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/configuration.md

Uses AWS IAM for database authentication. Requires setting up a cache pool for credentials and configuring Doctrine to use the RDS host.

```yaml
# config/packages/rds_auth.yaml
rds_auth:
    region: '%env(AWS_REGION)%'
    iam_username: '%env(RDS_IAM_USERNAME)%'
    cache_pool: rds_credentials
    connections: []

# config/packages/doctrine.yaml
doctrine:
    dbal:
        driver: pdo_pgsql
        host: '%env(RDS_HOST)%'
        port: '%env(int:RDS_PORT)%'
        dbname: '%env(RDS_DATABASE)%'
        user: '%env(RDS_USERNAME)%'  # Ignored when iam_username is set
        password: '%env(RDS_PASSWORD)%'  # Ignored when iam_username is set
        sslmode: require

# config/packages/cache.yaml
framework:
    cache:
        pools:
            rds_credentials:
                adapter: cache.adapter.apcu

# .env.prod
AWS_REGION=us-west-2
RDS_HOST=db.example.com
RDS_PORT=5432
RDS_DATABASE=myapp
RDS_IAM_USERNAME=app_user
# Leave RDS_USERNAME and RDS_PASSWORD unset or empty
```

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

### Configure Environment Variable Defaults

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/configuration.md

Uses the default:: processor to allow environment variables to resolve to null when unset.

```yaml
iam_username: '%env(default::RDS_IAM_USERNAME)%'
secret_arn: '%env(default::RDS_SECRET_ARN)%'
cache_pool: 'cache.app'  # Not an env var; a service id
```

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

### Configure Local Development Environment

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/configuration.md

Disables dynamic authentication for local development. The middleware remains registered but defaults to static credentials.

```yaml
# config/packages/rds_auth.yaml (or omit it entirely)
rds_auth:
    region: '%env(AWS_REGION)%'
    # iam_username and secret_arn remain null

# config/packages/doctrine.yaml
doctrine:
    dbal:
        driver: pdo_pgsql
        host: '%env(DB_HOST)%'
        dbname: '%env(DB_NAME)%'
        user: '%env(DB_USER)%'
        password: '%env(DB_PASSWORD)%'

# .env.local
AWS_REGION=us-west-2
DB_HOST=localhost
DB_NAME=myapp
DB_USER=myuser
DB_PASSWORD=localpassword
```

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

### Import CacheItemPoolInterface

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/types-and-imports.md

Interface for PSR-6 cache pools, often used in middleware constructors.

```php
use Psr\Cache\CacheItemPoolInterface;
```

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

### Verify APCu Configuration

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/cache-behavior.md

Command to verify that APCu is enabled and CLI support is active.

```bash
$ php -i | grep -A 5 "apc"
```

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

### Tagging Doctrine Middleware for All Connections

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/bundle-class.md

Applies the middleware to all DBAL connections when the connections configuration is empty.

```php
$middleware->tag('doctrine.middleware');
```

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

### Retrieve a Service

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/testing-guide.md

Retrieves a service from the container for state assertions.

```php
$service = self::getContainer()->get('service_id');
```

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

### Configure Middleware for All Connections

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/middleware-integration.md

YAML configuration to enable the RDS auth middleware for every configured DBAL connection.

```yaml
rds_auth:
    connections: []
```

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

### Configure Doctrine DBAL

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/middleware-integration.md

Standard Doctrine DBAL configuration using environment variables for RDS connection parameters.

```yaml
doctrine:
    dbal:
        driver: pdo_pgsql
        host: '%env(RDS_HOST)%'
        port: '%env(int:RDS_PORT)%'
        dbname: '%env(RDS_DATABASE)%'
        user: '%env(RDS_USERNAME)%'
        password: '%env(RDS_PASSWORD)%'
        sslmode: require
```

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

### Doctrine Multi-Connection Configuration

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/examples-and-recipes.md

Configure multiple database connections in Doctrine, specifying different drivers and authentication strategies for each.

```yaml
doctrine:
    dbal:
        default_connection: default
        connections:
            default:
                driver: pdo_pgsql
                host: '%env(RDS_HOST)%'
                port: '%env(int:RDS_PORT)%'
                dbname: '%env(RDS_DATABASE)%'
                user: app
                password: dummy
                sslmode: require
            legacy:
                driver: pdo_mysql
                host: '%env(LEGACY_HOST)%'
                port: 3306
                dbname: '%env(LEGACY_DATABASE)%'
                user: '%env(LEGACY_USER)%'
                password: '%env(LEGACY_PASSWORD)%'
            cache:
                driver: pdo_sqlite
                path: '%kernel.cache_dir%/cache.db'
```

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

### Create IAM-enabled Database User

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/examples-and-recipes.md

SQL commands to create a PostgreSQL user with IAM authentication privileges.

```sql
-- PostgreSQL
CREATE USER app WITH PASSWORD 'any_password_required_for_login_but_not_used';
GRANT rds_iam TO app;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO app;
```

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

### Enable APCu in PHP

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/installation.md

Configuration settings for APCu in php.ini.

```ini
# php.ini or /etc/php/8.4/cli/conf.d/20-apcu.ini
[apc]
apc.enabled = 1
apc.enable_cli = 1
apc.shm_size = 256M
apc.max_file_size = 10M
```

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

### Define Bundle Configuration Schema

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/types-and-imports.md

Inferred schema for the bundle configuration tree.

```php
type BundleConfiguration = {
    region: string,              // Non-empty string
    iam_username: string | null, // Nullable string
    secret_arn: string | null,   // Nullable string
    cache_pool: string | null,   // Nullable string (service id)
    connections: string[],       // Array of connection names
};
```

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

### View IAM Middleware Parameter Transformation

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/dbal-parameters.md

The resulting connection parameters after the middleware applies IAM authentication settings.

```text
driver: pdo_pgsql              # Unchanged
host: prod-db.example.com      # Unchanged
port: 5432                     # Unchanged
dbname: production             # Unchanged
user: app_iam                  # Modified
password: (RDS IAM token)      # Modified
sslmode: require               # Modified (was prefer)
charset: utf8mb4               # Unchanged
```

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

### Configure Doctrine DBAL for PostgreSQL

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/installation.md

Standard Doctrine DBAL configuration for PostgreSQL using environment variables.

```yaml
# config/packages/doctrine.yaml
doctrine:
    dbal:
        driver: pdo_pgsql
        host: '%env(RDS_HOST)%'
        port: '%env(int:RDS_PORT)%'
        dbname: '%env(RDS_DATABASE)%'
        user: '%env(RDS_USERNAME)%'
        password: '%env(RDS_PASSWORD)%'
        sslmode: require
        server_version: '%env(RDS_SERVER_VERSION)%'
```

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

### Import ArrayNodeDefinition

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/types-and-imports.md

Used to define associative array nodes within the configuration tree.

```php
use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
```

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

### Authentication Mode Selection Logic

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/credential-modes.md

The middleware evaluates credentials at connection time, prioritizing IAM authentication if the username is provided.

```text
if iam_username is set and non-empty:
    use RDS IAM authentication (Mode 1)
else if secret_arn is set and non-empty:
    use master-password refresh (Mode 2)
else:
    use parameters as configured (Mode 3)
```

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

### IAM Authentication Environment Variables

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/docs/configuration.md

Environment variables required to enable IAM authentication without modifying the configuration file.

```bash
AWS_REGION=ap-southeast-2
RDS_IAM_USERNAME=app_user
```

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

### Configure NoCacheTestKernel

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/testing-guide.md

Doctrine and RDS Auth configuration for testing disabled caching.

```php
$container->extension('doctrine', [
    'dbal' => ['url' => 'sqlite:///:memory:'],
]);
```

```php
$container->extension('rds_auth', [
    'cache_pool' => null,
]);
```

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

### Instantiate rds_auth.middleware

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/services.md

Service definition for the RdsAuthMiddleware, which requires token and password providers along with configuration parameters.

```php
$middleware = $services->set('rds_auth.middleware', RdsAuthMiddleware::class)
    ->args([
        service('rds_auth.token_provider'),
        service('rds_auth.password_provider'),
        $config['iam_username'],
        $config['secret_arn'],
        null !== $pool && '' !== $pool ? service($pool) : null,
    ])
;
```

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

### Enable IAM Authentication in PostgreSQL

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/credential-modes.md

SQL command to grant IAM authentication privileges to a database user.

```sql
GRANT rds_iam TO app_user;
```

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

### Usage with Doctrine Connection

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/examples-and-recipes.md

The bundle automatically handles password rotation retries without requiring changes to existing service logic.

```php
class UserService
{
    public function __construct(
        private Connection $connection,
    ) {}

    public function getCount(): int
    {
        // Works before, during, and after secret rotation
        return $this->connection->fetchOne('SELECT COUNT(*) FROM users');
    }
}
```

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

### Configure charset

Source: https://github.com/tacticmedia/rds-auth-bundle/blob/main/_autodocs/dbal-parameters.md

The character set parameter remains unchanged.

```yaml
doctrine:
    dbal:
        charset: utf8mb4

# Remains utf8mb4 in all modes
```