piotrpress / composer-setuper
This Composer plugin allows realizing full setup process (also interactively) of your project according to defined steps.
Installs: 5
Dependents: 1
Suggesters: 0
Security: 0
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Type:composer-plugin
Requires
- php: >=7.4
- composer-plugin-api: ^2.0
Requires (Dev)
- composer/composer: ^2.0
This package is auto-updated.
Last update: 2025-03-28 19:30:50 UTC
README
This Composer plugin allows realizing full setup process (also interactively) of your project according to defined steps.
Usage example
Take a look at extra.setup section in composer.json file of the WordPress Plugin Template project.
Installation
Setuper can be simply required like a regular dependency package or can be installed like a global plugin.
Project dependency
- Add Setuper as project dependency:
$ composer require piotrpress/composer-setuper
- Allow plugin execution:
$ composer config allow-plugins.piotrpress/composer-setuper true
Global dependency
- Add command as a global dependency:
$ composer global require piotrpress/composer-setuper
- Allow plugin execution:
$ composer config -g allow-plugins.piotrpress/composer-setuper true
Defining setup
Actions
Actions are setup steps that are firing during the Composer execution process.
You can define actions in composer.json extra property as an array of objects in setup property e.g.:
{
"extra": {
"setup": [
{
"action": "write",
"message": "Hello world!"
}
]
}
}
Setup can also be a PHP callback (defined as a static method) e.g.:
{
"extra": {
"setup": "MyVendor\\MyClass::setup"
}
}
namespace MyVendor; class MyClass { static public function setup() { return [ [ 'action' => 'write', 'message' => 'Hello world!' ] ]; } }
Single action can also be a PHP callback (defined as a static method) e.g.:
{
"extra": {
"setup": [
{
"action": "write",
"message": "Hello"
},
"MyVendor\\MyClass::writeWorld"
]
}
}
namespace MyVendor; class MyClass { static public function writeWorld() { return [ 'action' => 'write', 'message' => 'world!' ]; } }
NOTE: PHP classes containing defined callbacks must be autoloadable via Composer's autoload functionality.
Events
Actions are triggered by events.
{
"extra": {
"setup": [
{
"action": "write",
"message": "Hello world!",
"event": "post-update-cmd"
}
]
}
}
If you don't specify the event for the action, then it'll be assigned to setup script, which you can use in composer.json scripts property e.g.:
{
"scripts": {
"post-update-cmd": "@setup"
}
}
You can also run it manually from command line:
$ composer run setup
Priorities
Actions calls within an event are sorted by priority.
By default, the priority of an action is set to 0.
Higher value represent higher priorities.
{
"extra": {
"setup": [
{
"action": "write",
"message": "world!"
},
{
"action": "write",
"message": "Hello",
"priority": 1
}
]
}
}
Input / Output actions
The most powerfull and common usage feature of Setuper is interactively communicating with the user due setup process.
Setuper can taking users inserted values using insert, secret, select or confirm actions and sets the variables for future reference in other (e.g. filesystem manipulation) actions.
Set
Sets value to variable for future reference.
{
"action": "set",
"variable": "greeting",
"value": "Hello world!"
}
Parameters
variable-required|string- name of the variable following the PHP naming rules.value-required|mixed- value of the variable.
Insert
Sets value to variable passed by the user.
{
"action": "insert",
"variable": "greeting",
"message": "Insert your greeting:"
}
Parameters
variable-required|string- name of the variable following the PHP naming rules.message-required|string- outputs message for the user to the console.required-optional|boolean- whether the value is required or not.validator-optional|collable|collable[]- the PHP callback (defined as a static method)default-optional|string- the default value if none is given by the user.
NOTE: insert action uses ask() function from Symfony Console component, so for detailed info (e.g. how validating the value) check out the documentation.
Secret
Sets value to variable passed by the user.
{
"action": "secret",
"variable": "password",
"message": "Insert your password:"
}
Parameters
variable-required|string- name of the variable following the PHP naming rules.message-required|string- outputs message for the user to the console.
Select
Sets value to variable passed by the user.
{
"action": "select",
"variable": "color",
"message": "Select your favourite color:",
"choices": [ "red", "green", "blue" ]
}
Parameters
variable-required|string- name of the variable following the PHP naming rules.message-required|string- outputs message for the user to the console.choices-required|string[]- an array of choices.default-optional|string- the default value if none is given by the user.error-optional|string- the error message if the value is not in the choices array.multiple-optional|boolean- whether the user can select multiple choices or not.
Confirm
Sets value to variable passed by the user.
{
"action": "confirm",
"variable": "help",
"message": "Can I help you?"
}
Parameters
variable-required|string- name of the variable following the PHP naming rules.message-required|string- outputs message for the user to the console.default-optional|boolean- the default value if none is given by the user.
Write
Outputs single or multiple lines message to the console.
{
"action": "write",
"message": "Hello world!"
}
Parameters
message-required|string|string[]- the message as a single string or an array of lines.verbose-optional|string- one of the verbosity level:quiet,normal,verbose,very_verbose,debug
NOTE: write action uses writeln() function from Symfony Console component, so for detailed info (e.g. how to color and style the message) check out the documentation.
Filesystem actions
Directory
Creates a directory.
{
"action": "directory",
"path": "src"
}
Parameters
path-required|string|string[]- path to the directory. An array may be used to designate multiple directories.
Symlink
Creates a symbolic link.
{
"action": "symlink",
"source": "src",
"target": "inc"
}
Parameters
source-required|string|string[]- path to the source directory. An array may be used to designate multiple directories.target-required|string|string[]- path to the target directory. An array may be used to designate multiple directories.
Rename
Renames a file or directory.
{
"action": "rename",
"source": "src/hello.php",
"target": "src/hi.php"
}
Parameters
source-required|string|string[]- path to the source file or directory. An array may be used to designate multiple files or directories.target-required|string|string[]- path to the target file or directory. An array may be used to designate multiple files or directories.
Copy
Copies a file or directory.
{
"action": "copy",
"source": "src/hello.php",
"target": "inc/hello.php"
}
Parameters
source-required|string|string[]- path to the source file or directory. An array may be used to designate multiple files or directories.target-required|string|string[]- path to the target file or directory. An array may be used to designate multiple files or directories.
Move
Moves a file or directory.
{
"action": "move",
"source": "src/hello.php",
"target": "inc/hello.php"
}
Parameters
source-required|string|string[]- path to the source file or directory. An array may be used to designate multiple files or directories.target-required|string|string[]- path to the target file or directory. An array may be used to designate multiple files or directories.
Remove
Removes a file or directory.
{
"action": "remove",
"path": "src/hello.php"
}
Parameters
path-required|string|string[]- path to the file or directory. An array may be used to designate multiple files or directories.
Owner
Changes the owner of a file or directory.
{
"action": "owner",
"path": "src/hello.php",
"owner": "www-data"
}
Parameters
path-required|string|string[]- path to the file or directory. An array may be used to designate multiple files or directories.owner-required|string|string[]- the owner value. An array may be used to designate multiple owners.
Group
Changes the group of a file or directory.
{
"action": "group",
"path": "src/hello.php",
"group": "www-data"
}
Parameters
path-required|string|string[]- path to the file or directory. An array may be used to designate multiple files or directories.group-required|string|string[]- the group value. An array may be used to designate multiple groups.
Mode
Changes the mode of a file or directory.
{
"action": "mode",
"path": "src/hello.php",
"mode": "0755"
}
Parameters
path-required|string|string[]- path to the file or directory. An array may be used to designate multiple files or directories.mode-required|string|string[]- the mode value. An array may be used to designate multiple modes.
File content actions
Dump
Dump the content to the file.
{
"action": "dump",
"content": "<?= 'Hello world!';",
"file": "src/hello.php"
}
Parameters
content-required|string|string[]- the content being written. An array may be used to designate multiple contents.file-required|string|string[]- path to file where the content will be written. An array may be used to designate multiple files.
Append
Append the content to the file.
{
"action": "append",
"content": "<?= 'Hello world!';",
"file": "src/hello.php"
}
Parameters
content-required|string|string[]- the content being appended. An array may be used to designate multiple contents.file-required|string|string[]- path to file where the content will be appended. An array may be used to designate multiple files.
Replace
Replace all occurrences of the pattern with the replacement string in file content.
{
"action": "replace",
"pattern": "/Hello world!/i",
"replace": "Hi world!",
"file": "src/**/*.php"
}
Parameters
pattern-required|string|string[]- the pattern being searched for. An array may be used to designate multiple patterns.replace-required|string|string[]- the replacement value that replaces found search values. An array may be used to designate multiple replacements.file-required|string|string[]- path to file where the replacement will be made. An array may be used to designate multiple files. You can use*to match any string, or**to match any string that spans directories.
NOTE: Replace action uses preg_replace() and Symfony Finder Component, so for detailed info check out the documentation.
Requirements
- PHP > =
7.4 - Composer >=
2.0