README

Composer-WP 是一个 composer 插件，用于帮助管理 WordPress 网站的依赖关系。Composer-WP 允许您通过 composer 完全处理 WordPress 核心版本、插件和主题。

安装

$ composer global require balbuf/composer-wp

Composer-WP 必须全局安装，这样插件才能在解决项目的依赖关系之前加载。

因此，将其作为项目的构建步骤之一是个好主意

composer global require balbuf/composer-wp
composer global update balbuf/composer-wp
composer install

或者，您可以将此步骤作为 composer 在安装或更新包之前执行的脚本

  "scripts": {
      "pre-cmd": [
          "composer global require balbuf/composer-wp && composer global update balbuf/composer-wp"
      ],
      "pre-install-cmd": "@pre-cmd",
      "pre-update-cmd": "@pre-cmd"
  }

关于

类似于 wpackagist，Composer-WP 利用官方 WordPress SVN 存储库来提供作为 composer 包的插件和主题。然而，Composer-WP 提供的包是“虚拟”的——Composer-WP 通过直接引用 SVN 存储库来按需创建包，以获取可用包的列表。因此，没有第三方包存储库要查询，列表始终是最新的。

此外，虚拟包允许包属性动态。这允许您通过调整供应商名称简单地更改包类型，例如。每个供应商名称映射到一个包类型，包类型决定了包将安装在哪里。例如，您可以通过使用适当的供应商名称将插件安装为“常规”或“必需”的（分别对应于 wordpress-plugin 或 wordpress-muplugin）。

除了官方公共 WordPress 存储库之外，Composer-WP 允许您定义包含压缩包的自己的插件或主题存储库。此类存储库可以引用本地目录或通过 SSH 访问的远程目录。这些压缩包是您将通过 WP 管理面板上传和安装的标准插件或主题压缩文件。Composer-WP 扫描这些压缩文件，并从文件头中提取元信息（例如，插件/主题名称和版本）来为这些创建虚拟包。此类存储库类型对于管理未公开列出的包非常有用，例如专有或付费插件/主题。

特性

内置对所有官方 WordPress 存储库的支持

只需将专有/付费插件和主题放入目录中即可管理它们

Composer-WP 提供了一种新的存储库类型，可以包含私有目录中的标准压缩插件或主题。这些压缩文件被扫描以获取元信息（例如，插件/主题名称和版本），以创建虚拟包——无需 composer.json 文件。这些压缩文件可以存储在本地目录中，也可以存储在可通过 SSH 访问的远程服务器上的目录中。这对于 composer 无法从公共来源下载的付费插件或主题特别有用。

可配置的“虚拟供应商”，允许动态包类型

例如，您可以通过交换供应商名称将插件安装为“常规”或“必需”的（例如，wordpress-plugin/my-plugin 或 wordpress-muplugin/my-plugin）。为了解决与其他存储库中供应商的冲突，可以通过您的 composer.json 文件的 extra 属性将每个虚拟供应商名称别名或完全禁用。

使用包含的 mu-plugins 自动加载器自动加载包

已安装为“必须使用”插件的任何常规插件，如果启用 mu-plugins 自动加载器（默认设置），则将在 WordPress 中自动加载。这些“必须使用”插件将按照它们出现在您的 composer.json 中的顺序加载，这允许您在特定插件依赖于其他插件的情况下显式指定加载优先级。mu-plugins 自动加载器还会拉取 composer 的自己的自动加载器，使您能够轻松地在 WordPress 项目中使用任何非 WordPress 包。mu-plugin 自动加载器受到了Bedrock 自动加载器的启发并基于其构建。

对包名称和描述进行全文搜索

对于有相应 API 的 WordPress 仓库（WordPress.org 插件和主题以及WordPress.com 主题），通过 composer search 进行包发现利用了 API 的全文搜索功能，根据包的名称、缩写（composer 包名）或描述进行匹配，就像您直接搜索这些目录一样。对于其他 WordPress 仓库，包通过缩写或供应商名称进行匹配。私有 zip 仓库支持基于从插件或主题头部信息获取的名称、缩写和描述进行全文搜索。

内置自定义安装器，可帮助您将包放置在所需位置

Composer 支持自定义安装器，允许您控制包的安装位置，例如，插件和主题将进入您的 wp-content 目录。例如，广泛使用的 composer-installers 插件处理 WordPress 主题和插件（但不是核心文件）。不需要额外的安装器插件，因为 Composer-WP 安装器处理所有 WordPress 包类型，并且专门针对 WordPress 项目。

访问不再列出在 WordPress 目录中的插件和主题

不再在公共目录中可用的包通常仍然可以从底层的 SVN 仓库中获取。虽然不建议依赖这些包，但这确保了如果包从公共目录中删除，composer 不会突然失败。相反，composer 将安装已停用的包，并显示“废弃”通知以警告您。

新版本立即可用

包直接从源发现，因此没有同步延迟或由第三方镜像引起的中断的可能性。新的 WordPress 核心版本以及插件和主题更新在发布的那一刻即可使用。

WordPress.org 插件和主题仓库被高效缓存

WordPress.org 插件和主题目录非常庞大，每个目录都包含数千个包。Composer-WP 使用智能缓存技术来获取包列表的增量更新。首次使用仓库时，Composer-WP 获取该时间点存在的整个包列表。对于后续对该仓库的请求，Composer-WP 仅检查新包并确定一个“包增量”，以便更新缓存的包列表。这意味着依赖项解析比 wpackagist 更快，wpackagist 的缓存大约每小时失效一次，需要重新下载整个包列表。

仅在需要时下载包列表

根据项目的 composer.json 需求和/或通过命令行传递给 composer 的参数自动加载仓库。例如，这意味着如果您的项目仅需要 WordPress.org 目录中的插件，则不会浪费时间下载您不关心的主题列表。

优雅处理使用非标准版本标识符的软件包

WordPress插件库中的软件包不强制执行版本规范。Composer-WP不会忽略这些软件包，而是会尝试标准化版本标识符，使其可由Composer解析。如果所有其他方法都失败，则该软件包仍以通用的“dev”版本提供。

文档

要求

当然，需要composer
PHP 5.4+（尚未在PHP 7上测试）
wp-zip库类型需要基于Unix的操作系统，尽管其他基本功能应该在Windows上工作

基本用法

首先，确保Composer-WP已全局安装

$ composer global require balbuf/composer-wp

在没有任何额外配置的情况下，官方WordPress目录中的软件包即可使用

$ composer require wordpress-plugin/oomph-clone-widgets

确定软件包名称

Composer-WP使用的软件包名称由特定于特定库的供应商名称和软件包“缩略名”组成

vendor/slug

每个内置WordPress库的供应商名称和软件包命名约定可以在下面找到。

插件和主题

对于WordPress目录中的插件和主题，缩略名是出现在其URL中的软件包的清理名称。

例如，假设您想安装Contact Form 7插件：https://wordpress.org/plugins/contact-form-7/。插件的缩略名将是contact-form-7，WordPress.org插件目录的默认供应商名称是wordpress-plugin。完整的软件包名称将是wordpress-plugin/contact-form-7。

软件包名称书签

为了方便确定插件或主题的正确软件包名称，您可以将以下JavaScript片段作为书签添加到浏览器中。如果您在wordpress.org、theme.wordpress.com或vip.wordpress.com上的插件或主题详细信息页面上，此书签将使用该库的默认供应商名称显示软件包名称
javascript:void((function(r,l,w,h,s,p,e,u,m){l=l.match.bind(l);u=h+w+'\\.org\\/';if(m=l(new r(u+'themes'+s)))return p(e,w+'-theme/'+m[1]);if(m=l(new r(u+'plugins'+s)))return p(e,w+'-plugin/'+m[1]);if(m=l(new r(h+'theme\\.'+w+'\\.com\\/themes'+s)))return p(e,w+'-com/'+m[1]);if(m=l(new r(h+'vip\\.'+w+'\\.com\\/plugins'+s)))return p(e,w+'-vip/'+m[1]);alert(e+' not found')})(RegExp,location.href,'wordpress','^https?:\\/\\/','\\/([^\\/]+)\\/?$',prompt,'Composer-WP package name:'));

WordPress核心

WordPress核心版本使用wordpress作为供应商和缩略名

$ composer require wordpress/wordpress

使用Composer命令查找软件包

composer search和composer show是用于查找和验证软件包的有用命令。

您可以使用composer search来查找软件包名称

$ composer search contact form 7

尽可能使用全文搜索来匹配名称和描述。

您可以使用composer show -a来获取有关软件包的更多信息或简单地验证它是否存在

$ composer show -a wordpress-plugin/contact-form-7

如果软件包存在，Composer将提供有关可用版本等额外信息。

composer.json示例

WordPress站点的一个简单composer.json文件可能看起来像

{
  "name": "My WordPress Site",
  "require": {
    "wordpress/wordpress": "^4.4",
    "wordpress-theme/zoo": "~1.8",
    "wordpress-plugin/getty-images": "^2.4",
    "wordpress-muplugin/wordpress-importer": "*"
  },
  "require-dev": {
    "wordpress-plugin/debug-bar": "0.8.2"
  }
}

进一步阅读

请参阅官方composer文档以获取有关一般使用的更多信息。

额外配置

Composer-WP有额外的配置选项，可以在composer.json文件的"extra"属性中的"composer-wp"部分指定。默认设置是根据典型的WordPress项目配置的，因此您可能不需要更改这些选项进行基本使用。

  "extra": {
    "composer-wp": {
      "repositories": [],
      "vendors": {},
      "installer": {}
    }
  }

仓库

"repositories"属性是一个数组，包含影响内置仓库或定义新的自定义仓库的仓库配置。

内置仓库

仓库属性的简单用途是指定内置仓库以启用或禁用

"repositories": [
  {
    "themes": false
  },
  {
    "develop": true
  }
]

此配置将禁用WordPress.org主题目录并启用WordPress核心开发仓库。这些仓库通过其仓库名称进行引用，仓库名称如下所示。所有内置仓库（除核心开发仓库外）在通过composer.json或命令行参数请求它们所处理的包时将自动加载，因此通常不需要在此处启用内置仓库。然而，您可以使用此功能禁用不需要使用的仓库（例如，为了加快某些命令，如composer search）。如果您希望使用WordPress核心开发仓库，必须显式启用它，如上所示。启用或禁用内置仓库也可以合并为一个单独的对象

"repositories": [
  {
    "themes": false,
    "develop": true
  }
]

自定义仓库

您也可以在此处定义新的仓库

"repositories": [
  {
    "type": "wp-zip",
    "url": "/private-plugins",
    "ssh": "user@example.com",
    "max-depth": 1
  }
]

Composer-WP支持两种仓库类型：wp-zip和wp-svn。每种类型都有自己的属性，但都共享以下属性

type （必需）

定义仓库的类型
- wp-zip - 此仓库类型允许您在本地或通过SSH远程扫描插件或主题的zip文件目录
- wp-svn - 此仓库类型用于内部内置仓库，允许公共SVN仓库充当composer包仓库
package-types （必需）

这是一个对象，用于定义支持的包类型并将类型映射到供应商名称。例如
```
"package-types": {
  "wordpress-plugin": "wpackagist-plugin",
  "wordpress-theme": "wpackagist-theme"
}
```
这将允许仓库处理使用wpackagist的供应商名称的包
url （必需）

根据仓库类型，这定义了URL或路径。

特定于仓库类型的属性

wp-zip
- url （必需）
  
  url属性定义了zip文件所在的目录路径。对于SSH仓库，这仅是路径，不包括服务器的域名。
- ssh
  
  此属性定义了SSH连接信息（如果适用）：[用户@]主机。格式与传递给ssh的格式完全相同。默认值为null - 仓库路径是本地的。
- package-types （必需）
  
  默认
```
"package-types": {
  "wordpress-plugin": "wordpress-plugin",
  "wordpress-muplugin": "wordpress-muplugin",
  "wordpress-theme": "wordpress-theme"
}
```
- max-depth
  
  在指定路径内遍历的最大目录数。默认值为null - 无限制。

供应商

“ vendors”属性允许您创建供应商别名并禁用现有的供应商名称。此属性是一个简单的对象，将新的供应商名称映射到现有名称，或将现有供应商名称映射到false以禁用其使用

"vendors": {
  "wpackagist-plugin": "wordpress-plugin",
  "wpcom-themes": "wordpress-com",
  "wordpress-com": false
}

上述配置将允许插件以来自wpackagist的方式要求，并将默认的WordPress.com主题仓库供应商名称wordpress-com替换为wpcom-themes。请注意，原始供应商名称wordpress-com将不再被识别，但wpackagist-plugin和wordpress-plugin都将被识别。

安装程序

“ installer”属性允许您配置内置的安装程序。安装程序旨在与其他自定义安装程序（如https://github.com/oomphinc/composer-installers-extender）兼容。也就是说，如果没有其他自定义安装程序，Composer-WP将默认处理WordPress包。然而，如果有另一个自定义安装程序（如https://github.com/oomphinc/composer-installers-extender）被配置为处理WordPress包，Composer-WP将允许该安装程序处理这些包，除非明确指示（通过指定安装路径）

内置安装程序有以下属性

wordpress-path （默认：wp）

这定义了您希望将WordPress核心文件安装到项目根目录的相对位置。注意，当Composer安装一个包时，它会在安装新文件之前完全清空目标目录。因此，WordPress路径应仅用于WordPress核心文件，因为任何其他内容（例如插件、主题和wp-config.php）在安装或更新时将被删除。建议您将wp-config.php文件放在WordPress路径的父目录中（WordPress可以自动在那里找到它），并将wp-content目录替换为指向您的实际wp-content文件夹的符号链接。（请参阅下面的symlink-wp-content选项。）
wp-content-path （默认值： wp-content）

这定义了主题、插件和mu插件将被安装到项目根目录的相对位置。该路径将被视为标准的wp-content文件夹，即包将安装到该路径下的themes、plugins和mu-plugins子目录。必须指定此选项才能使用symlink-wp-content选项。
wpmu-plugin-dir

这允许您指定与wp-content中标准位置不同的mu插件路径。WordPress允许您定义一个常数来改变mu-plugins路径，这样您就可以将mu插件包安装到您的备用路径。如果指定，这将覆盖否则将使用的基于wp-content的路径。
path-mapping

如果您需要更细粒度地控制WordPress包类型，您可以在此处单独指定每个类型及其安装路径的映射。如果您使用了wordpress-path和/或wp-content-path属性，您可能不需要使用此选项。

示例
```
"path-mapping": {
  "wordpress-theme": "wp-content/themes/my-custom-themes"
}
```
注意，如果显式设置，wordpress-muplugin和wordpress-core类型将被wpmu-plugin-dir和wordpress-path属性替代。
symlink-wp-content （默认值： true）

此选项允许Composer-WP自动将WordPress核心文件附带的wp-content目录替换为指向wp-content-path中设置的目录的符号链接。这允许在不受其他包影响的情况下清除和重新安装WordPress核心文件。每当WordPress核心更新时，符号链接将被恢复。请注意，WordPress核心发布中包含的原始wp-content目录将被删除，这意味着如果您想使用示例WordPress主题（例如“twentysixteen”）或插件，您必须在composer.json中分别要求它们。为了使用此选项，必须定义wordpress-path和wp-content-path属性（默认值被视为有效），并且这些路径必须存在（例如，有包安装到这些路径）。
mu-plugin-autoloader （默认值： true）

此选项允许您启用或禁用包含的mu插件自动加载器。如果启用，所有安装在mu插件目录中的常规插件将按在composer.json中定义的顺序自动加载到WordPress中。此外，Composer自动加载器将被加载到WordPress中。为了使用此选项，必须定义wp-content-path或wpmu-plugin-dir（默认值被视为有效）并且这些路径必须存在。
autoloader-path

此选项允许您指定mu插件自动加载器将包含的Composer自动加载器文件的显式路径。如果没有指定，该值将是从WordPress根目录或mu插件文件夹到您的vendor文件夹的相对路径，并附加autoload.php。您还可以使用WordPress安装中的COMPOSER_AUTOLOADER常数覆盖此设置。如果定义了此常数，则它将优先。您可以将此常数的值设置为false以不包含任何Composer自动加载器。
dev-first （默认值： false）

此选项用于确定是否首先通过自动加载器加载 require-dev mu 插件。默认情况下，require 中的 mu 插件将在 require-dev 中的任何插件之前加载。

可以通过将此属性设置为 false 完全禁用安装程序。

"installer": false

内置 WordPress 仓库

Composer-WP 有几个内置仓库，当您请求这些仓库的软件包时，它们将自动加载。每个仓库都有自己的供应商名称集合，用于确定请求的软件包应加载哪些仓库。可以通过您的 composer.json 文件（见下文）显式启用或禁用特定的仓库。

WordPress.org 插件 (https://wordpress.org/plugins/)

由 WordPress 社区开发的插件。

WordPress.org 主题 (https://wordpress.org/themes/)

由 WordPress 社区开发的主题。

WordPress 核心 (https://wordpress.org/download/)

WordPress 核心版本，包括主要版本和安全性/错误修复更新。

WordPress.com 主题 (https://theme.wordpress.com/)

提供用于 WordPress.com 托管网站的免费主题，但也可能用于自托管网站。

WordPress VIP 插件 (https://vip.wordpress.com/plugins/)

获准在 WordPress VIP 托管网站上使用的插件。注意：这些插件可能不在 WordPress VIP 环境外正确工作。有关在 WordPress VIP 环境中复制的更多信息，请参阅 VIP 快速入门文档。

WordPress 核心 - 开发版本 (https://develop.svn.wordpress.org/)

WordPress 核心开发仓库与主核心仓库保持同步，但还包括单元测试框架和国际化的额外工具。注意：与其他内置仓库不同，必须显式启用 develop 仓库才能将其用作依赖项，因为它与常规 core 仓库共享供应商命名空间。

balbuf / composer-wp

维护者

详细信息