处理私有包

Private Packagist

Private Packagist 是一款商业包托管产品，提供专业支持以及基于网页的私有和公共包管理，还有精细的访问权限控制。Private Packagist 为包的 zip 文件提供镜像功能，这使得安装速度更快，且不依赖第三方系统——例如，即使 GitHub 出现故障，你也可以进行部署，因为你的 zip 文件有镜像备份。

Private Packagist 有托管的 SaaS 解决方案和本地自托管包两种形式，提供交互式的设置体验。

Private 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
}

如果你想精挑细选所需的包，可以在经典的composerrequire键中列出你希望在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>

当你理顺了这个流程后，通常要做的就是在服务器上把这个命令作为定时任务来运行。这样它就会像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文件所需的时间，如果你使用（自定义）网络钩子在代码推送到你的某个仓库时触发重新构建，这会很有帮助。

要仅重新构建特定的包，请在命令行中传递包名称，如下所示：

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

请注意，这仍然需要拉取并扫描您所有的版本控制系统（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" }
    ]
}

如果您只想扫描单个代码库并更新其中发现的所有包，请将版本控制系统代码库的URL作为可选参数传递：

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

用法

在你的项目中，现在只需添加你自己的Composer仓库，使用packages.example.org作为URL，然后你就可以获取你的私有包，一切都应该能顺利运行。你不再需要在每个项目中复制所有仓库了，只需要那个会自动更新的唯一仓库即可。

{
    "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：可选参数，是一个本地目录，用于存放分发文件，而非使用output-dir/directory
whitelist：可选，如果设置为包名称列表，satis将仅转储这些包的dist文件
blacklist：可选，如果设置为包名称列表，satis将不会转储这些包的发行文件
checksum：可选，默认值为true，禁用时（false），satis不会为分发文件提供sha1校验和。

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

前缀-url

如果下载内容最终存储在私有的Amazon S3存储桶或CDN主机上，那么在URL前加上另一个主机名会特别有用。CDN能大幅缩短下载时间，从而加快软件包的安装速度。

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

网页输出

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自动解析并添加项目的所有依赖项。这可以与下载功能一起使用，以获得完整的本地包镜像。将以下内容添加到您的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完成的。有关更多详细信息，请参阅配置架构上的文档。
notify-batch：可选参数，用于指定每次用户安装软件包时将被调用的URL。请参见notify-batch。