README

PSH - PHP shell helper

继续使用您的标准shell脚本

PSH旨在成为一个简单、易于使用的构建脚本解决方案的替代品。

介绍

您不必学习一门新的语言（通常更加冗长），而是可以在命令行上扩展您的现有技能。

主要优点是

与团队成员共享您的现有shell脚本
如果单个语句在sh脚本中失败，则添加错误处理
用变量替换sh脚本中的占位符
在环境配置中重载变量和脚本

安装

尽管您可以将PSH用作composer依赖项，但我们建议使用<强>PHAR存档。PSH仅通过shell与您的应用程序通信，因此不需要对您的其他项目依赖项产生影响。

通过composer

本地

composer require shopware/psh --dev

全局

composer global require shopware/psh

作为PHAR存档

将psh.phar下载到您的本地环境中。

wget https://shopwarelabs.github.io/psh/psh.phar # PHP7 Version
chmod +x psh.phar

通过phive作为PHAR存档（推荐）

phive install psh

如果您想了解如何安装phive，请点击这里。

自己构建

PSH用于构建自身。您需要先克隆存储库并自行安装composer依赖项。

git clone https://github.com/shopwareLabs/psh.git
cd psh
composer install # assuming you have composer installed globally
composer bin box install # box is needed to build phar file

./psh unit # verify your installation by executing the test suite.
./psh build

这将在build/psh.phar目录中创建一个发布phar。项目本身需要PHP 7.2+。

使用方法

注意：YAML配置格式已弃用，将在版本2.0中删除。如果您需要旧版文档，请参阅此文档的旧版本。

PSH是一个CLI应用程序。在使用之前，您需要在项目根目录中创建一个名为.psh.xml或.psh.xml.dist的配置文件。

配置

所需的最小文件如下所示

<?xml version="1.0" encoding="UTF-8"?>
<psh xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopwareLabs/psh/master/resource/config.xsd">

</psh>

根元素（<psh>）可以包含以下配置选项之一、多个或全部。

路径

为了将psh用作脚本执行器，您需要定义搜索的位置。

<path>deployment/scripts</path>
<path>test/scripts</path>
<path>more/scripts</path>

然后PSH将在所有这些位置中搜索*.sh文件。这些脚本可以通过PSH执行。

注意：如果脚本名称以点（.）开头，它将被排除在列表之外，但可以像任何其他脚本一样调用。> psh.phar .hidden-action

占位符

脚本中的占位符如下所示

ln -s __PATH__

占位符__PATH__现在需要作为配置文件中的常量或变量的一部分。

通知：在脚本中，所有占位符必须使用大写字母。即使配置中定义了其他方式，替换也仅适用于大写字母。在占位符的末尾添加（sic!）将会进行转义。例如 __DIR__(sic!)。

常量

常量是占位符替换的基本解决方案。您可以在配置中这样定义占位符

<placeholder>
    <const name="PATH">/var/www</const>
</placeholder>

然后这将执行

ln -s /var/www

变量

使用变量，您可以在脚本中使用一行shell语句的输出。

<placeholder>
    <dynamic name="PATH">echo $HOME</dynamic>
</placeholder>

变量将在实际语句执行之前执行，但您可以想象结果等同于

ln -s `echo $HOME`

Dotenv

使用dotenv，您有权加载项目中的 .env 文件。

<placeholder>
    <dotenv>.env</dotenv>
</placeholder>

您还可以配置多个指向 .env 文件的路径。

<placeholder>
    <dotenv>.env</dotenv>
    <dotenv>.env2</dotenv>
</placeholder>

.env2 在此示例中覆盖了 .env。

示例

.psh.xml

<path>dev-ops/common/actions"</path>
<placeholder>
    <dotenv>.env</dotenv>
</placeholder>

.env

TEST=mytest

dev-ops/common/actions/test.sh

#!/usr/bin/env bash

echo __TEST__

要求

可能需要要求设置占位符，但不能立即设置。一个这样的例子可能是一个系统依赖的路径。PSH 允许您通过添加以下内容与用户进行通信

<placeholder>
    <require name="FOO" description="Foo needs to be a reference to bar"/>
</placeholder>

现在除非 foo 设置，否则无法执行任何 psh 脚本。描述是可选的，可以省略。

模板

如果您的应用程序依赖于不属于您的存储库的文件，因为这些文件在不同系统上不同（通常是 *.dist 文件），您可以使用模板来实现这些文件的自动部署。

<template 
    source="templates/consts.tpl" 
    destination="app/consts.php"
/>

这读取了 templates/consts.tpl 的内容，使用配置中的常量或变量替换占位符，并将结果写入 app/consts.php。

甚至可以在模板目标中使用占位符

<template
    source="templates/consts.tpl"
    destination="app/consts-__ENVIRONMENT__.php"
/>

环境

环境用于扩展或覆盖基本配置。您可以添加更多脚本，重新定义或添加常量或变量。一个名为 foo 的环境可能看起来像这样

<environment name="foo">

    <path>foo/sh/scripts</path>
    <path>bar/sh/scripts</path>
    
    <placeholder>
        <const name="TEST">1</const>
        <dynamic name="ID">id</dynamic>   
    </placeholder>

</environment>

此环境加载来自 foo/sh/scripts 和 bar/sh/scripts 的所有脚本，添加一个常量 TEST 和一个变量 ID。如果您想调用此环境中的脚本，必须在调用前加上 foo:。

为了排除整个环境，请将 hidden 属性添加到环境标签，并将其设置为 true，如下所示

<environment name="internal" hidden="true">
    <path>internal/only/scripts</path>
</environment>

这些脚本可以像任何常规脚本一样执行，只是不会显示在列表中。

头部

可选的 - 并且只是为了好玩 - 您可以在每次 PSH 执行前输出一个 ASCII 标题。

    <header><![CDATA[
         _
     ___| |__   ___  _ ____      ____ _ _ __ ___
    / __| '_ \ / _ \| '_ \ \ /\ / / _` | '__/ _ \
    \__ \ | | | (_) | |_) \ V  V / (_| | | |  __/
    |___/_| |_|\___/| .__/ \_/\_/ \__,_|_|  \___|
                    |_|
    ]]></header>

覆盖配置文件

您可以在 .psh.xml 所在目录中放置一个 .psh.xml.override 以覆盖特定的配置。

注意：您可以使用 YAML 文件覆盖 XML 配置文件，以便于从一种格式迁移到另一种格式。

导入配置文件

您可以使用导入语句导入环境、操作和占位符，并告诉 psh 在其他地方查找。

<import path="another/config/file/location" />

这些目录应包含一个 psh.xml 或 psh.xml.dist。如果没有找到文件，则发出警告，但不会产生中断错误，因为 psh 可能目前正在安装或下载文件。您还可以使用 glob 模式，如 "tools/**/config"。

注意：这是通过合并不同的配置为一个来完成的。请注意，您可能会覆盖基本配置。

PSH-脚本

尽管您的大多数现有 sh 脚本应该可以正常工作，但您可能会发现以下一些添加是有用的或必要的。

请注意：命令将验证执行成功 -> 所有失败都将导致脚本失败！

定义占位符

为了确保您的脚本可重用，您可以添加 PSH 将用配置值替换的占位符。所有占位符以 __ 开头和结尾，只包含大写字母、数字和单个 _ 字符。

__TEST_IT__

包括其他操作

可以通过名称包含其他脚本。

ACTION: build # default environment or
ACTION: pipelines:build # if it's in an environment

与“包含其他脚本”相比的好处是您通常不需要处理绝对或相对路径。

包括其他脚本

在一行前加上 INCLUDE: ，将处理该行的剩余部分作为要在此处包含和执行的其他脚本的路径。

INCLUDE: my/sub/script.sh

如果路径是相对的，PSH 将尝试相对于当前脚本的位置或相对于配置文件的位置加载脚本。

按需模板

在一行前加上 TEMPLATE: 将触发按需模板创建。该行的剩余部分应如下所示：SOURCE_PATH:DESTINATION_PATH

TEMPLATE: ../templates/template.ini.tpl:../destination/template.ini

注意，这里的所有路径都必须相对于脚本位置。

将执行推迟到后台

在后台执行脚本，因此以下命令会立即执行

D: php generate_some_things.php

等待所有推迟的命令执行

如果您想等待所有结果，只需在其中添加一个 WAIT。

WAIT:

打开到另一台机器的ssh连接

许多 DevOps 脚本会打开一个 SSH 通道到本地运行的虚拟机/容器或远程的测试系统。如果您通过 PSH 做这件事，您必须在行前加上 TTY:

TTY: vagrant ssh

如果语句出错则忽略

与您通常的 shell 脚本不同，对于 PSH 来说，一个 sh 语句是否失败很重要。如果您需要它忽略错误，您必须在该行前加上 I:

I: rm -R sometimes/there

将语句拆分为多行

如果单个 shell 语句太长，不适合一行，您可以在 PSH 中将其断开，并在下一行缩进三个空格。PSH 然后将它在执行之前连接起来，并一次性执行。

bin/phpunit
    --debug
    --verbose

描述

您可以为脚本添加描述，当显示命令列表时将打印出来。

#!/usr/bin/env bash
#DESCRIPTION: My useful comment.

缺点

export 语句和内部变量不起作用，因为这些语句 不再共享单个环境。
改变脚本流程的语句默认不工作。

BASH脚本

PSH 允许您直接执行 bash 脚本。上述描述的 PSH-Scripts 的大多数功能在此运行时部分不起作用，但占位符的使用仍然可行且受到鼓励。

因此，如果您有希望 PSH 直接执行的 Bash 脚本，请在 shebang 后添加第二行

#!/usr/bin/env bash
# <PSH_EXECUTE_THROUGH_CMD>

FOO="BAR"

echo $PWD
echo $FOO
echo __PLACEHOLDER__

# <PSH_EXECUTE_THROUGH_CMD> 将建议 PSH 通过您的当前操作系统执行脚本。

注意：PSH 是为了安全性和可预测性而编写的，因此如果忘记在脚本开头添加 set -euo pipefail，它将警告您。

内部

只有当存在占位符时，PSH 才会在同一目录内创建一个隐藏文件并将其标记为可执行，请确保您的环境允许这样做。
PSH 的未来版本将将其更改为要求 PSH-Scripts 有特殊的 shebang 行，请留意这一点（例如 #!/usr/bin/env psh）。

执行它

一般格式是 ./psh.phar <application-options> <script-names> <script-options>。目前唯一支持的应用程序选项是 --no-header，脚本名称是逗号分隔的动作列表（或一个）和脚本选项是键值对，用于覆盖占位符。让我们看看一些例子

执行 phar 将打印所有可用命令的列表

> ./psh.phar

###################
Available commands:

	- build
	- unit

2 script(s) available

第一个参数总是脚本名称。例如，这将执行单元脚本

> ./psh.phar unit

###################
Starting Execution of 'unit' ('actions/unit.sh')


(1/3) Starting
> bin/php-cs-fixer fix
	You are running php-cs-fixer with xdebug enabled. This has a major impact on runtime performance.
	
	Loaded config from "/var/www/swag/psh/.php_cs".
	
	[....]

您可以通过逗号分隔脚本来添加要执行的更多命令

> ./psh.phar unit,build #executes both scripts in order

您可以为您的 .sh 文件添加替换占位符的参数，如下所示示例

    ./psh.phar unit --param someValue  #or
    ./psh.phar unit --param=someValue --otherParam value --onMoreParam=value ...
    ./psh.phar list --add -l

在您的 .sh 文件中编写。

    ls __ADD__

执行

    ls -l

Bash自动完成

Bash 自动完成仅由 PSH-Global 提供。这将安装一个全局脚本，它将获取您项目中的 psh.phar 文件，并为您安装自动完成。

shopware / psh

维护者

详情