如何配置和使用 Flex 私有 Recipe 仓库

编辑此页

自从 symfony/cli 1.16 版本发布以来，你可以构建自己的私有 Symfony Flex recipe 仓库，并无缝地将其集成到 composer 包的安装和维护过程中。

当你拥有必须执行自己安装任务的私有 bundles 或 packages 时，这尤其有用。为此，你需要完成以下几个步骤

  • 创建一个私有仓库；
  • 创建你的私有 recipes；
  • 为 recipes 创建索引；
  • 将你的 recipes 存储在私有仓库中；
  • 授权 composer 访问私有仓库；
  • 配置你的项目的 composer.json 文件；以及
  • 在你的项目中安装 recipes。

创建一个私有仓库

GitHub

登录你的 GitHub.com 账户，点击右上角的账户图标，并选择 Your Repositories（你的仓库）。然后点击 New（新建）按钮，填写 repository name（仓库名称），选择 Private（私有）单选按钮，然后点击 Create Repository（创建仓库）按钮。

Gitlab

登录你的 Gitlab.com 账户，点击 New project（新建项目）按钮，选择 Create blank project（创建空白项目），填写 Project name（项目名称），选择 Private（私有）单选按钮，然后点击 Create project（创建项目）按钮。

创建你的私有 Recipes

symfony/flex recipe 是一个 JSON 文件，它具有以下结构

1
2
3
4
5
6
7
8
9
{
    "manifests": {
        "acme/package-name": {
            "manifest": {
            },
            "ref": "7405f3af1312d1f9121afed4dddef636c6c7ff00"
        }
    }
}

如果你的 package 是一个私有 Symfony bundle，你的 recipe 中将包含以下内容

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "manifests": {
        "acme/private-bundle": {
            "manifest": {
                "bundles": {
                    "Acme\\PrivateBundle\\AcmePrivateBundle": [
                        "all"
                    ]
                }
            },
            "ref": "7405f3af1312d1f9121afed4dddef636c6c7ff00"
        }
    }
}

将 acme 和 private-bundle 替换为你自己的私有 bundle 详细信息。"ref" 条目是一个随机的 40 个字符的字符串，composer 使用它来确定你的 recipe 是否被修改。每次你更改你的 recipe 时，你还需要生成一个新的 "ref" 值。

提示

使用以下 PHP 脚本生成一个随机的 "ref" 值

1
echo bin2hex(random_bytes(20));

"all" 条目告诉 symfony/flex 为所有环境在你的项目的 bundles.php 文件中创建一个条目。要仅为 dev 环境加载你的 bundle，请将 "all" 替换为 "dev"。

你的 recipe JSON 文件的名称必须符合以下约定，其中 1.0 是你的 bundle 的版本号（将 acme 和 private-bundle 替换为你自己的私有 bundle 或 package 详细信息）

acme.private-bundle.1.0.json

你可能还需要 symfony/flex 在项目的 /config/packages 目录中为你的 bundle 或 package 创建配置文件。为此，请按如下方式更改 recipe JSON 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
    "manifests": {
        "acme/private-bundle": {
            "manifest": {
                "bundles": {
                    "Acme\\PrivateBundle\\AcmePrivateBundle": [
                        "all"
                    ]
                },
                "copy-from-recipe": {
                    "config/": "%CONFIG_DIR%"
                }
            },
            "files": {
                "config/packages/acme_private.yaml": {
                    "contents": [
                        "acme_private:",
                        "    encode: true",
                        ""
                    ],
                    "executable": false
                }
            },
            "ref": "7405f3af1312d1f9121afed4dddef636c6c7ff00"
        }
    }
}

有关你可以在 recipe 文件中包含的内容的更多示例，请浏览 Symfony recipe 文件。

为 Recipes 创建索引

下一步是创建一个 index.json 文件，它将包含你所有私有 recipes 的条目，以及其他常规配置信息。

GitHub

index.json 文件具有以下格式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "recipes": {
        "acme/private-bundle": [
            "1.0"
        ]
    },
    "branch": "main",
    "is_contrib": true,
    "_links": {
        "repository": "github.com/your-github-account-name/your-recipes-repository",
        "origin_template": "{package}:{version}@github.com/your-github-account-name/your-recipes-repository:main",
        "recipe_template": "https://api.github.com/repos/your-github-account-name/your-recipes-repository/contents/{package_dotted}.{version}.json"
    }
}

在 "recipes" 中为你的每个 bundle recipe 创建一个条目。将 your-github-account-name 和 your-recipes-repository 替换为你自己的详细信息。

Gitlab

index.json 文件具有以下格式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "recipes": {
        "acme/private-bundle": [
            "1.0"
        ]
    },
    "branch": "main",
    "is_contrib": true,
    "_links": {
        "repository": "gitlab.com/your-gitlab-account-name/your-recipes-repository",
        "origin_template": "{package}:{version}@gitlab.com/your-gitlab-account-name/your-recipes-repository:main",
        "recipe_template": "https://gitlab.com/api/v4/projects/your-gitlab-project-id/repository/files/{package_dotted}.{version}.json/raw?ref=main"
    }
}

在 "recipes" 中为你的每个 bundle recipe 创建一个条目。将 your-gitlab-account-name、your-gitlab-repository 和 your-gitlab-project-id 替换为你自己的详细信息。

将你的 Recipes 存储在私有仓库中

将 recipe .json 文件和 index.json 文件上传到你的私有仓库的根目录中。

授权 composer 访问私有仓库

GitHub

在你的 GitHub 账户中，点击右上角的账户图标，选择 Settings（设置）和 Developer Settings（开发者设置）。然后选择 Personal Access Tokens（个人访问令牌）。

生成一个新的访问令牌，并具有 Full control of private repositories（完全控制私有仓库）权限。复制访问令牌值，切换到你的本地计算机的终端，并执行以下命令

1
$ composer config --global --auth github-oauth.github.com [token]

将 [token] 替换为你的 GitHub 个人访问令牌的值。

Gitlab

在你的 Gitlab 账户中，点击右上角的账户图标，选择 Preferences（偏好设置）和 Access Tokens（访问令牌）。

生成一个新的个人访问令牌，并具有 read_api 和 read_repository 作用域。复制访问令牌值，切换到你的本地计算机的终端，并执行以下命令

1
$ composer config --global --auth gitlab-token.gitlab.com [token]

将 [token] 替换为你的 Gitlab 个人访问令牌的值。

配置你的项目的 composer.json 文件

GitHub

将以下内容添加到你的项目的 composer.json 文件中

1
2
3
4
5
6
7
8
9
10
{
    "extra": {
        "symfony": {
            "endpoint": [
                "https://api.github.com/repos/your-github-account-name/your-recipes-repository/contents/index.json",
                "flex://defaults"
            ]
        }
    }
}

将 your-github-account-name 和 your-recipes-repository 替换为你自己的详细信息。

提示

extra.symfony 键很可能已存在于你的 composer.json 中。在这种情况下，将 "endpoint" 键添加到现有的 extra.symfony 条目中。

提示

endpoint URL 必须指向 https://api.github.com/repos，而不是 https://www.github.com。

Gitlab

将以下内容添加到你的项目的 composer.json 文件中

1
2
3
4
5
6
7
8
9
10
{
    "extra": {
        "symfony": {
            "endpoint": [
                "https://gitlab.com/api/v4/projects/your-gitlab-project-id/repository/files/index.json/raw?ref=main",
                "flex://defaults"
            ]
        }
    }
}

将 your-gitlab-project-id 替换为你自己的详细信息。

提示

extra.symfony 键很可能已存在于你的 composer.json 中。在这种情况下，将 "endpoint" 键添加到现有的 extra.symfony 条目中。

在你的项目中安装 Recipes

如果你的私有 bundles/packages 尚未安装在你的项目中，请运行以下命令

1
$ composer update

如果私有 bundles/packages 已经安装，而你只想安装新的私有 recipes，请运行以下命令

1
$ composer recipes
本作品，包括代码示例，根据 Creative Commons BY-SA 3.0 许可获得许可。
目录
    版本