composer.json文件编写规范

根包:是由composer.json项目根目录定义的包。它是composer.json定义项目需求的主要部分。

  • 首先,生成一个composer.json示例:
    使用命令行工具:
    1 .切换到指定目录下D:www/>
    2 .composer inint //定义根目录composer.json包
    3 .按字段提示填写,初始化结果如下:
{
    "name": "zlq/douban",
    "description": "this is a douban house spider",
    "type": "douban",
    "license": "type",
    "authors": [
        {
            "name": "zheng wiliiam",
            "email": "zlqbook@outlook.com"
        }
    ],
    "minimum-stability": "stable",
    "require": {}
}

这是一个json根包的基本信息

  • 具体字段文件字段表现规范,查询JSON架构,快捷查询你所要使用的字段的格式。
    每个字段属性含义,下面是解释和示例。

字段属性

  • 名字 (已发布的包(库)必需。)
    包的名称:它由供应商名称和项目名称组成,用/分割
    独白/独白
    gorw /事件源
    该名称可以包含任何字符,包括空格,并且它不区分大小写(foo/bar并且Foo/Bar被视为相同的包)。为了简化安装,建议定义一个不包含非字母数字字符或空格的短小名称。
  • 说明(已发布的包(库)必需。)
    包的简短描述。通常这是一行长。
  • 版本
    包的版本,在大多数情况下,这不是必需的;
    这必须遵循的格式X.Y.Z或vX.Y.Z用一个可选的后缀-dev,-patch(-p), (-alpha),-a(-beta)-b或-RC。补丁,alpha,beta和RC后缀也可以后跟一个数字。
  • 型号
    包的类型。它默认为library。
    Composer支持四种类型:
    1 .library:这是默认值。它只是将文件复制到vendor。
    2 .project:这表示项目而不是库。例如,Symfony标准版等应用程序shell,SilverStripe安装程序等CMS 或作为软件包分发的完整应用程序。例如,这可以由IDE用于提供在创建新工作空间时初始化的项目列表。
    4 .metapackage:一个包含需求并将触发其安装的空包,但不包含任何文件,也不会向文件系统写入任何内容。因此,它不需要可安装dist或source密钥。
    5.composer-plugin:类型的包composer-plugin可以为具有自定义类型的其他包提供安装程序。在专门的文章中阅读更多 内容。
    如果在安装期间需要自定义逻辑,则仅使用自定义类型。建议省略此字段并将其默认设置为library。
    包类型用于自定义安装逻辑。如果您的软件包需要一些特殊逻辑,则可以定义自定义类型。这可以是a symfony-bundle,a wordpress-plugin或a typo3-cms-extension。这些类型都将特定于某些项目,并且需要提供能够安装该类型的包的安装程序。
  • 关键字
    与包相关的一组关键字。这些可用于搜索和过滤
  • 主页
    项目网站的URL。
  • 自述
    自述文档的相对路径。
  • 时间
    版本的发布日期。
    必须是YYYY-MM-DD或YYYY-MM-DD HH:MM:SS格式。
  • 许可
    包的许可证,这可以是字符串或字符串数​​组。
    最常见许可证的推荐表示法是(按字母顺序排列):

Apache的2.0
BSD-2-第
BSD -3-第
BSD-4-第
仅限GPL-2.0 / GPL-2.0或更高版本
仅限GPL-3.0 / GPL-3.0或更高版本
LGPL-2.1-only / LGPL-2.1或更高版本
LGPL-3.0-only / LGPL-3.0或更高版本
MIT

建议提供此功能,SPDX开源许可证注册表中列出了更多标识符。
对于闭源软件,可以将其"proprietary"用作许可证标识符。
一个例子:

{
    "license": "MIT"
}

对于包,当在许可证(“析取许可证”)之间进行选择时,可以将多个指定为数组。

析取许可证的示例:

{
    "license": [
       "LGPL-2.1-only",
       "GPL-3.0-or-later"
    ]
}

或者,它们可以用“或”分开并括在括号中;

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

类似地,当需要应用多个许可证(“联合许可证”)时,它们应该用“和”分隔并括在括号中。

  • 作者#
    包的作者。这是一个对象数组。
    每个作者对象可以具有以下属性:
    名称:作者姓名。通常是他们的真名。
    电子邮件:作者的电子邮件地址。
    主页:作者网站的URL。
    角色:作者在项目中的角色(例如开发者或翻译者)
    一个例子:
{
    "authors": [
        {
            "name": "Nils Adermann",
            "email": "naderman@naderman.de",
            "homepage": "http://www.naderman.de",
            "role": "Developer"
        },
        {
            "name": "Jordi Boggiano",
            "email": "j.boggiano@seld.be",
            "homepage": "https://seld.be",
            "role": "Developer"
        }
    ]
}
  • 支持#
    各种信息,以获得有关项目的支持。
    支持信息包括以下内容:

电子邮件:支持的电子邮件地址
问题:问题跟踪器的URL。
论坛:论坛的 URL。
wiki:wiki的 URL。
irc:支持的IRC通道,如irc:// server / channel。
source:用于浏览或下载源的 URL。
docs:文档的 URL。
rss: RSS源的URL。

一个例子:

{
    "support": {
        "email": "support@example.org",
        "irc": "irc://irc.freenode.org/composer"
    }
}
  • 包链接
    以下所有内容都采用了一个对象,该对象通过版本约束将包名称映射到包的版本。在这里阅读更多关于版本。
    例:
{
    "require": {
        "monolog/monolog": "1.0.*"
    }
}

所有链接都是可选字段。
require并且require-dev还支持稳定性标志(仅限root)。这些允许您进一步限制或扩展包的稳定性,超出最小稳定性设置的范围。例如,如果要允许不稳定的依赖包,可以将它们应用于约束,或将它们应用于空约束。
例:

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

如果您的某个依赖项依赖于不稳定的包,则还需要明确要求它,以及其足够的稳定性标志。
例:
假设doctrine/doctrine-fixtures-bundle需要"doctrine/data-fixtures": "dev-master" 在根composer.json中,你需要在下面添加第二行以允许doctrine/data-fixtures包的dev版本:

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

require并且require-dev还支持开发版本的显式引用(即提交),以确保它们被锁定到给定状态,即使您运行更新也是如此。这些只有在您明确要求使用开发版本并附加引用时才有效#<ref>。这也是一个 仅限root的功能,在依赖项中将被忽略。

例:

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

注意:此功能具有严重的技术限制,因为仍将从散列之前指定的分支名称中读取composer.json元数据。因此,您应该仅在开发期间将其用作临时解决方案以修复瞬态问题,直到您可以切换到标记版本。Composer团队不主动支持此功能,也不接受与其相关的错误报告。

也可以对包约束进行内联别名,以使其匹配否则不会的约束。有关更多信息,请参阅别名文章。

require并且require-dev还支持对项目成功运行所需的特定PHP版本和PHP扩展的引用。

例:

{
    "require" : {
        "php" : "^5.5 || ^7.0",
        "ext-mbstring": "*"
    }
}

注意:列出项目所需的PHP扩展非常重要。并非所有PHP安装都是相同的:有些可能会错过您可能认为是标准的扩展(例如ext-mysqli默认情况下在Fedora / CentOS最小安装系统中没有安装)。未能列出所需的PHP扩展可能会导致糟糕的用户体验:Composer将安装您的软件包而不会出现任何错误,但它会在运行时失败。该composer show --platform命令列出了系统上可用的所有PHP扩展。您可以使用它来帮助您编译您使用和要求的扩展列表。或者,您可以使用第三方工具分析项目以获取所使用的扩展名列表。

  • 要求
    列出此程序包所需的程序包。除非满足这些要求,否则不会安装包。
    require-dev (root-only)#
    列出开发此程序包或运行测试等所需的程序包。默认情况下会安装root程序包的dev要求。两个install或update支持--no-dev,以防止开发依赖从安装选项。

  • 冲突
    列出与此软件包版本冲突的软件包。它们不允许与您的包装一起安装。
    需要注意的是,如指定范围时,<1.0 >=1.1在一个conflict链接,这将说明与小于1.0的所有版本冲突和等于或更新比1.1在同一时间,这可能不是你想要的。你可能想要<1.0 || >=1.1在这种情况下去。

  • 替换
    列出由此包替换的包。这允许您分叉包,使用其自己的版本号以不同的名称发布它,而需要原始包的包继续使用您的fork,因为它替换了原始包。
    这对于包含子包的包也很有用,例如,主symfony / symfony包中包含所有Symfony组件,这些组件也可作为单独的包提供。如果您需要主包,它将自动满足其中一个单独组件的任何要求,因为它取代了它们。
    当使用替换为上述子包装目的时,建议小心。然后,您通常只应替换使用self.version作为版本约束,以确保主程序包仅替换该确切版本的子程序包,而不替换任何其他不正确的版本。

  • 提供
    此程序包提供的其他程序包列表。这对于通用接口非常有用。包可能依赖于某个虚拟 logger包,任何实现此记录器接口的库都只能将其列入provide。

  • 建议
    建议的包可以增强或适用于此包。这些是信息性的,并在安装软件包后显示,以便为用户提供他们可以添加更多软件包的提示,即使它们不是严格要求的。
    格式类似于上面的包链接,除了值是自由文本而不是版本约束。
    例:

{
    "suggest": {
        "monolog/monolog": "Allows more advanced logging of the application flow",
        "ext-xml": "Needed to support XML format in class Foo"
    }
}
  • 自动加载
    PHP自动加载器的自动加载映射。
    PSR-4和PSR-0 自动加载,classmap产生和files包括被支持。
    PSR-4是推荐的方式,因为它提供了更好的易用性(添加类时无需重新生成自动加载器)。
    PSR-4 #
    在psr-4键下,您可以定义从命名空间到路径的映射,相对于包根。自动加载类似于指向目录Foo\Bar\Baz的名称空间前缀 的类意味着自动加载器将查找名为的文件并将其包含(如果存在)。请注意,与旧的PSR-0样式相反,前缀()不存在于文件路径中。Foo\src/src/Bar/Baz.phpFoo\
    命名空间前缀必须以\允许类似前缀之间的冲突结束。例如Foo,匹配FooBar命名空间中的类,以便尾部反斜杠解决问题:Foo\并且FooBar\是不同的。
    在安装/更新期间,PSR-4引用全部组合成单个key => value数组,该数组可以在生成的文件中找到 vendor/composer/autoload_psr4.php。
    例:
{
    "autoload": {
        "psr-4": {
            "Monolog\\": "src/",
            "Vendor\\Namespace\\": ""
        }
    }
}

如果需要在多个目录中搜索相同的前缀,可以将它们指定为数组:

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

如果您想要一个可以查找任何命名空间的回退目录,您可以使用一个空前缀,如:

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

PSR-0 #
在psr-0键下,您可以定义从命名空间到路径的映射,相对于包根。请注意,这也支持PEAR样式的非命名空间约定。

请注意,名称空间声明应该\以确保自动加载器完全响应为止。例如Foo,匹配,FooBar所以尾部反斜杠解决问题:Foo\并且FooBar\是不同的。

在安装/更新期间,PSR-0引用全部组合成单个key => value数组,该数组可以在生成的文件中找到vendor/composer/autoload_namespaces.php。
例:

{
    "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/" }
    }
}
  • 类图
    classmap在安装/更新期间,引用都被组合成单个key => value数组,该数组可以在生成的文件中找到 vendor/composer/autoload_classmap.php。通过扫描给定目录/文件中的所有类.php和.inc文件来构建此映射。
    您可以使用类映射生成支持为不遵循PSR-0/4的所有库定义自动加载。要配置它,请指定要搜索类的所有目录或文件。
    例:
{
    "autoload": {
        "classmap": ["src/", "lib/", "Something.php"]
    }
}
  • 档案
    如果要在每个请求中明确要求某些文件,则可以使用files自动加载机制。如果您的包中包含无法由PHP自动加载的PHP函数,这将非常有用。
    例:
{
    "autoload": {
        "files": ["src/MyLibrary/functions.php"]
    }
}
  • 从类映射中排除文件#
    如果要从类别图中排除某些文件或文件夹,可以使用该exclude-from-classmap属性。这可能对您在实时环境中排除测试类很有用,例如,即使在构建优化的自动加载器时也会从类映射中跳过这些类。
    类映射生成器将忽略此处配置的路径中的所有文件。路径是从包根目录(即composer.json位置)绝对的,并且支持*匹配除斜杠之外的任何东西,并**匹配任何东西。**隐式添加到路径的末尾。
    例:

{
"autoload": {
"exclude-from-classmap": ["/Tests/", "/test/", "/tests/"]
}
}

  • 优化自动加载器
    自动加载器会对您的请求时间产生相当大的影响(使用大量类的大型框架中每个请求50-100ms)。

  • autoload-dev (仅限root)
    允许为开发目的定义自动加载规则。
    运行测试套件所需的类不应包含在主自动加载规则中,以避免在生产中污染自动加载器以及其他人将您的包用作依赖项。
    因此,最好依靠专用路径进行单元测试,并将其添加到autoload-dev部分。
    例:

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

  • 包含路径
    DEPRECATED:这仅用于支持遗留项目,并且所有新代码最好使用自动加载。因此,这是一种弃用的做法,但该功能本身不会从Composer中消失。
    应该附加到PHP的路径列表include_path。
    例:

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

  • 定义安装目标
    如果包根位于命名空间声明之下,则无法正确自动加载。target-dir解决了这个问题。
    Symfony就是一个例子。组件有单独的包。Yaml组件在下Symfony\Component\Yaml。包根是该 Yaml目录。为了使自动加载成为可能,我们需要确保它没有安装到vendor/symfony/yaml,但是代之以进入 vendor/symfony/yaml/Symfony/Component/Yaml,以便自动加载器可以加载它vendor/symfony/yaml。
    要做到这一点,autoload并target-dir定义如下:

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

  • 最小稳定性(仅限root)
    这定义了稳定性过滤包的默认行为。这默认为stable,所以如果你依赖一个dev包,你应该在你的文件中指定它以避免意外。
    检查每个软件包的所有版本的稳定性,而那些不如minimum-stability设置稳定的软件包在解决项目依赖性时会被忽略。(请注意,您也可以在每个包中使用在require块中指定的版本约束中的稳定性标志来指定稳定性要求。
    可用的选项(在稳定的顺序)dev,alpha,beta,RC,和stable。

  • prefer-stable (仅限根)
    启用此功能后,如果可以找到兼容的稳定包,Composer将优先选择比不稳定包更稳定的包。如果你需要一个开发版本或者只有一个软件包可以使用alpha,那么这些仍然会被选中,以保证最小稳定性。
    使用"prefer-stable": true启用。

  • 存储库(仅限root)
    使用自定义软件包存储库。
    默认情况下,Composer仅使用packagist存储库。通过指定存储库,您可以从其他地方获取包。
    存储库不会递归解析。你只能将它们添加到你的主 composer.json。依赖项的存储库声明composer.json被忽略。

  • 配置(仅限根)
    一组配置选项。它只用于项目。有关每个选项的说明,请参阅 Config。

  • 脚本(仅限根)
    Composer允许您通过使用脚本来挂接安装过程的各个部分。

有关事件的详细信息和示例,请参阅脚本。

  • 额外
    任意额外的数据供消费者使用scripts。
    这可以是几乎任何事情。要从脚本事件处理程序中访问它,您可以执行以下操作:
    $extra = $event->getComposer()->getPackage()->getExtra();
    可选的。

  • bin
    一组应该被视为二进制文件并被链接到bin-dir (从配置文件中)的文件。

有关详细信息,请参阅供应商二进制文件

  • 档案
    一组用于创建程序包归档的选项。
    支持以下选项:
    排除:允许配置排除路径的模式列表。模式语法与.gitignore文件匹配。前导感叹号(!)将导致包含任何匹配文件,即使先前的模式排除它们也是如此。前导斜杠只会在项目相对路径的开始处匹配。星号不会展开到目录分隔符。
    例:
{
    "archive": {
        "exclude": ["/foo/bar", "baz", "/*.test", "!/foo/bar/baz"]
    }
}

的例子包括/dir/foo/bar/file,/foo/bar/baz,/file.php, /foo/my.test但将排除/foo/bar/any,/foo/baz , /my.test。

  • 放弃#
    指示此包是否已被放弃。
    它可以是布尔值或指向推荐替代的包名称/ URL。
    默认为false
  • 非特征分支
    非数字(例如“最新”或其他)的分支名称的正则表达式列表,不会作为特征分支处理。这是一串字符串。

推荐阅读更多精彩内容