5. composer.json 架构

注意： 一个资源包是不是“root 包”，取决于它的上下文。 例：如果你的项目依赖 monolog 库，那么你的项目就是“root 包”。 但是，如果你从 GitHub 上克隆了 monolog 为它修复 bug， 那么此时monolog 就是“root 包”。

• monolog/monolog
• igorw/event-source

• 1.0.0
• 1.0.2
• 1.1.0
• 0.2.5
• 1.0.0-dev
• 1.0.0-alpha3
• 1.0.0-beta2
• 1.0.0-RC5

注意： Packagist 使用 VCS 仓库， 因此 version 定义的版本号必须是真实准确的。 自己手动指定的 version，最终有可能在某个时候因为人为错误造成问题。

• library: 这是默认类型，它会简单的将文件复制到 vendor 目录。
• project: 这表示当前包是一个项目，而不是一个库。例：框架应用程序 Symfony standard edition，内容管理系统 SilverStripe installer 或者完全成熟的分布式应用程序。使用 IDE 创建一个新的工作区时，这可以为其提供项目列表的初始化。
• metapackage: 当一个空的包，包含依赖并且需要触发依赖的安装，这将不会对系统写入额外的文件。因此这种安装类型并不需要一个 dist 或 source。
• composer-plugin: 一个安装类型为 composer-plugin 的包，它有一个自定义安装类型，可以为其它包提供一个 installler。详细请查看 9. 设置和使用自定义安装类型 。

• 该包相关的关键词的数组。这些可用于搜索和过滤。
• 实例：
  • logging
  • events
  • database
  • Redis
  • templating
• 可选。

• 该项目网站的 URL 地址。
• 可选。

• 版本发布时间。
• 必须符合 YYYY-MM-DD 或 YYYY-MM-DD HH:MM:SS 格式。
• 可选。

• 包的许可协议，它可以是一个字符串或者字符串数组。
• 最常见的许可协议的推荐写法（按字母排序）：
  • Apache-2.0
  • BSD-2-Clause
  • BSD-3-Clause
  • BSD-4-Clause
  • GPL-2.0
  • GPL-2.0+
  • GPL-3.0
  • GPL-3.0+
  • LGPL-2.1
  • LGPL-2.1+
  • LGPL-3.0
  • LGPL-3.0+
  • MIT
• 可选，但强烈建议提供此内容。更多许可协议的标识符请参见 SPDX Open Source License Registry。

• 一个例：

  {
      "license": "MIT"
  }
  

• 对于一个包，当允许在多个许可协议间进行选择时（"disjunctive license"），这些协议标识符可以被指定为数组。
• 多协议的一个例：

  {
      "license": [
         "LGPL-2.1",
         "GPL-3.0+"
      ]
  }
  

• 另外它们也可以由 "or" 分隔，并写在括号中：

  {
      "license": "(LGPL-2.1 or GPL-3.0+)"
  }
  

• 同样，当有多个许可协议需要结合使用时（"conjunctive license"），它们应该被 "and" 分隔，并写在括号中。

• 包的作者。这是一个对象数组。
• 这个对象必须包含以下属性：
  • name: 作者的姓名，通常使用真名。
  • email: 作者的 email 地址。
  • homepage: 作者主页的 URL 地址。
  • role: 该作者在此项目中担任的角色（例：开发人员 或 翻译）。
• 一个实例：

  {
      "authors": [
          {
              "name": "Nils Adermann",
              "email": "naderman@naderman.de",
              "homepage": "http://www.naderman.de",
              "role": "Developer"
          },
          {
              "name": "Jordi Boggiano",
              "email": "j.boggiano@seld.be",
              "homepage": "http://seld.be",
              "role": "Developer"
          }
      ]
  }
  

• 可选，但强烈建议提供此内容。

• 获取项目支持的向相关信息对象。
• 这个对象必须包含以下属性：
  • email: 项目支持 email 地址。
  • issues: 跟踪问题的 URL 地址。
  • forum: 论坛地址。
  • wiki: Wiki 地址。
  • irc: IRC 聊天频道地址，类似于 irc://server/channel。
  • source: 网址浏览或下载源。
• 一个实例：

  {
      "support": {
          "email": "support@example.org",
          "irc": "irc://irc.freenode.org/composer"
      }
  }
  

• 可选。

• 实例：

  {
      "require": {
          "monolog/monolog": "1.0.*"
      }
  }
  

• 所有的这些都是可选的。

• 实例：

  {
      "require": {
          "monolog/monolog": "1.0.*@beta",
          "acme/foo": "@dev"
      }
  }
  

• 实例：

  {
      "require": {
          "doctrine/doctrine-fixtures-bundle": "dev-master",
          "doctrine/data-fixtures": "@dev"
      }
  }
  

• 实例：

  {
      "require": {
          "monolog/monolog": "dev-master#2eb0c0978d290a1c45346a1955188929cb4e5db7",
          "acme/foo": "1.0.x-dev#abc123"
      }
  }
  

注意： 虽然这有时很方便，但不应该长期在你的包中使用，因为它有一个技术上的限制。 composer.json 将仍然在哈希值之前指定的分支名称读取元数据， 正因为如此，在某些情况下，它不会是一个实用的解决方法， 如果可能，你应该总是尝试切换到拥有标签的版本。

• 实例：

  {
      "suggest": {
          "monolog/monolog": "Allows more advanced logging of the application flow"
      }
  }
  

• Example:

  {
      "autoload": {
          "psr-4": {
              "Monolog\\": "src/",
              "Vendor\\Namespace\\": ""
          }
      }
  }
  

• If you need to search for a same prefix in multiple directories, you can specify them as an array as such:

  {
      "autoload": {
          "psr-4": { "Monolog\\": ["src/", "lib/"] }
      }
  }
  

• If you want to have a fallback directory where any namespace will be looked for, you can use an empty prefix like:

  {
      "autoload": {
          "psr-4": { "": "src/" }
      }
  }
  

• 实例：

  {
      "autoload": {
          "psr-0": {
              "Monolog\\": "src/",
              "Vendor\\Namespace\\": "src/",
              "Vendor_Namespace_": "src/"
          }
      }
  }
  

• 如果你需要搜索多个目录中一个相同的前缀，你可以将它们指定为一个数组，例：

  {
      "autoload": {
          "psr-0": { "Monolog\\": ["src/", "lib/"] }
      }
  }
  

• PSR-0 方式并不仅限于申明命名空间，也可以是精确到类级别的指定。这对于只有一个类在全局命名空间的类库是非常有用的（如果 PHP 源文件也位于包的根目录）。例如，可以这样申明：

  {
      "autoload": {
          "psr-0": { "UniqueGlobalClass": "" }
      }
  }
  

• 如果你想设置一个目录作为任何命名空间的备用目录，你可以使用空的前缀，像这样：

  {
      "autoload": {
          "psr-0": { "": "src/" }
      }
  }
  

• 实例：

  {
      "autoload": {
          "classmap": ["src/", "lib/", "Something.php"]
      }
  }
  

• 实例：

  {
      "autoload": {
          "files": ["src/MyLibrary/functions.php"]
      }
  }
  

• 实例:

  {
      "autoload": {
          "psr-4": { "MyLibrary\\": "src/" }
      },
      "autoload-dev": {
          "psr-4": { "MyLibrary\\Tests\\": "tests/" }
      }
  }
  

不建议 ：这是目前唯一支持传统项目的做法，所有新的代码都建议使用自动加载。 这是一个过时的做法，但 Composer 将仍然保留这个功能。

• 实例：

  {
      "include-path": ["lib/"]
  }
  

• 可选。

DEPRECATED : 这仅用于支持旧式PSR-0样式的自动加载，所有新代码最好使用不带target dir的PSR-4，并且鼓励使用带有PHP名称空间的PSR-0的项目迁移到PSR-4。

• 要做到这一点 autoload 和 target-dir 应该定义如下：

  {
      "autoload": {
          "psr-0": { "Symfony\\Component\\Yaml\\": "" }
      },
      "target-dir": "Symfony/Component/Yaml"
  }
  

• 可选。

• composer: 一个 composer 类型的资源库，是一个简单的网络服务器（HTTP、FTP、SSH）上的 packages.json 文件，它包含一个 composer.json 对象的列表，有额外的 dist 和/或 source 信息。这个 packages.json 文件是用一个 PHP 流加载的。你可以使用 options 参数来设定额外的流信息。
• vcs: 从 Git、SVN 和 hg 取得资源。
• pear: 从 pear 获取资源。
• package: 如果你依赖于一个项目，它不提供任何对 composer 的支持，你就可以使用这种类型。你基本上就只需要内联一个 composer.json 对象。

• 实例：

  {
      "repositories": [
          {
              "type": "composer",
              "url": "http://packages.example.com"
          },
          {
              "type": "composer",
              "url": "https://packages.example.com",
              "options": {
                  "ssl": {
                      "verify_peer": "true"
                  }
              }
          },
          {
              "type": "vcs",
              "url": "https://github.com/Seldaek/monolog"
          },
          {
              "type": "pear",
              "url": "http://pear2.php.net"
          },
          {
              "type": "package",
              "package": {
                  "name": "smarty/smarty",
                  "version": "3.1.7",
                  "dist": {
                      "url": "http://www.smarty.net/files/Smarty-3.1.7.zip",
                      "type": "zip"
                  },
                  "source": {
                      "url": "http://smarty-php.googlecode.com/svn/",
                      "type": "svn",
                      "reference": "tags/Smarty_3_1_7/distribution/"
                  }
              }
          }
      ]
  }
  

注意： 顺序是非常重要的，当 Composer 查找资源包时，它会按照顺序进行。默认情况下 Packagist 是最后加入的，因此自定义设置将可以覆盖 Packagist 上的包。

• process-timeout: 默认为 300。处理进程结束时间，例如：Git 克隆的时间。Composer 将放弃超时的任务。如果你的网络缓慢或者正在使用一个巨大的包，你可能要将这个值设置的更高一些。
• use-include-path: 默认为 false。如果为 true，Composer autoloader 还将在 PHP include path 中继续查找类文件。
• preferred-install: 默认为 auto。它的值可以是 source、dist 或 auto。这个选项允许你设置 Composer 的默认安装方法。
• github-protocols: 默认为 ["git", "https", "ssh"]。从 github.com 克隆时使用的协议优先级清单，因此默认情况下将优先使用 Git 协议进行克隆。你可以重新排列它们的次序，例如，如果你的网络有代理服务器或 Git 协议的效率很低，你就可以提升 https 协议的优先级。
• github-oauth: 一个域名和 OAuth keys 的列表。 例如：使用 {"github.com": "oauthtoken"} 作为此选项的值， 将使用 oauthtoken 来访问 GitHub 上的私人仓库，并绕过 low IP-based rate 的 API 限制。 关联知识 关于如何获取 GitHub 的 OAuth token。
• vendor-dir: 默认为 vendor。通过设置你可以安装依赖到不同的目录。
• bin-dir: 默认为 vendor/bin。如果一个项目包含二进制文件，它们将被连接到这个目录。
• cache-dir: unix 下默认为 $home/cache，Windows 下默认为 C:\Users\\AppData\Local\Composer。用于存储 composer 所有的缓存文件。相关信息请查看 4. 命令行 。
• cache-files-dir: 默认为 $cache-dir/files。存储包 zip 存档的目录。
• cache-repo-dir: 默认为 $cache-dir/repo。存储 composer 类型的 VCS（svn、github、bitbucket） repos 目录。
• cache-vcs-dir: 默认为 $cache-dir/vcs。此目录用于存储 VCS 克隆的 git/hg 类型的元数据，并加快安装速度。
• cache-files-ttl: 默认为 15552000（6个月）。默认情况下 Composer 缓存的所有数据都将在闲置6个月后被删除，这个选项允许你来调整这个时间，你可以将其设置为0以禁用缓存。
• cache-files-maxsize: 默认为 300MiB。Composer 缓存的最大容量，超出后将优先清除旧的缓存数据，直到缓存量低于这个数值。
• prepend-autoloader: 默认为 true。如果设置为 false，composer autoloader 将不会附加到现有的自动加载机制中。这有时候用来解决与其它自动加载机制产生的冲突。
• autoloader-suffix: 默认为 null。Composer autoloader 的后缀，当设置为空时将会产生一个随机的字符串。
• optimize-autoloader Defaults to false. Always optimize when dumping the autoloader.
• github-domains: 默认为 ["github.com"]。一个 GitHub mode 下的域名列表。这是用于GitHub的企业设置。
• notify-on-install: 默认为 true。Composer 允许资源仓库定义一个用于通知的 URL，以便有人从其上安装资源包时能够得到一个反馈通知。此选项允许你禁用该行为。
• discard-changes: 默认为 false，它的值可以是 true、false 或 stash。这个选项允许你设置在非交互模式下，当处理失败的更新时采用的处理方式。true 表示永远放弃更改。"stash" 表示继续尝试。Use this for CI servers or deploy scripts if you tend to have modified vendors.

{
    "config": {
        "bin-dir": "bin"
    }
}

• 任意的，供 scripts 使用的额外数据。这可以是几乎任何东西。若要从脚本事件访问处理程序，你可以这样做：

  $extra = $event->getComposer()->getPackage()->getExtra();
  

• 可选。

• exclude: 允许设置一个需要被排除的路径的列表。使用与 .gitignore 文件相同的语法。一个前导的（!）将会使其变成白名单而无视之前相同目录的排除设定。前导斜杠只会在项目的相对路径的开头匹配。星号为通配符。

{
    "archive": {
        "exclude": ["/foo/bar", "baz", "/*.test", "!/foo/bar/baz"]
    }
}