Shopware’s psh.phar Command Line Tool

Most software projects of any significant size start to accumulate shell scripts. These small programs automate tasks. These tasks can be anything from installing the platform for use to working on the core platform’s code.

In some projects this is as simple as a top level ./bin folder that contains all the necessary scripts. Other projects us formal systems to organize these scripts. The grandparent of all these systems is probably GNU Make and its ubiquitous (and byzantine) Makefiles.

With web frameworks, it’s more common for there to be a standard alone command runner — the rails CLI, Laravel’s artisan command, Django’s django-admin, etc. These programs are most often implemented in the language of the project itself. The rails CLI runs ruby programs, the artisan CLI runs PHP programs, and the django-admin runs python programs.

Shopware lives this part of its life a little off the beaten path and splits the difference with its psh.phar tool.

PHP Shell Runner

If you start working with Shopware’s platform you’ll eventually see command invocations using the psh.phar tool.

% ./psh.phar

###################

SHOPWARE Developer Version

       _
      | |
   ___| |__   ___  _ ____      ____ _ _ __ ___
  / __| '_ \ / _ \| '_ \ \ /\ / / _` | '__/ _ \
  \__ \ | | | (_) | |_) \ V  V / (_| | | |  __/
  |___/_| |_|\___/| .__/ \_/\_/ \__,_|_|  \___|
                  | |
                  |_|

Using .psh.yaml.dist


Available commands:

//... command snip ...

Your first instinct might be that this is a command-runner created with the Symfony console framework.

It is not.

Your second instinct might be that this is a stand-alone command-runner, similar to pestle, drush, or wp-cli that contains commands implemented in PHP.

It is not this either.

The psh.phar program, while developed by Shopware engineers, is a stand-alone project that can be used independently from Shopware. This command organizes, runs, and extends unix shell scripts. When you run psh.phar it will look for a .psh.yaml or .psh.yaml.dist configuration file. This configuration file tells psh.phar where to find its shell scripts.

This might be easiest to explain with an example.

Hello psh.phar

Let’s say you have a simple hello world shell script in a folder named bin

% mkdir bin
% touch bin/hello.sh
% chmod +x bin/hello.sh

that looks like this

#!/bin/bash
# File: bin/hello.sh
echo "Hello World"

Running the program should look like this

% ./bin/hello.sh
Hello World

At the root of this project, you also have the psh.phar command (if you need to install this phar archive, check the project README.md).

If you run this command you’ll get an error

% ./psh.phar

Fatal error: Uncaught RuntimeException: No config file found, make sure you have created a .psh file in phar:///private/tmp/working/psh.phar/src/Config/ConfigFileFinder.php:38
Stack trace:

Without a configuration file, psh.phar doesn’t know what to do.

However, if you create a .psh.yaml configuration file, and configure the ./bin folder in its paths section

# File: ./psh.yaml
paths:
    - ./bin

you’ll be able to see the hello command in the default namespace/hierarchy.

% ./psh.phar

###################
Using .psh.yaml

Available commands:


default:
 - hello

1 script(s) available

and in turn, run the command.

% ./psh.phar hello
./psh.phar hello

###################
Using .psh.yaml

Starting Execution of 'hello' ('/private/tmp/working/./bin/hello.sh')


(1/1) Starting
> echo "Hello World"
    Hello World

Duration: 1s
All commands successfully executed!

You can also create command hierarchies by using the environments section of the configuration files. A .psh.yaml file like this

environments:
    foo:
        paths:
            - ./bin

will give you a top level foo namespace/hierarchy for your command

% ./psh.phar foo:hello

###################
Using .psh.yaml

Starting Execution of 'foo:hello' ('/private/tmp/working/./bin/hello.sh')


(1/1) Starting
> echo "Hello World"
    Hello World

Duration: 1s
All commands successfully executed!

Finally — psh.phar is more just just a shell runner. When you run your commands via psh.phar there’s extra features available to your shell script. Covering these features is beyond the scope of this primer, but the project README is a good starting point for learning more about these features.

Wrap Up

With psh.phar, any shell script can be added to a project’s command line runner, not just commands implemented in a project’s primary language. Some folks like to say that after the world ends all we’ll have is cockroaches and a pile of bash scripts. If that’s the case psh.phar will have you and your team ready to face and organize their post-apocalyptic challenges.