什么是 Packagist？

Packagist 是默认的 Composer 包仓库。它让您找到包，并让 Composer 知道从哪里获取代码。您可以使用 Composer 来管理项目或库的依赖关系 - 更多信息请访问 Composer 网站。

您可以在 GitHub 上找到 packagist.org 的源代码。

社区

如果您对 Composer 有问题或想提供帮助，请加入我们，在 irc.libera.chat 的 #composer 频道。您可以在 Composer 文档 中找到更多社区资源。

贡献/捐赠

要报告问题或贡献代码，您可以在 GitHub 上找到源代码仓库。

如果您想从财务上支持项目的托管和维护，最好的方式是检查和使用 Private Packagist。它可以帮助您快速可靠地安装包，为您提供私有包仓库，而且这笔钱将用于 Composer 和 Packagist 的维护！

如何提交包？

命名您的包

首先，您必须选择一个包名。这是一个非常重要的步骤，因为一旦选择就无法更改，它应该足够独特，以避免未来发生冲突。

包名由供应商名称和项目名称组成，它们通过 / 连接。供应商名称存在是为了防止命名冲突。例如，通过包含供应商名称，igorw 和 seldaek 都可以有一个名为 json 的库，通过将它们的包命名为 igorw/json 和 seldaek/json。

在某些情况下，供应商名称和包名称可能相同。一个例子是 `monolog/monolog`。对于具有唯一名称的项目，这被推荐。这也允许以后在同一个供应商下添加更多相关项目。如果您正在维护一个库，这将使您能够轻松地将它拆分成更小的解耦部分。

以下是典型的包名称列表供参考

// Monolog is a library, so the vendor name and package name are the same.
monolog/monolog

// That could be the name of a drupal module (maintained/provided by monolog,
// if the drupal team did it, the vendor would be drupal).
monolog/monolog-drupal-module

// Acme is a company or person here, they can name their package with a common name (Email).
// As long as it's in their own vendor namespace it does not conflict with anyone else.
acme/email

一旦在 Packagist 上发布了一个具有该名称的包，包上的供应商名称就受到保护。这意味着您不能发布已存在于 Packagist 上的具有相同供应商名称的包，除非获得许可。要能够为已存在的供应商名称发布包，您需要是该供应商至少一个包的维护者。包和供应商名称可以包含小写字母 (a-z)、数字 (0-9) 以及字符 ".", "-" 和 "_"。每个都必须以字母或数字开头。

创建 composer.json 文件

composer.json 文件应位于您的包的 git/svn/.. 仓库的顶部，它是您向 Packagist 和 Composer 描述您的包的方式。

典型的 composer.json 文件看起来像这样

{
    "name": "monolog/monolog",
    "type": "library",
    "description": "Logging for PHP 8.0",
    "keywords": ["log","logging"],
    "homepage": "https://github.com/Seldaek/monolog",
    "license": "MIT",
    "authors": [
        {
            "name": "Jordi Boggiano",
            "email": "[email protected]",
            "homepage": "http://seld.be",
            "role": "Developer"
        }
    ],
    "require": {
        "php": ">=8.0.0"
    },
    "autoload": {
        "psr-0": {
            "Monolog": "src"
        }
    }
}

大多数这些信息都很明显，关键字是标签，require 是您的包具有的依赖项列表。这当然可以是包，不仅仅是 PHP 版本。您可以使用 ext-foo 来要求 PHP 扩展（例如 ext-curl）。请注意，大多数扩展没有暴露版本信息，所以除非您确信它有，否则使用 "ext-curl": "*" 允许任何版本更安全。最后，type 字段在这种情况下表示这是一个库。如果您为框架等创建插件，并且如果它们集成了 composer，它们可能有自己的插件包类型，您可以使用它们自己的安装程序来安装该包。如果没有自定义类型，您可以选择省略它或使用 "library"。

一旦将此文件提交到您的仓库根目录，您就可以通过输入公共仓库URL来将包提交到Packagist。

管理包版本

您的包的新版本会自动从您在VCS仓库中创建的标签中获取。

管理版本的最简单方法是直接从composer.json文件中省略版本字段。版本号将随后从标签和分支名称中解析。

标签/版本名称应匹配'X.Y.Z'或'vX.Y.Z'，对于RC、beta、alpha或修补程序版本，可以有一个可选后缀。以下是一些有效的标签名称示例

1.0.0
v1.0.0
1.10.5-RC1
v4.4.4beta2
v2.0.0-alpha
v2.0.4-p1

分支将自动出现在“dev”版本中，任何人都可以轻松安装以尝试您的库的最新和最佳版本，但这并不意味着您不应该标记发布。强烈建议使用语义化版本控制。

更新计划

如果您已启用JS，新包将在提交后立即被爬取。

没有自动更新（GitHub/BitBucket/GitLab/Gitea钩子）的现有包将每周爬取一次以获取更新。当启用钩子时，包将在您推送时或至少每月至少一次（如果爬取失败）时被爬取。如果您已登录为维护者，您还可以在包页面上手动触发包的更新。

强烈建议为所有包设置GitHub/BitBucket/GitLab/Gitea服务钩子。这减少了我们这边的负载，并确保您的包几乎可以即时更新。请查看下方的如何更新包说明。

搜索索引每5分钟更新一次。它将索引（或重新索引）自上次搜索索引器运行以来被爬取的任何包。

如何更新包？

GitHub钩子

启用Packagist服务钩子确保您在GitHub上推送时，您的包总是可以即时更新。

为此，您可以

  • 确保您通过GitHub登录（如果您已经有了一个未连接到GitHub的账户，您可以在您的个人资料上连接它）。如果您已经登录，请先注销，然后再通过GitHub再次登录，以确保您授予我们所需的权限。
  • 确保Packagist应用程序有权访问您需要从其发布包的所有GitHub组织。
  • 查看您的包列表，以查看是否有任何包有关于未自动同步的警告。
  • 如果您还需要为某些包设置同步，请尝试触发手动账户同步，让Packagist再次尝试在您的账户上设置钩子。请注意，存档的仓库无法设置，因为它们在GitHub的API中是只读的。

不想通过GitHub登录并授予我们webhook配置访问权限吗？

您可以使用以下值手动配置GitHub webhook

  • 有效载荷URL：https://packagist.org.cn/api/github?username=PACKAGIST_USERNAME
  • 内容类型：application/json
  • 密钥：您的Packagist API令牌
  • 哪些事件？只需push事件就足够了。

Bitbucket Webhooks

要启用Bitbucket webhook，请转到您的Bitbucket仓库，打开设置并从菜单中选择“Webhooks”。添加一个新的钩子。您必须输入包含您的用户名和API令牌的Packagist端点。输入https://packagist.org.cn/api/bitbucket?username=USERNAME&apiToken=API_TOKEN作为URL。保存您的更改，完成操作。

GitLab服务

要启用GitLab服务集成，请转到您的GitLab仓库，从菜单中选择设置>集成页面。在项目服务列表中搜索Packagist。勾选“Active”框，输入您的packagist.org用户名和API令牌。保存您的更改，完成操作。

Gitea Webhook

Gitea从v1.17版本开始支持在Packagist上自动更新包。

要启用 Gitea webhook，请前往您的 Gitea 仓库，打开设置 > Webhooks 页面，然后点击“添加 Webhook”。从下拉菜单中选择“Packagist”。您需要在表单中输入您的 Packagist 用户名、API 令牌和您的软件包的 Packagist URL。所有其他选项可以保持不变。保存您的更改即可。

手动钩子设置

如果您不使用 Bitbucket 或 GitHub，您可以手动调用一个通用端点，该端点可以从 git post-receive 钩子或类似的功能中调用。您必须向 https://packagist.org.cn/api/update-package?username=USERNAME&apiToken=API_TOKEN 发送一个 POST 请求，请求体如下所示：{"repository":{"url":"PACKAGIST_PACKAGE_URL"}}

您可以使用 curl 等工具来完成此操作。

curl -XPOST -H'content-type:application/json' 'https://packagist.org.cn/api/update-package?username=USERNAME&apiToken=API_TOKEN' -d'{"repository":{"url":"PACKAGIST_PACKAGE_URL"}}'

API 令牌

您可以在您的 个人资料页面 上找到您的 API 令牌。

IP 允许列表

如果您正在尝试限制 IP 并需要授权我们的 packagist.org 工作人员访问，我们维护一个 公共 IP 地址列表。