README

The library behind ramsey/devtools, allowing for extension of the ramsey/devtools Composer plugin.

About

This library is what powers the ramsey/devtools Composer plugin. Since you can't extend Composer plugins, this exists to allow for extension. If you don't need to extend this for your own plugin needs, and you want the functionality provided by the plugin, check out ramsey/devtools instead.

This package also provides the devtools CLI tool, which you may use even if you do not want to use the plugin functionality.

This project adheres to a code of conduct. By participating in this project and its community, you are expected to uphold this code.

Installation

Install this package with Composer.

composer require --dev ramsey/devtools-lib

Usage

If using this library as a standalone tool, and not as a Composer plugin, type ./vendor/bin/devtools list to see the list of commands this library provides.

./vendor/bin/devtools list

Note

Install ramsey/devtools, instead, if you do not need to extend this library to create your own Composer plugin.

Extending or Overriding ramsey/devtools-lib Commands

Maybe the commands ramsey/devtools-lib provides don't do everything you need, or maybe you want to replace them entirely. The configuration allows you to do this!

Using the ramsey/devtools.commands property in the extra section of composer.json, you may specify any command (without your custom prefix, if you've configured one) as having other scripts to run, in addition to the command's default behavior, or you may override the default behavior entirely.

Tip

If you don't want to use the property name "ramsey/devtools," you may use "devtools" instead. However, if there is a conflict with another package that uses the extra.devtools property, extra.ramsey/devtools takes precedence, so you may use it to avoid conflicts.

Specifying additional scripts works exactly like writing custom commands in composer.json, but the location is different. Everything you can do with a custom Composer command, you can do here because they're the same thing.

{
    "extra": {
        "ramsey/devtools": {
            "command-prefix": "my-prefix",
            "commands": {
                "lint:all": {
                    "script": "@mylint"
                },
                "test:all": {
                    "script": [
                        "@mylint",
                        "@phpbench"
                    ]
                }
            }
        }
    },
    "scripts": {
        "mylint": "parallel-lint src tests",
        "phpbench": "phpbench run"
    }
}

In this way, when you run ./vendor/bin/devtools lint:all or ./vendor/bin/devtools test:all, it will execute the default behavior first and then run your additional commands. To override the default behavior so that it doesn't run at all and only your scripts run, specify the override property and set it to true.

{
    "extra": {
        "ramsey/devtools": {
            "commands": {
                "lint:all": {
                    "override": true,
                    "script": "parallel-lint src tests"
                }
            }
        }
    }
}

Contributing

Contributions are welcome! To contribute, please familiarize yourself with CONTRIBUTING.md.

Coordinated Disclosure

Keeping user information safe and secure is a top priority, and we welcome the contribution of external security researchers. If you believe you've found a security issue in software that is maintained in this repository, please read SECURITY.md for instructions on submitting a vulnerability report.

Copyright and License

The ramsey/devtools-lib library is copyright © Ben Ramsey and licensed for use under the terms of the MIT License (MIT). Please see LICENSE for more information.