README

Composer 插件，为包提供了一种向根项目暴露自定义脚本的途径。这些脚本与仅根的 scripts 选项类似。

https://www.travis-ci.cn/kuria/composer-pkg-scripts.svg?branch=master

内容

要求
术语
安装
定义包脚本
运行包脚本
在事件中使用包脚本
列出包脚本
调试包脚本和变量

要求

PHP 7.1+
Composer 1.6+

术语

根包: 主要包（项目）
根脚本: 在根包的 scripts 选项中定义的脚本
包脚本: 在包的 extra.package-scripts 选项中定义的脚本

安装

将 kuria/composer-pkg-scripts 作为依赖项添加到您的 composer.json 文件中。

这可以在根包中完成，也可以在所需的一个包中完成（也许是一个元包）。这完全取决于您的使用情况。

{
    // ...
    "require": {
        "kuria/composer-pkg-scripts": "^1.0"
    }
}

定义包脚本

包脚本可以定义在 composer.json 的 extra 选项中。

语法与仅根 scripts 选项相同。参见 Composer 文档 - 定义脚本。

{
    "name": "acme/example",
    // ...
    "extra": {
        "package-scripts": {
            "hello-world": "echo Hello world!",
            "php-version": "php -v"
        }
    }
}

最终脚本名称将自动以包名称为前缀。

上面的示例将定义以下脚本

acme:example:hello-world
acme:example:php-version

要定义更短的别名，请参阅指定别名和帮助。

注意

包脚本不会覆盖具有相同名称的根 scripts。

注意

根包中定义的包脚本将不会被加载。请使用 scripts 代替。

引用其他脚本

除了根 scripts，包脚本还可以引用同一文件中定义的其他包脚本。

参见 Composer 文档 - 引用脚本。

{
    "name": "acme/example",
    // ...
    "extra": {
        "package-scripts": {
            "all": ["@first", "@second", "@third"],
            "first": "echo first",
            "second": "echo second",
            "third": "echo third"
        }
    }
}

可以使用其他包的完整名称或别名（如果存在）来引用其他包的脚本。建议使用完整名称。

{
    "name": "acme/example",
    // ...
    "extra": {
        "package-scripts": {
            "another-foo": "@acme:another:foo"
        }
    }
}

指定别名和帮助

包脚本的别名和帮助可以在 composer.json 的 extra 选项中定义。

{
    "name": "acme/example",
    // ...
    "extra": {
        "package-scripts": {
            "hello-world": "echo Hello world!",
            "php-version": "php -v"
        },
        "package-scripts-meta": {
            "hello-world": {"aliases": "hello", "help": "An example command"},
            "php-version": {"aliases": ["phpv", "pv"], "help": "Show PHP version"}
        }
    }
}

与脚本名称不同，别名不会自动以包名称为前缀。

上面的示例将定义以下脚本

acme:example:hello-world
acme:example:php-version
hello
phpv
pv

注意

包脚本别名不会覆盖具有相同名称的根 scripts 或其他别名。

在根包中指定别名

如果一个包没有提供合适的别名，根包可以在其 scripts 选项中定义它们。

{
    "name": "acme/project",
    // ...
    "scripts": {
        "acme-hello": "@acme:example:hello-world"
    }
}

使用变量

与根脚本不同，包脚本可以使用变量占位符。

占位符的语法是

{$variable-name}

变量名可以由除了"{"之外的任何字符组成
不存在的变量将解析为空字符串
最终值通过escapeshellarg()进行转义
数组变量将被连接成一个字符串，用空格分隔，每个值都通过escapeshellarg()进行转义

Composer配置

所有Composer配置指令都可通过变量访问。

请参阅Composer文档 - 配置。

{
    "name": "acme/example",
    // ...
    "extra": {
        "package-scripts": {
            "list-vendors": "ls {$vendor-dir}"
        }
    }
}

包变量

包可以在composer.json的extra选项中定义自己的变量。

{
    "name": "acme/example",
    // ...
    "extra": {
        "package-scripts": {
            "hello": "echo {$name}"
        },
        "package-scripts-vars": {
            "name": "Bob"
        }
    }
}

如果需要，这些默认值可以在根包中覆盖

{
    "name": "acme/project",
    // ...
    "extra": {
        "package-scripts-vars": {
            "acme/example": {
                "name": "John"
            }
        }
    }
}

引用其他变量

包变量可以引用composer配置指令或属于同一包的其他包变量。

{
    "name": "acme/example",
    // ...
    "extra": {
        "package-scripts": {
            "hello": "echo Hello {$names}",
            "show-paths": "echo {$paths}"
        },
        "package-scripts-vars": {
            "names": ["Bob", "{$other-names}"],
            "other-names": ["John", "Nick"],
            "paths": ["{$vendor-dir}", "{$bin-dir}"]
        }
    }
}

composer acme:example:hello

> echo Hello "Bob" "John" "Nick"
Hello Bob John Nick

composer acme:example:show-paths

> echo "/project/vendor" "/project/vendor/bin"
/project/vendor /project/vendor/bin

注意

数组变量必须直接引用，例如"{$array-var}"，不要嵌入到字符串中间。

嵌套数组变量的引用将展开成一个简单的列表，如上面示例所示。

运行包脚本

包脚本可以像根脚本一样调用

composer run-script acme:example:hello-world
composer acme:example:hello-world

请参阅Composer文档 - 手动运行脚本。

在事件中使用包脚本

包脚本可以在事件脚本中使用（前提是此时插件已加载）。

{
    "name": "acme/project",
    // ...
    "scripts": {
        "post-install-cmd": "@acme:example:hello-world"
    }
}

列出包脚本

此插件提供了一个名为package-scripts:list的命令，该命令列出活动和无效的包脚本及其别名。

composer package-scripts:list

Available package scripts:
  acme:example:hello-world (hello)    An example command
  acme:example:php-version (phpv, pv) Show PHP version

启用详细模式将显示更多信息

composer package-scripts:list -v

Available package scripts:
  acme:example:hello-world Run the "hello-world" script from acme/example
   - package: acme/example
   - definition: "echo Hello world!"
   - aliases:
  acme:example:php-version Run the "php-version" script from acme/example
   - package: acme/example
   - definition: "php -v"
   - aliases:

您可以使用psl别名而不是完整的命令名称。

调试包脚本和变量

此插件提供了一个名为package-scripts:dump的命令，该命令将转储编译后的脚本（包括根脚本）或包脚本变量。

composer package-scripts:dump

指定--vars标志将转储编译后的包脚本变量

composer package-scripts:dump --vars

您可以使用psd别名而不是完整的命令名称。

kuria / composer-pkg-scripts

维护者

详细信息