README

A composer plugin to manage shell dependencies.

How it works

The plugin generates an autoloader for shell scripts in shell packages, which then needs to be sourced (included) in the entry point of the shell script where we want to use the dependencies.

This is exactly what happens with PHP packages.

To generate the shell autoloader, it loops throuygh all packages and for each shell package it searches all shell scripts and adds them to the shell autoloader.

How to use

Except for the following, everything works the same way as with PHP projects.

On the project that depends on shell packages

Install and allow the plugin

composer require "hgraca/composer-shell-plugin"

{
  "name": "hgraca/some-project",
  "type": "project",
  "require": {
    "hgraca/composer-shell-plugin": "dev-main"
  },
  "config": {
    "allow-plugins": {
      "hgraca/composer-shell-plugin": true
    }
  }
}

Include the autoloader in your script entry point

#!/usr/bin/env bash

# The "VENDOR_PATH" variable MUST be defined, as the autoloader depends on it,
# because there is no posix compliant way to infer this.
VENDOR_PATH="..."
. "${VENDOR_PATH}/autoload.sh"

# call the functions in the installed projects

On the shell packages

Flag a project as being a shell project/library

In the composer.json of a shell package, set the package type as a shell-project or shell-library.

For example:

{
  "name": "hgraca/dummy-shell-project-2",
  "type": "shell-library",
  "description": "A project to manually test the composer-shell-plugin plugin by being installed in another project."
}

A working example

For a working example, please check tests/PluginTestPlayground.

Feel free to run:

composer -d tests/PluginTestPlayground/TestProject install
tests/PluginTestPlayground/TestProject/bin/run.sh

Define the folders with shell scripts (optional)

In the composer.json of a shell package, in extra.hgraca/composer-shell-plugin.source-folders set the list of folders with shell scripts that should be added to the autoloader.

This is optional, by default the src folder will be used for this effect.

For example:

{
    "name": "hgraca/dummy-shell-project-1",
    "type": "shell-library",
    "description": "A project to manually test the composer-shell-plugin plugin by being installed in another project.",
    "extra": {
        "hgraca/composer-shell-plugin": {
            "source-folders": [
                "src",
                "lib"
            ]
        }
    }
}

How to run

Using local PHP (8.2):

Install the dependencies with composer install;
The recipe can be run with composer run-app;
The tests can be run with composer test;
To list all custom scripts run composer run-script --list.

Using Docker:

Change PHP and xdebug configs in ./build;
Install the dependencies with docker compose -f ./build/docker-compose.yaml run app composer install;
The recipe can be run with docker compose -f ./build/docker-compose.yaml run app composer run-app;
The tests can be run with composer docker-test;
To list all custom scripts run docker compose -f ./build/docker-compose.yaml run app composer run-script --list.

Other commands

composer git-bundle: create a git bundle
git clone -b main composer-shell-plugin.gitbundle composer-shell-plugin: recreate the repository from the git bundle

Author

Herberto Graca

hgraca / composer-shell-plugin

Maintainers

Details