README

Automate anything with PHP. Simply. Efficiently. Elegantly.

🚀 TL;DR

Castor is a lightweight, modern task runner for PHP.
No need for Bash, Makefiles or YAML.
Write your automation scripts in PHP, run them from the CLI.

✅ 100% PHP — define tasks as simple PHP functions
⚡ Fast & native — no configuration, no boilerplate
🔧 Provided with a bunch of useful built-in functions
🧠 Autocompletion & descriptions for each task
🧰 Easy to integrate in your dev workflows

🤓 Presentation

Castor is a DX-oriented task runner built in PHP featuring a range of functions for common task processing.

It can be viewed as an alternative to Makefile, Fabric, Invoke, Shell scripts, etc., but it leverages PHP's scripting capabilities and extensive library ecosystem.

It comes with many features to make your life easier:

Seamless parsing of arguments and options, simplifying input handling
Autocomplete support for faster and error-free typing
A built-in list of useful functions:
- run(): Run external processes, enabling seamless integration with external tools
- io(): Display beautiful output and interacts with the terminal
- watch(): Watch files and automatically triggers actions on file modifications
- fs(): Create, remove, and manipulate files and directories
- And even more advanced functions

Note

Castor is still in early development, and the API is not stable yet. Even if it is unlikely, it is still possible that it will change in the future.

🧑‍🔬 Usage

In Castor, tasks are set up as typical PHP functions marked with the #[AsTask()] attribute in a castor.php file.

These tasks can run any PHP code but also make use of various functions for standard operations that come pre-packaged with Castor.

For example:

<?php

namespace greetings;

use Castor\Attribute\AsTask;
use function Castor\io;

#[AsTask()]
function hello(): void
{
    io()->writeln('Hello from castor');
}

Will expose a greetings:hello task that you can run with castor greetings:hello:

$ castor greetings:hello
Hello from castor

Then, you can go wild and create more complex tasks:

#[AsTask(description: 'Clean the infrastructure (remove container, volume, networks)')]
function destroy(bool $force = false)
{
    if (!$force) {
        io()->warning('This will permanently remove all containers, volumes, networks... created for this project.');
        io()->comment('You can use the --force option to avoid this confirmation.');

        if (!io()->confirm('Are you sure?', false)) {
            io()->comment('Aborted.');

            return;
        }
    }

    run('docker-compose down -v --remove-orphans --volumes --rmi=local');

    notify('The infrastructure has been destroyed.')
}

If you want to read more about usage, you can read the basic usage documentation, or watch some examples.

🧰 Get started in 10 seconds

curl "https://castor.jolicode.com/install" | bash

castor

There are also others ways to install Castor, see the installation documentation.

📚 Want more?

Discover more by reading the docs:

jolicode / castor

Maintainers

Details