shaggy8871/yami

Yami 是一个 YAML 迁移工具

维护者

详细信息

github.com/shaggy8871/yami

源代码

问题

安装: 79

依赖: 0

建议者: 0

安全: 0

星标: 9

关注者: 1

分支: 3

开放问题: 0

类型：应用

v0.0.3 2020-07-21 19:10 UTC

Requires

Requires (Dev)

MIT 6098f74430cd8238c03908745bb703dcaf79e66f

  • J. Ginsberg <john.ginsberg.woop@tristadeca.com>

This package is auto-updated.

Last update: 2024-09-08 16:49:56 UTC

README

Build Status

Yami 是一个用于 YAML 文件的 PHP 迁移工具。它非常适合在源代码库之外维护 YAML 文件，例如用于凭据或秘密管理（如 .env 文件）。一些主要优点包括

  • 它维护一个或多个 YAML 文件更改的历史记录，并能够批量回滚或回滚到特定时间点。
  • 它关注 YAML 文件的结构而不是数据，并在迁移期间允许从多个来源注入数据，包括秘密管理器或环境变量。
  • 它非常适合 CI 系统，可以作为测试或部署期间更大工作流程的一部分实现。
  • 编写迁移非常简单，不需要额外的技能或使用命令行工具。

目录

  1. 安装
  2. 入门
  3. 创建迁移
  4. 运行迁移
  5. 回滚
  6. 配置选项
  7. 保护数据
  8. 命令行选项

安装

在 composer.json 中

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/shaggy8871/php-diff"
    }
  ],
  "require": {
    "shaggy8871/yami": "dev-master"
  },
  "minimum-stability": "dev"
}

然后运行

composer install

入门

从您的命令行运行 vendor/bin/yami config 创建一个配置文件。将创建一个基本配置脚本，如下所示。

<?php

return [
    'environments' => [
        'default' => [
            'yaml' => [
                'adapter' => 'file',
                'file' => 'default.yaml',
            ],
            'migrations' => [
                'path' => './migrations',
            ],
        ],
    ],
    'save' => [
        'indentation' => 2,
    ]
];

配置文件支持一个或多个环境。一个环境至少需要两个键

  • yaml.adapter - 要使用的适配器类型。有关其他选项，请参阅下面的 YAML 适配器。
  • yaml.file - YAML 文件的路径，相对于 Yami 安装根目录。
  • migrations.path - migrations 目录的路径，相对于 Yami 安装根目录。

以下概述了其他配置选项。

如果您没有为迁移创建目录，可以按照以下方式创建

mkdir migrations

创建迁移

要创建迁移脚本，运行

vendor/bin/yami create --migration=TestMigration -e default

migration 参数是必需的，应该使用驼峰式命名来描述您的迁移。Yami 将在环境指定的 path 中创建迁移脚本。使用 -e default 参数指定要使用哪个环境的设置。如果没有指定环境，将使用配置脚本中找到的第一个环境作为默认值。

一个基本的迁移脚本如下所示

<?php

use Yami\Migration\AbstractMigration;

class TestMigration extends AbstractMigration
{

    public function up()
    {
        $node = $this->get('.');
        $node->add(['foo' => 'bar']);

        $this->save();
    }

    public function down()
    {
        $node = $this->get('.');
        $node->remove('foo');

        $this->save();
    }

}

up() 方法在迁移时调用。在回滚时调用 down() 方法。

每个迁移都遵循一系列简单的步骤

  1. 找到基本节点。
  2. 对内容进行更改。

一旦您完成了节点的操作，请调用 $this->save() 将更改保存回文件。如果设置了 --dry-run 标志，则更改将输出到屏幕，但不会写入文件。

迁移方法

$this->get()

《$this->get()` 方法期望一个遵循原始 jq 风格格式化的搜索字符串。最基本的搜索是 .，它代表 YAML 文件的根。调用 $this->get('.') 将允许您操作整个 YAML 文件。此搜索仅应在向 YAML 文件底部添加节点时使用。

在根节点中搜索特定元素可以通过在 '.' 后立即指定节点名称来完成。如果您的 YAML 文件如下所示

foo:
  bar: baz

您可以通过调用 $this->get('.foo') 来访问和操作 foo 的内容。同样，您可以通过调用 $this->get('.foo.bar') 来访问 foo > bar 节点。

要在数组中搜索特定元素，请在 [] 方括号中添加数组索引。例如，要访问名为 foo > bar 的数组的第一个元素，请调用 $this->get('.foo.bar.[0])。

一旦您有一个节点，您可以对它执行一个或多个操作。

$this->exists()

使用 $this->exists() 来测试节点是否存在于树中，在尝试对其进行操作之前。此函数接受与 $this->get() 相同的参数。如果您尝试对不存在的树元素执行节点操作，它将失败。

$this->save()

一旦您对节点进行了所有必要的更改，请调用 $this->save() 以将更改保存回树。如果迁移中的任何步骤失败，则不会写入任何更改。

如果您打算操作另一个节点，则无需调用 $this->save()。只需简单调用 $this->get()，之前的节点将自动保存回树。

节点方法

$node->add()

《add()` 方法允许您向现有节点或 YAML 文件的根添加内容。如果您尝试向标量值追加值，则不能使用 add()。因此，使用上面的示例 YAML，这将有效

$node = $this->get('.');
$node->add(['foo' => 'bar']);

但这不会

$node = $this->get('.foo.bar');
$node->add(['new' => 'value']);

这是因为 foo > bar 包含一个标量字符串值 baz，它不能转换为数组。

add() 方法支持添加标量值或键/值对数组。如果提供标量值，它将被添加为数组元素。如果添加键/值对，它将被添加为映射元素。

$node->set()

《set()` 方法允许您覆盖节点的全部内容。请注意，这可能会从节点中删除整个树。不应在根节点 . 上使用 set() 方法，因为它将用指定的任何值替换整个 YAML 文件。

$node->remove()

《remove()` 方法将从一个或多个映射或元素中删除节点。您可以传递单个键作为字符串，例如 $node->remove('bar') 或要删除多个子节点的键数组，例如 $node->remove(['bar', 'baz'])。在具有数组值的节点上调用 remove() 将根据名称从数组中删除指定的值。

$node->has()

如果节点包含具有指定名称的子节点，则返回 true。例如 $node->has('foo')。

$node->containsArray()

与 has() 相同，但还检查子节点是否为数组。使用 $node->containsArray('foo')。

$node->containsType()

与 has() 相同，但还验证标量内容的类型。用法为 $node->containsType('foo', 'string')。有效类型包括 integer、string、float 和 boolean。

$node->dump()

将节点的内容输出到 stdout。

运行迁移

要测试迁移而不覆盖 YAML 文件，请运行 vendor/bin/yami migrate --dry-run。

要提交和保存迁移，请运行 vendor/bin/yami migrate。

注意：如果您没有使用--env=<环境>或-e <环境>参数指定环境，将使用默认环境，这可能不是您期望的。

回滚

如果您需要回滚迁移，请运行vendor/bin/yami rollback。您可以可选地传递--dry-run参数来查看结果而无需提交更改。

如果没有指定其他参数，Yami将回滚最后一批更改。

步骤

要指定要回滚的特定迁移数，请使用--step=X或-s X参数。例如vendor/bin/yami rollback -s 1将只回滚一个迁移。

目标

要回滚到特定的目标迁移，请使用--target=X或-t X参数。例如vendor/bin/yami rollback -t 2020_04_03_001122_test_migration将回滚到并包括此迁移，但不进一步。

配置选项

以下配置选项可以添加到您的配置文件中以自定义Yami的行为。

您也可以在特定环境中添加这些配置选项以自定义每个环境的操作方式。例如

<?php

return [
    'environments' => [
        /**
         * The development.yaml file may be committed if it's masked
         */
        'development' => [
            'yaml' => [
                'adapter' => 'file',
                'file' => 'development.yaml',
            ],
            'migrations' => [
                'path' => './migrations',
            ],
            'save' => [
                'maskValues' => true,
                'indentation' => 4,
            ]
        ],
        /**
         * The production.yaml file is not masked, so should not be committed
         */
        'production' => [
            'yaml' => [
                'adapter' => 'file',
                'file' => 'production.yaml',
            ],
            'migrations' => [
                'path' => './migrations',
            ],
        ]
    ],
    'save' => [
        'indentation' => 2,
    ]
];

当使用该环境时，特定环境的值将覆盖一般配置值。

自定义配置文件

要支持多个项目，您可以设置多个配置文件。要使用默认配置文件以外的配置文件，只需使用--config=<文件>或-c <文件>参数传递它。例如

vendor/bin/yami migrate -c ./projects/api/config.php

将使用此配置文件中指定的默认环境运行迁移。

YAML 适配器

默认情况下，Yami将在本地文件系统中查找您的YAML文件。适配器file需要一个指向磁盘上YAML文件位置的文件名。

以下适配器是原生支持的。您也可以通过实现Yami\Yaml\YamlAdapterInterface接口并通过yaml.adapter参数指向完全限定的类名来配置自己的适配器。

保护数据

为了确保凭据和其他敏感数据的安全，Yami引入了两个互补的功能。

秘密

不是将值硬编码到迁移中，这可能导致意外出现在源代码库中，Yami可以在运行迁移时查找它们。

密钥可以从第三方密钥管理系统提取，或者通过环境变量传递。

在运行迁移之前，将验证密钥，如果提供的数据与预期不符，则将失败。

要配置密钥管理系统，在适当的环境中添加以下内容到您的配置文件中

<?php

return [
    'environments' => [
        'default' => [
            'yaml' => [
                'adapter' => 'file',
                'file' => 'default.yaml',
            ],
            'migrations' => [
                'path' => './migrations',
            ],
            'secretsManager' => [
                'adapter' => 'ssm',
                'credentials' => [
                    'profile' => 'default',
                    'region' => 'us-east-1'
                ]
            ]
        ]
    ]
];

目前仅支持local（使用环境变量）和ssm（使用AWS SSM）适配器作为原生。如果没有指定密钥管理系统，则默认为local。使用SSM需要安装AWS SDK for PHP。

如果您更喜欢编写自己的密钥管理系统类，它必须实现Yami\Secrets\SecretsManagerInterface接口，并且完全限定的类名应通过secretsManager.adapter参数传递。

<?php

use Yami\Migration\AbstractMigration;

class TestClass extends AbstractMigration
{
    public function up()
    {
        $node = $this->get('.');
        $node->add([
            'foo' => 'bar',
            'access_key_id' => $this->secret('/api/production/s3/access_key_id', [
                'type' => 'string'
            ]),
            'secret_access_key' => $this->secret('/api/production/s3/secret_access_key', [
                'type' => 'string'
            ])
        ]);

        $this->save();
    }
}

密钥名称将被归一化到有效的环境变量，因此/api/production/s3/secret_key_id将寻找一个名为api_production_s3_SecretKeyId的环境变量。

在运行迁移时，可以通过以下方式通过命令行传递环境变量

export api_production_s3_AccessKeyId=<value>
export api_production_s3_SecretAccessKey=<value>
vendor/bin/yami migrate

掩码值

迁移不需要实际的值来运行，因为它们主要关注文件的结构。为了允许开发者测试迁移而不暴露敏感数据，Yami允许您屏蔽值。

已经提供了一个工具来屏蔽现有YAML文件中的所有值。只需调用

vendor/bin/yami mask

您可以选择传递 -c 和 -e 参数来相应地自定义配置文件和环境。

在屏蔽之前，原始文件将在同一位置进行备份，以防您需要恢复数据。

屏蔽后的 YAML 文件是安全的，可以提交。未屏蔽的 YAML 文件绝对不应该提交到源代码仓库。

为了确保在迁移后更改仍然被屏蔽，请使用 maskValues 配置选项。

命令行选项