README

Composer 插件，为包提供向根项目暴露自定义脚本的方法。这些脚本的工作方式类似于仅根的 scripts 选项。

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

内容

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

需求

PHP 7.1+
Composer 1.6+

术语

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

安装

在您的 composer.json 中指定 kuria/composer-pkg-scripts 作为依赖项。

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

{
    // ...
    "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"
    }
}

使用变量

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

占位符的语法是

{$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}"，不要将其嵌入到字符串中间。

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

运行包脚本

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

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 别名而不是完整的命令名称。

melchiorkokernoot / composer-pkg-scripts

维护者

详细信息