处理私有包#

私有 Packagist#

私有 Packagist 是一款商业软件包托管产品，提供专业支持以及对私有和公共软件包的基于 Web 的管理，以及细粒度的访问权限。私有 Packagist 提供对软件包 zip 文件的镜像，这使得安装速度更快，并且独立于第三方系统 - 例如，即使 GitHub 出现故障，您也可以部署，因为您的 zip 文件已镜像。

私有 Packagist 作为托管的 SaaS 解决方案或内部部署的自托管软件包提供，提供交互式设置体验。

私有 Packagist 的部分收入用于支付 Composer 和 Packagist.org 的开发和托管费用，因此使用它是在财务上支持这些开源项目维护的良好方式。您可以在 Packagist.com 上找到有关如何设置自己的软件包存档的更多信息。

Satis#

另一方面，Satis 是开源的，但它只是一个静态的 composer 存储库生成器。它有点像 packagist 的超轻量级、静态文件版本，可用于托管公司私有包或您自己的包的元数据。您可以使用 Composer 或 Docker 安装它。

设置#

例如，假设您有一些想要在公司范围内重复使用的软件包，但不想开源它们。您首先需要定义一个 Satis 配置：一个 JSON 文件，其中列出了您精选的存储库。

默认文件名是 satis.json，但您可以随意命名。

以下是一个示例配置，您可以看到它包含一些 VCS 存储库，但它们可以是任何类型的存储库。然后它使用 "require-all": true，这将选择您在其中定义的存储库中所有软件包的所有版本。

Satis 默认情况下会查找存储库根目录中的 satis.json 文件。

{
    "name": "my/repository",
    "homepage": "http://packages.example.org",
    "repositories": [
        { "type": "vcs", "url": "https://github.com/mycompany/privaterepo" },
        { "type": "vcs", "url": "http://svn.example.org/private/repo" },
        { "type": "vcs", "url": "https://github.com/mycompany/privaterepo2" }
    ],
    "require-all": true
}

如果您想要挑选您想要的软件包，您可以在经典的 composer require 键中列出您想要在 satis 存储库中包含的所有软件包，使用 "*" 约束确保选择所有版本，或者使用其他约束如果您想要非常具体的版本。

{
    "repositories": [
        { "type": "vcs", "url": "https://github.com/mycompany/privaterepo" },
        { "type": "vcs", "url": "http://svn.example.org/private/repo" },
        { "type": "vcs", "url": "https://github.com/mycompany/privaterepo2" }
    ],
    "require": {
        "company/package": "*",
        "company/package2": "*",
        "company/package3": "2.0.0"
    }
}

完成此操作后，运行

php bin/satis build <configuration file> <build dir>

在完善了该流程后，您通常会将此命令作为 cron 作业在服务器上运行。然后它会更新您所有软件包信息，就像 Packagist 一样。

请注意，如果您的私有软件包托管在 GitHub 上，您的服务器应该有一个 SSH 密钥，该密钥允许它访问这些软件包，然后您应该在命令中添加 --no-interaction（或 -n）标志，以确保它回退到 SSH 密钥身份验证，而不是提示输入密码。这对于持续集成服务器也是一个很好的技巧。

设置一个虚拟主机指向该 web/ 目录，假设它是 packages.example.org。或者，使用 PHP >= 5.4.0，您可以使用内置的 CLI 服务器 php -S localhost:port -t satis-output-dir/ 作为临时解决方案。

部分更新#

您可以指示 Satis 有选择地仅更新特定软件包或仅处理具有给定 URL 的存储库。这减少了重建 package.json 文件所需的时间，并且在您使用（自定义） Webhook 触发重建时代码被推送到您的存储库之一时非常有用。

要仅重建特定软件包，请在命令行中传递软件包名称，如下所示

php bin/satis build satis.json web/ this/package that/other-package

请注意，这仍然需要拉取和扫描所有 VCS 存储库，因为任何 VCS 存储库都可能包含（在任何分支上）选定的软件包之一。

如果您想要仅扫描选定的软件包，而不是所有 VCS 存储库，您需要为所有软件包声明一个名称（这仅适用于 VCS 存储库类型）

{
    "repositories": [
        { "name": "company/privaterepo", "type": "vcs", "url": "https://github.com/mycompany/privaterepo" },
        { "name": "private/repo", "type": "vcs", "url": "http://svn.example.org/private/repo" },
        { "name": "mycompany/privaterepo2", "type": "vcs", "url": "https://github.com/mycompany/privaterepo2" }
    ]
}

如果您想要仅扫描单个存储库并更新其中找到的所有软件包，请将 VCS 存储库 URL 作为可选参数传递

php bin/satis build --repository-url https://only.my/repo.git satis.json web/

用法#

在您的项目中，您现在只需要使用 packages.example.org 作为 URL 添加您自己的 Composer 存储库，然后您就可以要求您的私有软件包，并且一切都应该顺利进行。您不再需要在每个项目中复制所有存储库。只有一个唯一的存储库会自我更新。

{
    "repositories": [ { "type": "composer", "url": "http://packages.example.org/" } ],
    "require": {
        "company/package": "1.2.0",
        "company/package2": "1.5.2",
        "company/package3": "dev-master"
    }
}

安全#

要保护您的私有存储库，您可以通过 SSH 或 SSL 使用客户端证书托管它。在您的项目中，您可以使用 options 参数来指定服务器的连接选项。

使用 SSH 的自定义存储库示例（需要 SSH2 PECL 扩展）

{
    "repositories": [{
        "type": "composer",
        "url": "ssh2.sftp://example.org",
        "options": {
            "ssh2": {
                "username": "composer",
                "pubkey_file": "/home/composer/.ssh/id_rsa.pub",
                "privkey_file": "/home/composer/.ssh/id_rsa"
            }
        }
    }]
}

提示：有关更多信息，请参阅 ssh2 上下文选项。

使用 SSL/TLS（HTTPS）和客户端证书的示例

{
    "repositories": [{
         "type": "composer",
         "url": "https://example.org",
         "options": {
             "ssl": {
                 "local_cert": "/home/composer/.ssl/composer.pem"
             }
         }
    }]
}

提示：有关更多信息，请参阅 ssl 上下文选项。

使用自定义 HTTP 标头字段进行令牌身份验证的示例

{
    "repositories": [{
        "type": "composer",
        "url": "https://example.org",
        "options":  {
            "http": {
                "header": [
                    "API-TOKEN: YOUR-API-TOKEN"
                ]
            }
        }
    }]
}

身份验证#

身份验证可以在多种不同的方式中处理。

下载#

当 GitHub、GitLab 或 BitBucket 存储库在您的本地 satis 上镜像时，构建过程将包括这些平台提供的下载位置。这意味着存储库和您的设置依赖于这些服务的可用性。

同时，这意味着所有在其他地方托管的代码（在其他服务上，或者例如在 Subversion 中）将没有可用的下载，因此安装通常需要更长的时间。

要使您的 satis 安装能够为所有（Git、Mercurial 和 Subversion）软件包创建下载，请将以下内容添加到您的 satis.json 中

{
    "archive": {
        "directory": "dist",
        "format": "tar",
        "prefix-url": "https://amazing.cdn.example.org",
        "skip-dev": true
    }
}

选项说明#

directory：必需，dist 文件的位置（在 output-dir 内部）
format：可选，zip（默认）或 tar
prefix-url：可选，下载的位置，默认情况下为主页（来自 satis.json）后跟 directory
skip-dev：可选，默认情况下为 false，启用（true）时，satis 将不会为分支创建下载
absolute-directory：可选，一个本地目录，dist 文件将被转储到该目录，而不是 output-dir/directory
whitelist：可选，如果设置为软件包名称列表，satis 将仅转储这些软件包的 dist 文件
blacklist：可选，如果设置为软件包名称列表，satis 将不会转储这些软件包的 dist 文件
checksum：可选，默认情况下为 true，禁用（false）时，satis 不会为 dist 文件提供 sha1 校验和

启用后，所有下载（包括来自 GitHub 和 BitBucket 的下载）将被替换为本地版本。

prefix-url#

使用另一个主机对 URL 进行前缀，尤其是在下载最终存储在私有 Amazon S3 存储桶或 CDN 主机上时非常有用。CDN 会显着提高下载时间，从而提高软件包安装速度。

示例：prefix-url 为 https://my-bucket.s3.amazonaws.com（directory 设置为 dist），创建的下载 URL 如下所示：https://my-bucket.s3.amazonaws.com/dist/vendor-package-version-ref.zip。

Web 输出#

output-html：可选，默认情况下为 true，禁用（false）时，satis 不会生成 output-dir/index.html 页面。
twig-template：可选，output-dir/index.html 页面的个性化 Twig 模板的路径。

已废弃的软件包#

要使您的 satis 安装能够指示某些软件包已被废弃，请将以下内容添加到您的 satis.json 中

{
    "abandoned": {
        "company/package": true,
        "company/package2": "company/newpackage"
    }
}

true 值表示软件包已完全废弃，而 "company/newpackage" 值指定软件包由 company/newpackage 软件包替换。

请注意，在其自己的 composer.json 文件中设置为废弃的所有软件包也将被标记为废弃。

解析依赖项#

可以使 satis 自动解析并添加您项目的依赖项。这可以与 Downloads 功能一起使用，以拥有软件包的完整本地镜像。将以下内容添加到您的 satis.json 中

{
    "require-dependencies": true,
    "require-dev-dependencies": true
}

当搜索软件包时，satis 将尝试从列出的存储库中解析所有必需的软件包。因此，如果您需要来自 Packagist 的软件包，则需要在 satis.json 中定义它。

仅当 require-dev-dependencies 参数设置为 true 时，才会打包开发依赖项。

其他选项#

providers：可选，默认情况下为 false，启用（true）时，每个软件包将被转储到一个单独的包含文件中，该文件只有在真正需要软件包时才会由 Composer 加载。加快了 Composer 对具有大量软件包（例如 packagist）的存储库的处理速度。
output-dir：可选，定义在调用 build 命令时未提供为参数的情况下，存储库文件的输出位置。
config：可选，允许您定义来自 composer 的所有配置选项，除了 archive-format 和 archive-dir 之外，因为配置是通过 archive 完成的。有关更多详细信息，请参阅有关 config 架构的文档。
notify-batch：可选，指定在用户安装软件包时每次都会调用的 URL。请参阅 notify-batch。

发现错误？文档中有什么错误？分叉并编辑它！