Root file and shebang

This document explains how to make Castor to use a custom root file and how to leverage shebang lines for direct script execution.

Using a custom root file

By default, castor looks for a castor.php or .castor/castor.php file in the current working directory or one of its parents.

However, you can use another root file by using the --castor-file option:

castor --castor-file=path/to/your-file.php your-task

The root directory then follows that file instead of the directory you started Castor from, so its own remote imports are read from the castor.composer.json sitting next to it, and installed in its own .castor/vendor. When the file lives in a .castor directory, the root is the directory holding it, just like for a regular .castor/castor.php.

The working directory of the context is left alone: the tasks still run where you started Castor from. Pointing at another entrypoint tells Castor where to read the tasks from, not where to run them.

Using a shebang line

Unix systems support shebang lines to execute scripts directly from the command line, without having to prefix them with the interpreter.

The --castor-file option makes it possible to create a Castor file that can be executed directly. For example, you can create a file named my-script with the following content:

#!/usr/bin/env -S castor --castor-file
<?php

\defined('CASTOR_USE_CHDIR') || \define('CASTOR_USE_CHDIR', true);

use Castor\Attribute\AsTask;

use function Castor\io;

#[AsTask()]
function shebangTask(): void
{
    io()->writeln('Hello from shebang task!');
}

Make sure to give execute permissions to your script:

chmod +x my-script

Now, you can run your script directly from the command line:

./my-script shebang-task