README

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

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参数存储，直接作为纯文本传递给凭证提供程序或其他来源。每个凭证提供程序都应提供一个唯一的数据库标识符、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 参数存储提供者

CEmerson\DBSafe\CredentialsProviders\AWSSSMParameterStoreCredentialsProvider

AWS参数存储不会像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')向记录器记录消息。

数据库工厂

数据库工厂负责使用从缓存或凭据提供者获取的凭据创建连接。它非常简单，只有一个方法——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'"
]);

自定义数据库工厂

你可以通过创建一个实现DBFactory接口的类来创建自定义数据库工厂。它只有一个需要实现的方法——一个从给定的DSN、用户名和密码返回数据库连接的方法。此方法必须在提供的凭据错误时抛出IncorrectCredentials异常，以便DBSafe的重试功能可以工作。

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