Castor

https://github.com/jolicode/castor
Admin
Castor is a lightweight PHP-based task runner for automation, CI/CD, and DevOps that allows you to...
Tokens:106,589
Snippets:953
Trust Score:10
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Determine Composer global bin directory

Source: https://github.com/jolicode/castor/blob/main/doc/installation/alternative-methods.md

Shows the command to find the Composer global home directory, with example output on some Linux systems. The output may vary by operating system.

```console
$ composer config --list --global | grep -F "[home]"

# It may looks like this on some Linux systems:
# [home] /home/<your_username>/.config/composer
# Or like this too:
# [home] /home/<your_username>/.composer
```

--------------------------------

### Install Castor via CLI

Source: https://github.com/jolicode/castor/blob/main/README.md

Use the curl command to install Castor and verify the installation by running the castor command.

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

castor
```

--------------------------------

### Install Castor with setup-php action

Source: https://github.com/jolicode/castor/blob/main/doc/installation/github-action.md

Uses the shivammathur/setup-php action to install both a specific PHP version and Castor by specifying it in the tools option.

```yaml
jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v5

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
          tools: castor

      - name: Run castor "hello" task
        run: castor hello
```

--------------------------------

### Install Castor with setup-castor action

Source: https://github.com/jolicode/castor/blob/main/doc/installation/github-action.md

Uses the official castor-php/setup-castor action to install Castor via a static binary, eliminating the need for a pre-installed PHP environment on the runner.

```yaml
jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v5

      - name: Setup castor
        uses: castor-php/setup-castor@v1.0.0

      - name: Run castor "hello" task
        run: castor hello
```

--------------------------------

### Run simple task

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/basic-usage.md

Executes the `hello` task defined in the previous example. Outputs 'Hello from castor.'

```console
$ castor hello
Hello from castor.

```

--------------------------------

### Install PHPStan

Source: https://github.com/jolicode/castor/blob/main/CONTRIBUTING.md

Install the PHPStan static analysis tool dependencies from the project root directory.

```bash
composer install --working-dir=tools/phpstan
```

--------------------------------

### Install Castor with mise

Source: https://github.com/jolicode/castor/blob/main/doc/installation/alternative-methods.md

Installs the static binary from the releases page using mise. The matching_regex option selects the static binary instead of the phar, and the bin option exposes it as castor. Drop --global to pin Castor in the project's mise.toml.

```bash
mise use --global 'github:jolicode/castor[matching_regex=^castor\.[a-z]+-[a-z0-9]+(\.exe)?$,bin=castor]'
```

--------------------------------

### Install Castor snapshot build

Source: https://github.com/jolicode/castor/blob/main/doc/installation/installer.md

Installs a snapshot pre-release from the main branch to try upcoming features. Snapshot versions look like v1.7.0-14-g4531440. Note that right after a push, the installer may still get the previous snapshot for a few minutes due to GitHub caching.

```bash
curl "https://castor.jolicode.com/install" | bash -s -- --version=snapshot
```

--------------------------------

### Install Castor static binary on macOS with Intel

Source: https://github.com/jolicode/castor/blob/main/doc/installation/alternative-methods.md

Downloads the Castor static binary for macOS with Intel and installs it to /usr/local/bin. The command verifies the installation with castor --version and reports an error if the target directory is not writable.

```bash
curl "https://github.com/jolicode/castor/releases/latest/download/castor.darwin-amd64" -Lfso /usr/local/bin/castor && \
    chmod u+x /usr/local/bin/castor && \
    castor --version || \
    (echo "Could not install castor. Is the target directory writeable?" && (exit 1))
```

--------------------------------

### Manual Installation via Git

Source: https://github.com/jolicode/castor/blob/main/doc/installation/alternative-methods.md

Clone the Castor repository, install dependencies with Composer, and create a symlink to the castor binary in your PATH.

```bash
cd $HOME/somewhere
git clone git@github.com:jolicode/castor.git
cd castor
composer install
ln -s $PWD/bin/castor $HOME/.local/bin/castor
```

--------------------------------

### Project architecture example

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/extending-castor/mount.md

Shows the directory structure for mounting multiple Castor applications.

```text
projects/
├─ A/
│  ├─ castor.php
├─ B/
│  ├─ castor.php
castor.php
```

--------------------------------

### Install Castor static binary on Windows

Source: https://github.com/jolicode/castor/blob/main/doc/installation/alternative-methods.md

Downloads the Castor static binary for Windows and saves it as castor.exe in a directory that is in your PATH. Replace <a directory in your PATH> with an actual directory.

```bash
curl.exe "https://github.com/jolicode/castor/releases/latest/download/castor.windows-amd64.exe" -Lso C:\<a directory in your PATH>\castor.exe
```

--------------------------------

### Install Castor with --install-dir option

Source: https://github.com/jolicode/castor/blob/main/doc/installation/installer.md

Installs Castor into a custom directory instead of the default $HOME/.local/bin. Replace /usr/local/bin with your desired path.

```bash
curl "https://castor.jolicode.com/install" | bash -s -- --install-dir /usr/local/bin
```

--------------------------------

### Verbose mode download progress output

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/http-request.md

Example of the logs and progress indicator displayed when running http_download() in verbose mode.

```text
18:55:09 INFO      [castor] Filename determined for http download ["filename" => "100MB-speedtest","url" => "http://eu-central-1.linodeobjects.com/speedtest/100MB-speedtest"]
18:55:11 INFO      [castor] Download progress: 29.72 MB/100.00 MB (29.72%) at 18.40 MB/s, ETA: 3s ["url" => "http://eu-central-1.linodeobjects.com/speedtest/100MB-speedtest"]
18:55:13 INFO      [castor] Download progress: 74.94 MB/100.00 MB (74.94%) at 20.73 MB/s, ETA: 1s ["url" => "http://eu-central-1.linodeobjects.com/speedtest/100MB-speedtest"]
18:55:14 INFO      [castor] Download progress: 100.00 MB/100.00 MB (100.00%) at 20.69 MB/s, ETA: 0s ["url" => "http://eu-central-1.linodeobjects.com/speedtest/100MB-speedtest"]
18:55:14 INFO      [castor] Download finished ["url" => "http://eu-central-1.linodeobjects.com/speedtest/100MB-speedtest","filePath" => "/www/castor/100MB-speedtest","size" => "100.00 MB"]
```

--------------------------------

### Configure PHPStan to scan Castor stubs

Source: https://github.com/jolicode/castor/blob/main/doc/installation/index.md

Adds the generated .castor.stub.php file to the scanFiles section of a phpstan.neon configuration so PHPStan recognizes Castor classes and functions. The file is created automatically on first run and should be gitignored.

```neon
parameters:
    # ...
    scanFiles:
        - .castor.stub.php

```

--------------------------------

### Install Castor with the official installer

Source: https://github.com/jolicode/castor/blob/main/doc/installation/installer.md

Installs Castor on Linux or macOS using the official installer. Requires PHP >= 8.2 because it installs a phar. The installer places Castor in $HOME/.local/bin by default.

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

--------------------------------

### Persist CASTOR_GENERATE_STUBS in shell configuration

Source: https://github.com/jolicode/castor/blob/main/doc/installation/index.md

Exports the CASTOR_GENERATE_STUBS=0 variable in ~/.bashrc and sources it so the setting persists across shell sessions.

```bash
echo 'export CASTOR_GENERATE_STUBS=0' >> ~/.bashrc
source ~/.bashrc

```

--------------------------------

### Install Castor with --static option

Source: https://github.com/jolicode/castor/blob/main/doc/installation/installer.md

Installs Castor as a static binary that embeds PHP, so PHP does not need to be installed on the system. Use this option when PHP is not available.

```bash
curl "https://castor.jolicode.com/install" | bash -s -- --static
```

--------------------------------

### Install Castor static binary on macOS with Apple Silicon

Source: https://github.com/jolicode/castor/blob/main/doc/installation/alternative-methods.md

Downloads the Castor static binary for macOS with Apple Silicon and installs it to /usr/local/bin. The command verifies the installation with castor --version and reports an error if the target directory is not writable.

```bash
curl "https://github.com/jolicode/castor/releases/latest/download/castor.darwin-arm64" -Lfso /usr/local/bin/castor && \
    chmod u+x /usr/local/bin/castor && \
    castor --version || \
    (echo "Could not install castor. Is the target directory writeable?" && (exit 1))
```

--------------------------------

### Install Castor phar on macOS with Intel

Source: https://github.com/jolicode/castor/blob/main/doc/installation/alternative-methods.md

Downloads the macOS Intel phar from the latest release and installs it to /usr/local/bin/castor. The command checks the installation with castor --version and prints an error if the target directory is not writable.

```bash
curl "https://github.com/jolicode/castor/releases/latest/download/castor.darwin-amd64.phar" -Lfso /usr/local/bin/castor && \
    chmod u+x /usr/local/bin/castor && \
    castor --version || \
    (echo "Could not install castor. Is the target directory writeable?" && (exit 1))
```

--------------------------------

### Example of repeating workingDirectory with import()

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/extending-castor/mount.md

Shows the repetitive pattern of setting the working directory manually, which mount() avoids.

```php
use Castor\Attribute\AsTask;

use function Castor\context;
use function Castor\run;

#[AsTask()]
function foobar() {
    run($command, context: context()->withWorkingDirectory(__DIR__));
}
```

--------------------------------

### Install PHP CS Fixer

Source: https://github.com/jolicode/castor/blob/main/CONTRIBUTING.md

Install the PHP CS Fixer tool dependencies from the project root directory.

```bash
composer install --working-dir=tools/php-cs-fixer
```

--------------------------------

### Install Castor static binary on Linux ARM64

Source: https://github.com/jolicode/castor/blob/main/doc/installation/alternative-methods.md

Downloads the Castor static binary for Linux ARM64 and installs it to $HOME/.local/bin. The command verifies the installation with castor --version and reports an error if the target directory is not writable.

```bash
curl "https://github.com/jolicode/castor/releases/latest/download/castor.linux-arm64" -Lfso $HOME/.local/bin/castor && \
    chmod u+x $HOME/.local/bin/castor && \
    castor --version || \
    (echo "Could not install castor. Is the target directory writeable?" && (exit 1))
```

--------------------------------

### Add Composer global bin to PATH

Source: https://github.com/jolicode/castor/blob/main/doc/installation/alternative-methods.md

Appends the Composer global bin directory to your PATH. Replace /home/<your_username> with the Unix $HOME environment variable if desired. After this, any binary globally installed with Composer will work everywhere.

```bash
export PATH="$HOME/.config/composer/vendor/bin:$PATH"
```

--------------------------------

### View static autocomplete suggestions

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/interacting-with-castor/autocomplete.md

Example of shell output when pressing Tab for the defined static argument.

```console
$ castor my-task [TAB]
bar  baz  foo
```

--------------------------------

### Add extra dependencies with --deps

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/remote.md

Runs a package with additional dependencies using the `--deps` option. This example runs `phpstan/phpstan` with the `phpstan/phpstan-symfony` extension.

```bash
castor execute --deps phpstan/phpstan-symfony phpstan/phpstan
```

--------------------------------

### wait_for_port() example

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/wait-for.md

Waits for a network port to be accessible on a given host within the timeout. Customize host, timeout, quiet, interval, and message.

```php
wait_for_port(
    port: 8080,
    host: '127.0.0.1',
    timeout: 15,
    quiet: false,
    intervalMs: 500,
    message: 'Waiting for port localhost:8080 to be accessible...',
);
```

--------------------------------

### Install Castor static binary on Linux AMD64

Source: https://github.com/jolicode/castor/blob/main/doc/installation/alternative-methods.md

Downloads the Castor static binary for Linux AMD64 (x86-64) and installs it to $HOME/.local/bin. Use this binary under Windows Subsystem for Linux (WSL) instead of the Windows binary. The command checks the installation by running castor --version and prints an error if the target directory is not writable.

```bash
curl "https://github.com/jolicode/castor/releases/latest/download/castor.linux-amd64" -Lfso $HOME/.local/bin/castor && \
    chmod u+x $HOME/.local/bin/castor && \
    castor --version || \
    (echo "Could not install castor. Is the target directory writeable?" && (exit 1))
```

--------------------------------

### Install Castor phar on Linux ARM64

Source: https://github.com/jolicode/castor/blob/main/doc/installation/alternative-methods.md

Downloads the Linux ARM64 phar from the latest release and installs it to $HOME/.local/bin/castor. The command checks the installation with castor --version and prints an error if the target directory is not writable.

```bash
curl "https://github.com/jolicode/castor/releases/latest/download/castor.linux-arm64.phar" -Lfso $HOME/.local/bin/castor && \
    chmod u+x $HOME/.local/bin/castor && \
    castor --version || \
    (echo "Could not install castor. Is the target directory writeable?" && (exit 1))
```

--------------------------------

### Install a specific Castor version with --version option

Source: https://github.com/jolicode/castor/blob/main/doc/installation/installer.md

Installs a specific version of Castor instead of the latest. Replace v1.0.0 with the desired version tag.

```bash
curl "https://castor.jolicode.com/install" | bash -s -- --version=v1.0.0
```

--------------------------------

### Disable stub generation with CASTOR_GENERATE_STUBS

Source: https://github.com/jolicode/castor/blob/main/doc/installation/index.md

Sets the CASTOR_GENERATE_STUBS environment variable to 0 to prevent Castor from generating the .castor.stub.php file. Useful when you don't want stubs.

```bash
CASTOR_GENERATE_STUBS=0 castor

```

--------------------------------

### Install Castor phar on macOS with Apple Silicon

Source: https://github.com/jolicode/castor/blob/main/doc/installation/alternative-methods.md

Downloads the macOS Apple Silicon phar from the latest release and installs it to /usr/local/bin/castor. The command checks the installation with castor --version and prints an error if the target directory is not writable.

```bash
curl "https://github.com/jolicode/castor/releases/latest/download/castor.darwin-arm64.phar" -Lfso /usr/local/bin/castor && \
    chmod u+x /usr/local/bin/castor && \
    castor --version || \
    (echo "Could not install castor. Is the target directory writeable?" && (exit 1))
```

--------------------------------

### Install Castor phar on Linux AMD64

Source: https://github.com/jolicode/castor/blob/main/doc/installation/alternative-methods.md

Downloads the Linux AMD64 phar from the latest release and installs it to $HOME/.local/bin/castor. The command checks the installation with castor --version and prints an error if the target directory is not writable.

```bash
curl "https://github.com/jolicode/castor/releases/latest/download/castor.linux-amd64.phar" -Lfso $HOME/.local/bin/castor && \
    chmod u+x $HOME/.local/bin/castor && \
    castor --version || \
    (echo "Could not install castor. Is the target directory writeable?" && (exit 1))
```

--------------------------------

### Using variable() to get context variables with default

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/context.md

Retrieve a variable from the context with variable(), providing a default value. The example shows the equivalent manual access using context() and catching OutOfBoundsException.

```php
use Castor\Attribute\AsTask;

use function Castor\context;
use function Castor\variable;

#[AsTask()]
function foo(): void
{
    $foobar = variable('foobar', 'default value');

    // Same as:
    $context = context();
    try {
        $foobar = $context['foobar'];
    } catch (\OutOfBoundsException) {
        $foobar = 'default value;
    }
}
```

--------------------------------

### Pin a specific package version with :

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/remote.md

Runs a specific version of a package by appending `:version` after the package name. This example runs version 3.0 of `friendsofphp/php-cs-fixer` with the `fix` argument.

```bash
castor execute friendsofphp/php-cs-fixer:3.0 fix
```

--------------------------------

### Install Castor globally with Composer

Source: https://github.com/jolicode/castor/blob/main/doc/installation/alternative-methods.md

Installs Castor globally via Composer. This method is not recommended due to potential conflicts in the global project. After installation, ensure the Composer global bin directory is in your PATH.

```bash
composer global require jolicode/castor
```

--------------------------------

### wait_for_url() example

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/wait-for.md

Waits for a URL to be accessible by attempting to open a connection within the timeout. Accepts timeout, quiet, interval, and message parameters.

```php
wait_for_url(
    url: 'https://example.com',
    timeout: 10,
    quiet: false,
    intervalMs: 200,
    message: 'Waiting for https://example.com to be accessible...',
);
```

--------------------------------

### Simple logo file example

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/extending-castor/repack.md

A PHP file that returns a string to be used as the custom logo. Provide the absolute or relative path to this file with the --logo-file option.

```php
// repack/my-logo.php

<?php

return '❤️ My LOGO ❤️';
```

--------------------------------

### Manual fingerprint control with fingerprint_exists() and fingerprint_save()

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/fingerprint.md

Provides granular control by manually checking if a fingerprint exists and saving it after execution. This example uses a Finder instance to hash multiple JSON files.

```php
use Castor\Attribute\AsTask;
use Castor\Fingerprint\FileHashStrategy;
use function Castor\finder;
use function Castor\fingerprint_exists;
use function Castor\fingerprint_save;
use function Castor\hasher;

#[AsTask(description: 'Check if the fingerprint has changed before executing some code')]
function task_with_some_fingerprint(): void
{
    if (!fingerprint_exists('task-id', my_fingerprint_check())) {
        io()->writeln('Executing some code because fingerprint has changed.');
        fingerprint_save('task-id', my_fingerprint_check());
    }
}

function my_fingerprint_check(): string
{
    return hasher()
        ->writeWithFinder(
            finder()
                ->in(__DIR__)
                ->name('*.json')
                ->files(),
            FileHashStrategy::Content
        )
        ->finish();
}
```

--------------------------------

### wait_for_docker_container() with containerChecker

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/wait-for.md

Waits for a Docker container to be ready. Optionally provide a containerChecker callback to run a specific check; the example runs a MySQL query inside the container.

```php
wait_for_docker_container(
    containerName: 'mysql-container',
    timeout: 30,
    quiet: false,
    intervalMs: 100,
    message: 'Waiting for my-container to be ready...',
    containerChecker: function ($containerId) {
        return run("docker exec $containerId mysql -uroot -proot -e 'SELECT 1'", context: context()->withAllowFailure())->isSuccessful();
    },
);
```

--------------------------------

### Install Castor phar on Windows

Source: https://github.com/jolicode/castor/blob/main/doc/installation/alternative-methods.md

Downloads the Windows AMD64 phar from the latest release and saves it to a directory in your PATH. The command uses curl.exe and does not include a version check.

```bash
curl.exe "https://github.com/jolicode/castor/releases/latest/download/castor.windows-amd64.phar" -Lso C:\<a directory in your PATH>\castor
```

--------------------------------

### Path option autocompletion examples

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/arguments.md

Shows autocompletion suggestions for a path option with directory and filter restrictions.

```console
$ castor lint --file [TAB]
routes.yaml  services.yaml  packages/
$ castor lint --file packages/[TAB]
packages/framework.yaml  packages/security.yaml
```

--------------------------------

### Run a remote command with ssh_run()

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/ssh.md

Executes a command on a remote server via SSH. The example lists the contents of /var/www on server-1.example.com as user 'debian' on port 2222. The path is quoted for the remote shell, and a leading ~ is expanded.

```php
use Castor\Attribute\AsTask;

use function Castor\ssh_run;

#[AsTask()]
function ls(): void
{
    // List content of /var/www directory on the remote server
    ssh_run('ls -alh', host: 'server-1.example.com', user: 'debian', sshOptions: [
        'port' => 2222,
    ], path: '/var/www');
}
```

--------------------------------

### Path argument autocompletion example

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/arguments.md

Shows autocompletion suggestions for a path argument when pressing TAB.

```console
$ castor path-argument /var/www/[TAB]
/var/www/foo  /var/www/bar  /var/www/baz
```

--------------------------------

### wait_for_http_status() example

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/wait-for.md

Specialized version of wait_for_http_response() that waits until the URL returns the desired HTTP status code. Configure status, timeout, quiet, interval, and message.

```php
wait_for_http_status(
    url: 'https://example.com/api',
    status: 200,
    timeout: 10,
    quiet: false,
    intervalMs: 300,
    message: 'Waiting for https://example.com/api to return HTTP 200',
);
```

--------------------------------

### Complex logo file example

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/extending-castor/repack.md

A PHP file that returns a closure receiving the application name and version as string parameters, allowing dynamic logo content.

```php
// repack/my-complex-logo.php

<?php

return function (string $appName, string $appVersion) {
    return <<<LOGO

    ❤️ My LOGO for {$appName} in Version {$appVersion} ❤️

    LOGO;
};
```

--------------------------------

### Upload a file with ssh_upload()

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/ssh.md

Transfers a local file to a remote server via SCP. The example uploads /tmp/test.html to /var/www/index.html on server-1.example.com as user 'debian'.

```php
use function Castor\ssh_upload;

#[AsTask()]
function upload_file(): void
{
    ssh_upload('/tmp/test.html', '/var/www/index.html', host: 'server-1.example.com', user: 'debian');
}
```

--------------------------------

### Use the command builder with run()

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/extending-castor/command-builder.md

Shows how to instantiate the Ls command builder, chain the all() method, and pass it to the run() function from Castor.

```php
use CommandBuilder\Ls;
use function Castor\run;

$ls = (new Ls('/path/to/directory'))->all();
run($ls);
```

--------------------------------

### Verify Castor binary provenance with gh attestation

Source: https://github.com/jolicode/castor/blob/main/doc/installation/installer.md

Verifies the provenance of the SHA256SUMS file using GitHub CLI (2.49 or later) when installed and authenticated. The installer and self-update also verify binary provenance with gh attestation verify.

```bash
gh attestation verify SHA256SUMS --repo jolicode/castor
```

--------------------------------

### Download a file with ssh_download()

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/ssh.md

Transfers a remote file to the local machine via SCP. The example downloads /tmp/test.html from the remote server to /var/www/index.html on the local machine, connecting as user 'debian'.

```php
use function Castor\ssh_download;

#[AsTask()]
function download_file(): void
{
    ssh_download('/tmp/test.html', '/var/www/index.html', host: 'server-1.example.com', user: 'debian');
}
```

--------------------------------

### Define a simple task with arguments

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/arguments.md

All function parameters become task arguments or options. This example shows a basic task that takes two arguments and prints them.

```php
{{ php("examples/basic/arguments/simple.php") }}
```

--------------------------------

### List supported shells for completion

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/interacting-with-castor/autocomplete.md

Run this command to see instructions for other supported shells like zsh or fish.

```bash
castor completion --help
```

--------------------------------

### wait_for_http_response() with responseChecker

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/wait-for.md

Waits for a URL to return a response that satisfies a user-defined responseChecker callback. The example validates the status code and response content.

```php
wait_for_http_response(
    url: 'https://example.com',
    responseChecker: function (ResponseInterface $response) {
        return $response->getStatusCode() !== 200
        && u($response->getContent())->containsAny(['Example Domain']);
    },
    timeout: 2,
);
```

--------------------------------

### List commands with namespace, format, and raw options

Source: https://github.com/jolicode/castor/blob/main/tests/Generated/ComposerHelpTest.php.output.txt

These commands show how to use the list command. The first lists all commands, the second filters by a namespace, the third changes the output format to XML, and the fourth outputs a raw list for embedding.

```shell
castor composer list
```

```shell
castor composer list test
```

```shell
castor composer list --format=xml
```

```shell
castor composer list --raw
```

--------------------------------

### Debug the CLI selection with castor:llm:debug

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/llm.md

Run castor:llm:debug to show installed CLIs, the value of each source, the one Castor uses, and the exact command it runs. With --test, it also sends a prompt to check the CLI answers.

```bash
castor castor:llm:debug
castor castor:llm:debug --test
```

--------------------------------

### Execute a PHP or PHAR file with run_php()

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/run-php.md

Use run_php() to execute external PHP scripts or PHAR files, ensuring compatibility across different Castor installation methods.

```php
#[AsTask()]
function exec_something()
{
    run_php('path/to/my.phar', ['arg1', 'arg2']);
}
```

--------------------------------

### Using --castor-file option

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/interacting-with-castor/root-file-and-shebang.md

Use the --castor-file option to specify a custom root file instead of the default castor.php or .castor/castor.php. The root directory follows that file, affecting remote imports and vendor installation, but the working directory remains where you started Castor.

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

--------------------------------

### Run a task via CLI

Source: https://github.com/jolicode/castor/blob/main/README.md

Execute the defined hello task using the castor command.

```console
$ castor hello
Hello from castor
```

--------------------------------

### Using the context() function to get and modify context

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/context.md

Retrieve the initial context with context(), access its workingDirectory property, and create a new context with withWorkingDirectory() to change the working directory for a run() command.

```php
use Castor\Attribute\AsTask;

use function Castor\context;
use function Castor\io;
use function Castor\run;

#[AsTask()]
function foo(): void
{
    $context = context();

    io()->writeln($context->workingDirectory); // will print the directory of the castor.php file

    $context = $context->withWorkingDirectory('/tmp'); // will create a new context where the current directory is /tmp
    run('pwd', context: $context); // will print "/tmp"
}
```

--------------------------------

### Open a URL with Castor's open() function

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/open.md

Use the `open()` function inside a Castor task to open a URL in the user's default application. The example defines a task named `open` that calls `open('https://castor.jolicode.com')`.

```php
use Castor\Attribute\AsTask;

use function Castor\open;

#[AsTask()]
function open()
{
    open('https://castor.jolicode.com');
}
```

--------------------------------

### Example of variable() return types with declared ContextData

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/context.md

Shows how variable() returns precise types when the ContextData alias is declared. The types are inferred from the alias shape and the default value.

```php
$name = variable('name');                // string
$production = variable('production');    // bool
$unknown = variable('unknown', 42);      // int, inferred from the default value
```

--------------------------------

### Run a specific binary of a package with @

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/remote.md

Selects a specific binary command from a package by appending `@binary-name` after the package name. Here, it runs the `php-cs-fixer` binary with the `fix` argument.

```bash
castor execute friendsofphp/php-cs-fixer@php-cs-fixer fix
```

--------------------------------

### Update Castor to snapshot with self-update --snapshot

Source: https://github.com/jolicode/castor/blob/main/doc/installation/installer.md

Updates an existing Castor installation to the latest snapshot pre-release. To go back to the latest release, run castor self-update without --snapshot.

```bash
castor self-update --snapshot
```

--------------------------------

### Run PHPUnit tests

Source: https://github.com/jolicode/castor/blob/main/CONTRIBUTING.md

Execute the test suite using the project's PHPUnit binary.

```bash
vendor/bin/phpunit
```

--------------------------------

### Example output of named jobs in interactive terminal

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/parallel.md

Shows the interactive terminal output when named jobs finish: each job appears as a block with a spinner, duration, and last lines. Failed jobs print their full output and error after all jobs finish.

```text
✔ lint   0.9s
✘ test   failed after 1.3s
    Running the test suite
    Test 1: OK
    Test 2: OK
    Test 3: KO
⠹ build  1.5s
```

--------------------------------

### Watch multiple directories in parallel with parallel()

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/parallel.md

Use parallel() to run multiple watch() functions concurrently, each watching a different directory. The example watches 'src/...' and 'doc/...' and triggers callbacks on file changes.

```php
use Castor\Attribute\AsTask;

use function Castor\parallel;

#[AsTask()]
function parallel_change()
{
    parallel(
        function () {
            watch('src/...', function (string $file, string $action) {
                // do something on src file change
            });
        },
        function () {
            watch('doc/...', function (string $file, string $action) {
                // do something on doc file change
            });
        },
    );
}
```

--------------------------------

### Parse and dump YAML with yaml_parse() and yaml_dump()

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/yaml.md

Use when you need to read and write YAML files in a Castor task. The snippet parses a YAML file into an array with yaml_parse() and writes it back with yaml_dump(), relying on the symfony/yaml component. No additional setup is shown beyond importing the functions.

```php
use Castor\Attribute\AsTask;

use function Castor\{yaml_parse, yaml_dump};

#[AsTask()]
function yaml_parse_and_dump(): void
{
    $content = yaml_parse(file_get_contents('file.yaml'));
    
    file_put_contents('file.yaml', yaml_dump($content));
}
```

--------------------------------

### Wrap command builder in a function

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/extending-castor/command-builder.md

Recommended pattern: provide a function that creates the command builder for a closer Castor experience. The function returns an Ls instance, which can be passed to run().

```php
use CommandBuilder\Ls;

function ls(string $directory): Ls
{
    return new Ls($directory);
}

...

run(ls('/path/to/directory')->all());
```

--------------------------------

### Update Castor with self-update command

Source: https://github.com/jolicode/castor/blob/main/doc/installation/installer.md

Updates Castor to the latest version when installed via the installer (phar or static binary). Supports options --force/-f, --no-backup, and --rollback/-r. Not available for source installations or Composer project dependencies.

```bash
castor self-update
```

--------------------------------

### fs

Source: https://github.com/jolicode/castor/blob/main/doc/docs/reference.md

Returns a filesystem instance.

```APIDOC
## fs

### Description
Returns a filesystem instance.

### Usage
`fs()`

```

--------------------------------

### Basic file watching with watch()

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/watch.md

Monitors a directory for changes and executes a callback. The $action parameter indicates if the file was created, written, renamed, or removed.

```php
use Castor\Attribute\AsTask;

use function Castor\io;
use function Castor\watch;

#[AsTask()]
function watcher(): void
{
    watch('src/', function (string $file, string $action) {
        io()->writeln("File {$file} has been {$action}");
    });
}
```

--------------------------------

### Run static analysis

Source: https://github.com/jolicode/castor/blob/main/CONTRIBUTING.md

Execute PHPStan to perform static analysis checks using the specified configuration file.

```bash
tools/phpstan/vendor/bin/phpstan --configuration=phpstan.neon
```

--------------------------------

### Using fs() and Path for filesystem operations

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/filesystem.md

Demonstrates OS-independent filesystem operations with fs() and static Path methods. Checks existence, creates and removes a directory, touches a file, and tests absolute paths. Note: with CASTOR_USE_CHDIR enabled, relative paths resolve against the context working directory.

```php
use Castor\Attribute\AsTask;
use Symfony\Component\Filesystem\Path;

use function Castor\fs;
use function Castor\io;

#[AsTask()]
function foo()
{
    $dir = '/tmp/foo';

    io()->writeln($dir . ' directory exist: ' . (fs()->exists($dir) ? 'yes' : 'no'));

    fs()->mkdir($dir);
    fs()->touch($dir . '/bar.md');

    io()->writeln($dir, ' is an absolute path: ' . (Path::isAbsolute($dir) ? 'yes' : 'no'));
    io()->writeln('../ is an absolute path: ' . (Path::isAbsolute('../') ? 'yes' : 'no'));

    fs()->remove($dir);

    io()->writeln('Absolute path: ' . Path::makeAbsolute('../', $dir));
}
```

--------------------------------

### Create a complex task with user interaction

Source: https://github.com/jolicode/castor/blob/main/README.md

Define a task that uses input/output helpers and executes shell commands, such as docker-compose.

```php
#[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.')
}
```

--------------------------------

### Using task() to get the current task name

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/console-and-io.md

Shows how to use task() to get the name of the task currently run by the user. Note that task() references the Castor task ran by the user, not the one where task() may be called.

```php
#[AsTask()]
function foo(): void
{
    io()->title(task()->getName());
}

#[AsTask()]
function bar(): void
{
    foo();
}
```

--------------------------------

### Using finder() to count PHP files

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/filesystem.md

Shows how to use finder() to search for files by name pattern and count results. Returns a Symfony Finder instance with a fluent interface.

```php
use Castor\Attribute\AsTask;

use function Castor\finder;
use function Castor\io;

#[AsTask()]
function foo()
{
    io()->writeln('Number of PHP files: ' . finder()->name('*.php')->in(__DIR__)->count());
}
```

--------------------------------

### Create a context from a .env file

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/interacting-with-castor/dot-env.md

Use the AsContext attribute to define a context that automatically loads variables from a .env file.

```php
use Castor\Attribute\AsContext;
use Castor\Context;

use function Castor\load_dot_env;

#[AsContext()]
function my_context(): Context
{
    return new Context(load_dot_env());
}
```

--------------------------------

### Compress a directory into a zip archive using zip_binary()

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/archive.md

Uses the zip_binary() function to compress a directory into a password-protected ZIP archive using the native zip binary with BZIP2 compression and level 9. Warning: the zip binary accepts the password as a command line argument, which is readable by every user of the machine (e.g., in ps) while the archive is created. Use zip() or zip_php() when the password must stay private.

```php
use Castor\Attribute\AsArgument;
use Castor\Attribute\AsTask;
use Castor\Helper\ZipArchiver;

use function Castor\zip_binary;
use function Castor\io;

#[AsTask(description: 'Compress a directory into a zip archive using native binary')]
function compress_dir_binary(string $directory, string $destination): void
{
    zip_binary($directory, $destination, 'my super secret password', CompressionMethod::BZIP2, 9);
    io()->success('Directory compressed successfully!');
}
```

--------------------------------

### Execute a remote PHP package with castor execute

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/remote.md

Runs the `friendsofphp/php-cs-fixer` package, downloading it and its dependencies, then executing the first binary command found (php-cs-fixer) with the `fix` argument. All options after the package name are passed to the binary command.

```bash
castor execute friendsofphp/php-cs-fixer fix
```

--------------------------------

### app

Source: https://github.com/jolicode/castor/blob/main/doc/docs/reference.md

Returns the application instance.

```APIDOC
## app

### Description
Returns the application instance.

### Usage
`app()`

```

--------------------------------

### Get arguments after end of options

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/arguments.md

Use the `#[AsArgsAfterOptionEnd]` attribute to ignore options after the `--` delimiter, useful for passing options to subcommands.

```php
{{ php("examples/basic/arguments/args-after-end-option.php") }}
```

--------------------------------

### Castor help output with file link

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/interacting-with-castor/ide-file-links.md

Shows the output of `castor help <task-name>`, which includes the file path and line number of the task definition as a clickable link.

```console
$ castor help my-task

Description:
  My task description

Usage:
  my-task [options]

Help:
  Defined in /path/to/castor.php:12
```

--------------------------------

### Using io() to interact with the console

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/console-and-io.md

Shows how to use the io() function to display titles, comments, ask questions, show progress bars, tables, and success messages. Returns a SymfonyStyle instance.

```php
use Castor\Attribute\AsTask;

use function Castor\io;

#[AsTask()]
function foo(): void
{
    io()->title('This is a title');

    io()->comment('With IO, you can ask questions ...');
    $value = io()->ask('Tell me something');
    io()->writeln('You said: ' . $value);

    io()->comment('... show progress bars ...');
    io()->progressStart(100);
    for ($i = 0; $i < 100; ++$i) {
        io()->progressAdvance();
        usleep(1000);
    }
    io()->progressFinish();

    io()->comment('... show table ...');
    io()->table(['Name', 'Age'], [
        ['Alice', 21],
        ['Bob', 42],
    ]);

    io()->success('This is a success message');
}
```

--------------------------------

### Compile Castor Application into a Static Binary

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/extending-castor/compile.md

Run the compile command with the phar file of your Castor application as an argument. Requires a repacked phar (see repack documentation). Not supported on Windows.

```bash
castor compile my-custom-castor-app.phar
```

--------------------------------

### Set timeout with withTimeout

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/context.md

By default, `run()` calls can go indefinitely. Use `withTimeout` to set a timeout in seconds. The example sets a 2-minute timeout.

```php
use Castor\Attribute\AsTask;

use function Castor\context;
use function Castor\run;

#[AsTask()]
function foo(): void
{
    run('my-script.sh', context: context()->withTimeout(120));
}
```

--------------------------------

### Display a desktop notification with notify()

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/notify.md

Use the notify() function to trigger a basic desktop notification.

```php
use Castor\Attribute\AsTask;

use function Castor\notify;

#[AsTask()]
function notify()
{
    notify('Hello world!');
}
```

--------------------------------

### Define a task with optional arguments

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/arguments.md

Arguments can be made optional by providing default values. This example shows a task with an optional argument and an optional option.

```php
{{ php("examples/basic/arguments/optional.php") }}
```

--------------------------------

### Import tasks from a directory

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/basic-usage.md

Uses the `import()` function to load tasks from a directory. Must be called at the top level of the file.

```php
<?php

use function Castor\import;

import(__DIR__ . '/tasks');

```

--------------------------------

### Configure HTTP client with http_client()

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/http-request.md

Access the HttpClientInterface directly via http_client() to apply custom options like timeouts or SSL verification settings.

```php
use Castor\Attribute\AsTask;

use function Castor\http_client;

#[AsTask()]
function foo()
{
    $client = http_client()
        ->withOptions([
            'verify_peer' => false,
            'timeout' => 10,
        ])
    ;
}
```

--------------------------------

### Watching multiple paths

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/watch.md

Monitors multiple directories or files simultaneously by passing an array of paths to the watch() function.

```php
use Castor\Attribute\AsTask;

use function Castor\io;
use function Castor\watch;

#[AsTask()]
function watcher(): void
{
    // watch recursively inside the src and tests folders
    watch(['src/...', 'tests/...'], function (string $file, string $action) {
        io()->writeln("File {$file} has been {$action}");
    });
}
```

--------------------------------

### Disable PTY and TTY with withPty and withTty

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/context.md

Use `withPty(false)` and `withTty(false)` together to disable both, which prevents standard input from being forwarded to the process. The example prints nothing.

```php
use Castor\Attribute\AsTask;

use function Castor\context;
use function Castor\run;

#[AsTask()]
function foo(): void
{
    run('echo "bar"', context: context()->withPty(false)->withTty(false)); // print nothing
}
```

--------------------------------

### Load .env file with load_dot_env()

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/interacting-with-castor/dot-env.md

The load_dot_env() function loads a .env file from the project root by default, populates environment variables for the current process, and returns them as an array. It is recommended to access variables via $_SERVER rather than the returned array to account for system-level overrides.

```php
use Castor\Attribute\AsTask;
use Castor\Context;

use function Castor\load_dot_env;

#[AsTask()]
function show_database_url(): void
{
    $env = load_dot_env();

    io()->writeln($_SERVER['DATABASE_URL'] ?? throw new \RuntimeException('DATABASE_URL is not defined'));
}
```

--------------------------------

### Log a message with log()

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/interacting-with-castor/log.md

Use the log() function to output messages at specific levels.

```php
use Castor\Attribute\AsTask;

use function Castor\log;

#[AsTask()]
function log()
{
    log('Error!, this is an "error" log message.', 'error');
}
```

--------------------------------

### Publish updated changes

Source: https://github.com/jolicode/castor/blob/main/CONTRIBUTING.md

Force push your rebased branch to your origin repository.

```bash
git push -f origin <your-branch>
```

--------------------------------

### Force supportsInteraction value with withSupportsInteraction()

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/context.md

Forces the `supportsInteraction` value on a context, for example to flag your own AI agent runner as non-interactive. This overrides the auto-detection based on the `CI` environment variable or TTY status.

```php
$c = context()->withSupportsInteraction(false);
```

--------------------------------

### io

Source: https://github.com/jolicode/castor/blob/main/doc/docs/reference.md

Returns the input/output instance.

```APIDOC
## io

### Description
Returns the input/output instance.

### Usage
`io()`

```

--------------------------------

### Task list output with custom attributes

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/basic-usage.md

Shows the task list output after customizing the task name, namespace, and description.

```console
$ castor
...
Available commands:
  completion         Dump the shell completion script
  help               Display help for a command
  list               List commands
 foo
  foo:bar            Configures the default name, namespace, and description

```

--------------------------------

### Display notifications with run()

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/notify.md

Use the withNotify method of the Context object to automatically display success or failure notifications when executing commands.

```php
use Castor\Attribute\AsTask;

use function Castor\context;
use function Castor\run;

#[AsTask()]
function notify()
{
    run(['echo', 'notify'], context: context()->withNotify(true)); // will display a success notification
    run('command_that_does_not_exist', context: context()->withNotify(true)); // will display a failure notification
}
```

--------------------------------

### Customize task name, namespace, and description

Source: https://github.com/jolicode/castor/blob/main/doc/docs/getting-started/basic-usage.md

Uses the `AsTask` attribute arguments to override the task name, namespace, and add a description.

```php
<?php

use Castor\Attribute\AsTask;

#[AsTask(name: 'bar', namespace: 'foo', description: 'Configures the default name, namespace, and description')]
function myTask(): void
{
    // ...
}

```

--------------------------------

### Register a listener with #[AsListener]

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/extending-castor/events.md

Register a listener for one or more Castor events using the #[AsListener] attribute. The priority argument is optional and defaults to 0; higher priority executes earlier. Multiple events can be specified for a single listener.

```php
use Castor\Attribute\AsListener;
use Castor\Event\AfterExecuteTaskEvent;
use Castor\Event\FunctionsResolvedEvent;

#[AsListener(event: AfterExecuteTaskEvent::class)]
#[AsListener(event: FunctionsResolvedEvent::class, priority: 1)]
function my_event_listener(AfterExecuteTaskEvent|FunctionsResolvedEvent $event): void
{
    // Custom logic to handle the events
}
```

--------------------------------

### Example output of named jobs in non-interactive terminal

Source: https://github.com/jolicode/castor/blob/main/doc/docs/going-further/helpers/parallel.md

Shows the output when the terminal is not interactive (CI, pipe, file) or in verbose/quiet modes: each line is prefixed with the job name, error output goes to error output, and a summary of jobs appears at the end.

```text
[test]  Running the test suite
[lint]  Linting a.php
[test]  Test 1: OK
[lint]  Linting b.php
[lint]  ✔ Done in 0.9s
[test]  Test 2: OK
[test]  Test 3: KO
[test]  In jobs.php line 21:
[test]   [ERROR] The following process did not finish successfully (exit code 1):
[test]  echo "Test 3: KO" >&2; exit 1
[test]   // Re-run the command with the -v option to see more details.
[test]  ✘ Failed after 1.3s
[build] Assets compiled
[build] ✔ Done in 1.6s

[lint]  ✔ Done in 0.9s
[test]  ✘ Failed after 1.3s
[build] ✔ Done in 1.6s
```

--------------------------------

### input

Source: https://github.com/jolicode/castor/blob/main/doc/docs/reference.md

Returns the input instance.

```APIDOC
## input

### Description
Returns the input instance.

### Usage
`input()`

```
Tokens:
Raw