===============
LIBRARY RULES
===============
From library maintainers:
- Symfony applications should install tacticmedia/rds-auth-bundle instead of wiring this middleware manually
- Requires PHP 8.3 or later and doctrine/dbal 4
- Pass a shared PSR-6 cache pool in production; without one every connection signs a new IAM token
- MySQL IAM authentication requires PDO::MYSQL_ATTR_SSL_CA in driverOptions; RDS refuses IAM logins without TLS
- To learn that the deployed password is outdated, pass a PSR-14 dispatcher as the last RdsAuthMiddleware argument and listen for ConfiguredPasswordOutdated

### Install the package

Source: https://github.com/tacticmedia/rds-auth-middleware/blob/main/docs/getting-started.md

Use Composer to add the dependency to your project.

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

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

### Start integration test services

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

Launch the required Docker containers for integration tests using the integration profile.

```bash
docker compose --profile integration up -d --wait postgres mysql moto
composer test:integration
```

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

### Install RDS Auth Middleware

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

Use Composer to add the package to your project dependencies.

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

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

### Configure RdsAuthMiddleware for Managed Passwords

Source: https://github.com/tacticmedia/rds-auth-middleware/blob/main/docs/managed-password.md

Setup the middleware with the secret ARN and a cache pool to handle automatic password rotation.

```php
use Doctrine\DBAL\Configuration;
use Doctrine\DBAL\DriverManager;
use TacticMedia\RdsAuth\RdsAuthMiddleware;
use TacticMedia\RdsAuth\RdsIamTokenProvider;
use TacticMedia\RdsAuth\RdsSecretPasswordProvider;

$middleware = new RdsAuthMiddleware(
    new RdsIamTokenProvider('ap-southeast-2'),
    new RdsSecretPasswordProvider('ap-southeast-2'),
    null,
    'arn:aws:secretsmanager:ap-southeast-2:123456789012:secret:rds!db-abc123',
    $cachePool,
);

$configuration = new Configuration();
$configuration->setMiddlewares([$middleware]);

$connection = DriverManager::getConnection([
    'driver' => 'pdo_pgsql',
    'host' => 'mydb.abc123.ap-southeast-2.rds.amazonaws.com',
    'dbname' => 'app',
    'user' => 'postgres',
    'password' => getenv('DB_PASSWORD'),   // the possibly stale deployed password
], $configuration);
```

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

### Initialize RdsAuthMiddleware with an event dispatcher

Source: https://github.com/tacticmedia/rds-auth-middleware/blob/main/docs/managed-password.md

Pass the event dispatcher as the final argument to the RdsAuthMiddleware constructor.

```php
$middleware = new RdsAuthMiddleware(
    new RdsIamTokenProvider('ap-southeast-2'),
    new RdsSecretPasswordProvider('ap-southeast-2'),
    null,
    'arn:aws:secretsmanager:ap-southeast-2:123456789012:secret:rds!db-abc123',
    $cachePool,
    new OutdatedPasswordAlerter(),
);
```

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

### Run development and testing commands

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

Execute these commands via Composer to run the test suites or the full quality assurance pipeline.

```bash
composer test               # PHPUnit unit suite
composer test:integration   # PHPUnit integration suite, needs Docker services
composer qa                 # rector, cs, stan, test in sequence
```

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

### Run project test and quality assurance commands

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

Use these Composer scripts to execute the test suite, static analysis, and code style fixes.

```bash
composer install
composer test                 # unit suite (default PHPUnit suite)
composer test:integration     # integration suite, needs the Docker services below
composer stan                 # PHPStan level 8 over src and tests
composer cs                   # php-cs-fixer fix
composer rector               # rector
composer qa                   # rector, cs, stan, test in sequence
composer coverage             # HTML and Clover reports in coverage/
```

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

### Configure the middleware

Source: https://github.com/tacticmedia/rds-auth-middleware/blob/main/docs/getting-started.md

Register the middleware with Doctrine DBAL by providing token and password providers. Ensure $cachePool is defined if caching is required.

```php
use Doctrine\DBAL\Configuration;
use Doctrine\DBAL\DriverManager;
use TacticMedia\RdsAuth\RdsAuthMiddleware;
use TacticMedia\RdsAuth\RdsIamTokenProvider;
use TacticMedia\RdsAuth\RdsSecretPasswordProvider;

$region = getenv('AWS_REGION') ?: 'us-east-1';

$middleware = new RdsAuthMiddleware(
    new RdsIamTokenProvider($region),
    new RdsSecretPasswordProvider($region),
    getenv('RDS_IAM_USERNAME') ?: null,          // null disables the IAM path
    getenv('RDS_SECRET_ARN') ?: null,            // null disables the refresh path
    $cachePool,                                  // any PSR-6 pool; omit to disable caching
);

$configuration = new Configuration();
$configuration->setMiddlewares([$middleware]);

$connection = DriverManager::getConnection($params, $configuration);
```

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

### Configure RDS Auth Middleware

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

Initialize the middleware with IAM and Secret providers, then register it with the Doctrine DBAL configuration.

```php
use Doctrine\DBAL\Configuration;
use Doctrine\DBAL\DriverManager;
use TacticMedia\RdsAuth\RdsAuthMiddleware;
use TacticMedia\RdsAuth\RdsIamTokenProvider;
use TacticMedia\RdsAuth\RdsSecretPasswordProvider;

$region = getenv('AWS_REGION') ?: 'us-east-1';

$middleware = new RdsAuthMiddleware(
    new RdsIamTokenProvider($region),
    new RdsSecretPasswordProvider($region),
    getenv('RDS_IAM_USERNAME') ?: null,          // null disables the IAM path
    getenv('RDS_SECRET_ARN') ?: null,            // null disables the refresh path
    $cachePool,                                  // any PSR-6 pool; omit to disable caching
);

$configuration = new Configuration();
$configuration->setMiddlewares([$middleware]);

$connection = DriverManager::getConnection($params, $configuration);
```

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

### Initialize APCu Cache Pool

Source: https://github.com/tacticmedia/rds-auth-middleware/blob/main/docs/caching.md

Configure an APCu adapter to share credentials across workers on the same host.

```php
use Symfony\
Component\\Cache\\Adapter\\ApcuAdapter;

$cachePool = new ApcuAdapter('rds_auth');
```

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

### Configure RdsAuthMiddleware for IAM Authentication

Source: https://github.com/tacticmedia/rds-auth-middleware/blob/main/docs/iam-authentication.md

Initializes the middleware with an IAM token provider and secret password provider, then attaches it to the Doctrine DBAL configuration.

```php
use Doctrine\DBAL\Configuration;
use Doctrine\DBAL\DriverManager;
use TacticMedia\RdsAuth\RdsAuthMiddleware;
use TacticMedia\RdsAuth\RdsIamTokenProvider;
use TacticMedia\RdsAuth\RdsSecretPasswordProvider;

$middleware = new RdsAuthMiddleware(
    new RdsIamTokenProvider('ap-southeast-2'),
    new RdsSecretPasswordProvider('ap-southeast-2'),
    'app_user',      // database user with IAM authentication enabled
    null,
    $cachePool,
);

$configuration = new Configuration();
$configuration->setMiddlewares([$middleware]);

$connection = DriverManager::getConnection([
    'driver' => 'pdo_pgsql',
    'host' => 'mydb.abc123.ap-southeast-2.rds.amazonaws.com',
    'dbname' => 'app',
], $configuration);
```

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

### Configure Database User for IAM Authentication

Source: https://github.com/tacticmedia/rds-auth-middleware/blob/main/docs/iam-authentication.md

SQL commands to enable IAM authentication for PostgreSQL and MySQL/MariaDB users.

```sql
CREATE USER app_user;
GRANT rds_iam TO app_user;
```

```sql
CREATE USER 'app_user'@'%' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
```

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

### Implement a PSR-14 event dispatcher

Source: https://github.com/tacticmedia/rds-auth-middleware/blob/main/docs/managed-password.md

A minimal PSR-14 dispatcher implementation to handle the ConfiguredPasswordOutdated event.

```php
use Psr\EventDispatcher\EventDispatcherInterface;
use TacticMedia\RdsAuth\ConfiguredPasswordOutdated;

final class OutdatedPasswordAlerter implements EventDispatcherInterface
{
    public function dispatch(object $event): object
    {
        if ($event instanceof ConfiguredPasswordOutdated) {
            error_log(sprintf(
                'Deployed database password is outdated: secret %s, host %s. Redeploy to reload it.',
                $event->secretArn,
                $event->host ?? 'unknown',
            ));
        }

        return $event;
    }
}
```

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

### Execute specific tests

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

Run individual test files or filter tests by name using PHPUnit directly.

```bash
vendor/bin/phpunit tests/RdsAuthDriverTest.php
vendor/bin/phpunit --filter testIamModeSwapsCredentials
```

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

### Generate IAM Token Standalone

Source: https://github.com/tacticmedia/rds-auth-middleware/blob/main/docs/iam-authentication.md

Uses RdsIamTokenGenerator to create a token manually for use as a database password.

```php
use TacticMedia\RdsAuth\RdsIamTokenGenerator;

$generator = new RdsIamTokenGenerator();
$token = $generator->createToken('mydb.abc123.ap-southeast-2.rds.amazonaws.com:5432', 'ap-southeast-2', 'app_user');
```

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

### Regenerate reference token fixtures

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

Update the reference token JSON file used by RdsIamTokenGeneratorReferenceTest.

```bash
php tests/fixtures/generate-reference-tokens.php
```

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

### Configure MySQL TLS for RDS IAM Authentication

Source: https://github.com/tacticmedia/rds-auth-middleware/blob/main/docs/database-engines.md

Sets the SSL CA certificate path in driver options to ensure RDS IAM authentication succeeds. Required because MySQL does not automatically configure TLS for IAM logins.

```php
$params['driverOptions'] = [\PDO::MYSQL_ATTR_SSL_CA => '/path/to/global-bundle.pem'];
```

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

### Define AWS IAM Policy for RDS Connect

Source: https://github.com/tacticmedia/rds-auth-middleware/blob/main/docs/iam-authentication.md

Required IAM policy to allow the rds-db:connect action for a specific database user.

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "rds-db:connect",
            "Resource": "arn:aws:rds-db:ap-southeast-2:123456789012:dbuser:db-ABCDEFGHIJKL/app_user"
        }
    ]
}
```

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

### RDS-managed secret JSON format

Source: https://github.com/tacticmedia/rds-auth-middleware/blob/main/docs/managed-password.md

The expected JSON structure for the secret stored in AWS Secrets Manager.

```json
{"username": "postgres", "password": "current-password"}
```

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

### IAM Policy for Secrets Manager Access

Source: https://github.com/tacticmedia/rds-auth-middleware/blob/main/docs/managed-password.md

Required IAM policy to allow the application to retrieve the secret value from AWS Secrets Manager.

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "secretsmanager:GetSecretValue",
            "Resource": "arn:aws:secretsmanager:ap-southeast-2:123456789012:secret:rds!db-abc123"
        }
    ]
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.