README

这个库最初是PDO Safe，一个用于使用AWS Parameter Store或AWS Secrets Manager与PDO的库。然而，随着时间的推移，它显然可以作为更通用的数据库工厂，允许从任何位置使用凭证创建任何类型的数据库。因此，它被重命名为DBSafe来反映这一点，尽管目前只包含PDO的工厂，并且仅支持从AWS Secrets Manager和AWS SSM Parameter Store获取凭证，以及一个简单的硬编码凭证提供程序，用于测试或迁移的便利性。

DBSafe将使用您连接到它的任何缓存来缓存您的凭证，以避免重复调用凭证存储。您可以指定凭证缓存的时长。此外，如果数据库连接失败，DBSafe将首先尝试从凭证存储中重新获取凭证，然后再次尝试连接，然后再失败。这允许在应用程序中断的情况下，外部滚动凭证并继续工作。

安装

使用composer将安装到您的项目中

composer require cemerson/dbsafe

快速开始

DBSafe类是主要的交互点。为了创建它，您需要传递给它一个PSR-6兼容的缓存池和一个PSR-3兼容的记录器。

$dbSafe = new DBSafe($cache, $logger);

一旦您有了这个对象，您需要为DBSafe在您的应用程序中管理的每个数据库连接设置一个凭证提供程序和DB工厂 - 虽然如果适当，这些可以由连接共享。

$credentialsProvider = new PlainTextCredentialsProvider(
    'mydb',
    'mysql:host=localhost;port=3306;dbname=mydb;charset=utf8',
    'username',
    'password'
);

$dbFactory = new PDODBFactory([
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    PDO::MYSQL_ATTR_INIT_COMMAND => "SET NAMES 'utf8'"
]);

一旦您有了凭证提供程序和DB工厂对象，您只需在DBSafe对象上调用getDB即可获取数据库连接。DBSafe将获取凭证，将其与您的缓存提供程序一起缓存，并返回由工厂返回的DB连接。

$dbConnection = $dbSafe->getDB($credentialsProvider, $dbFactory);

概念

这个库由凭证提供程序和工厂组成，本质上是通过缓存和日志将它们粘合在一起。您可以使用任何用户提供的凭证提供程序，任何用户提供的工厂，任何用户提供的PSR-6兼容缓存和任何PSR-3兼容记录器。一些凭证提供程序与库一起提供，用于与AWS服务一起使用，以及一个PDO工厂，因为我认为这将是最常见的用例。

凭证提供程序

凭证提供程序负责获取数据库凭证。这可能是从AWS服务如Secrets Manager、SSM Parameter Store，直接作为纯文本传递到凭证提供程序，或其他来源。每个凭证提供程序都应提供一个唯一标识符，一个DSN字符串，一个用户名和一个密码。有一个抽象类，它提供了一个帮助构造标准格式DSN字符串的方法。

所有凭证提供程序都接受一个唯一标识符作为它们的第一个参数。这必须在您的应用程序中是唯一的值，并且用于创建特定凭证的唯一缓存键。

这里描述了所有内置提供程序的使用。

纯文本提供程序

CEmerson\DBSafe\CredentialsProviders\PlainTextCredentialsProvider

这个非常简单 - 您只需将DSN、用户名和密码传递给提供程序，它就使用这些来创建数据库连接。如果您想在将DBSafe集成到现有项目中，同时仍然从本地源获取凭证以进行测试，或者用于本地开发，这是一个理想的选择。此提供程序不使用缓存。

AWS Secrets Manager提供程序

CEmerson\DBSafe\CredentialsProviders\AWSSecretsManagerCredentialsProvider

如果您的凭证存储在AWS Secrets Manager中，您可以使用此提供程序来获取它们。它需要唯一的标识符，然后是其他4个参数 - 来自AWS PHP SDK的AWS SecretsManagerClient，存储凭证的秘密名称，用于连接的字符集以及表示凭证缓存时间的DateInterval。

$credentialsProvider = new AWSSecretsManagerCredentialsProvider(
    $awsSecretsManagerClient,
    'my-db-credentials',
    'utf8',
    new DateInterval('P1D')
);

创建AWS客户端由用户自行决定，以便可以使用适当的版本和区域。此提供程序将从名为'my-db-credentials'的AWS Secrets Manager中获取凭证，将utf-8字符集作为DSN的一部分，并将凭证缓存1天。

AWS SSM Parameter Store Provider

CEmerson\DBSafe\CredentialsProviders\AWSSSMParameterStoreCredentialsProvider

AWS Parameter Store不像Secrets Manager那样一次性存储整个连接的详细信息，但DSN、用户名和密码需要作为单独的参数存储。此凭证提供程序接受唯一的标识符、AWS SSM客户端、DSN、用户名和密码的参数名称，以及最终缓存时间。

$credentialsProvider = new AWSSSMParameterStoreCredentialsProvider(
    $awsSSMClient,
    'my-other-db-credentials',
    'my-database-dsn',
    'my-database-username',
    'my-database-password',
    new DateInterval('PT1H')    
);

自定义提供程序

您可以通过创建一个实现CredentialsProvider接口的类来创建自定义提供程序，以便从其他地方获取凭证。如果获取凭证涉及到调用某个地方或其他只在凭证未缓存时才应该执行的任务，请确保仅在请求凭证时获取凭证，而不是在您的类构造函数中。

此接口还扩展了LoggerAwareInterface。您可以直接使用psr/log包中的LoggerAwareTrait，它将满足这里的所有要求。然后您可以使用（例如）$this->logger->info('message')将消息记录到记录器。

DB Factories

DB Factory负责使用从缓存或从凭证提供程序获取的凭证创建连接。它非常简单，只有一个方法 - getDB。

目前只包含了一个工厂，即PDODBFactory。

PDODBFactory

CEmerson\DBSafe\DBFactories\PDODBFactory

当您希望为应用程序使用PDO连接对象时，应使用此工厂。构造函数允许传入选项，这些选项将被传递给PDO对象构造函数。

$dbFactory = new PDODBFactory([
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    PDO::MYSQL_ATTR_INIT_COMMAND => "SET NAMES 'utf8'"
]);

自定义DB Factories

您可以通过创建一个实现DBFactory接口的类来自定义DB Factory。它只有一个需要实现的方法 - 从给定DSN、用户名和密码返回DB连接的方法。此方法必须抛出IncorrectCredentials异常，以便DBSafe的重试功能可以工作。

此接口还扩展了LoggerAwareInterface，可以通过简单地使用psr/log中的LoggerAwareTrait来满足。