### Using setup-php action

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

Example of setting up Castor using the setup-php action in a GitHub Actions workflow, which also installs PHP.

```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
```

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

### Manual Installation with Git

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

This snippet demonstrates cloning the repository, installing dependencies, and creating a symlink for manual installation.

```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
```

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

### Using the installer

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

The installer is the recommended and easiest way to install Castor on your system. It works on Linux and macOS.

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

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

### Terminal helper example

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

Example of using the terminal() helper to get terminal properties.

```php
{% include "/examples/basic/io/terminal.php" start="<?php\n\nnamespace io;\n\n" %}
```

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

### Windows or WSL

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

Download and install the Castor phar for Windows or WSL.

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

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

### Ls command builder example

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

An example of a command builder implementing the CommandBuilderInterface.

```php
class Ls implements CommandBuilderInterface
{
    private string $flags = '';

    public function __construct(private ?string $directory = null)
    {
    }

    public function all(): static
    {
        $this->flags .= 'a';

        return $this;
    }

    /** @return string[] */
    public function getCommand(): array
    {
        $command = ['ls'];

        if ($this->flags) {
            $command[] = '-' . $this->flags;
        }

        if ($this->directory) {
            $command[] = $this->directory;
        }

        return $command;
    }
}
```

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

### macOS with Intel

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

Download and install the Castor static binary for macOS with Intel.

```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))
```

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

### PHPStan configuration for stubs

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

Example of how to configure PHPStan to recognize Castor stubs.

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

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

### macOS with Intel

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

Download and install the Castor phar for macOS with Intel.

```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))
```

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

### Install Castor globally with Composer

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

Install Castor globally using Composer.

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

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

### Linux ARM64

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

Download and install the Castor static binary for Linux ARM64.

```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))
```

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

### Install Castor

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

This snippet shows how to install Castor using curl.

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

castor
```

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

### Export environment variable for shell configuration

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

Example of exporting the CASTOR_GENERATE_STUBS environment variable to a shell configuration file.

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

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

### Output in XML format

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

This example shows how to use the --format option to get the command list in XML format.

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

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

### macOS with Apple Silicon

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

Download and install the Castor static binary for macOS with Apple Silicon.

```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))
```

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

### Static binary installation

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

If you don't have PHP available on your system, Castor can be installed with a static binary that embeds PHP, so it can be run anywhere.

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

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

### Linux ARM64

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

Download and install the Castor phar for Linux ARM64.

```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))
```

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

### Raw list of commands

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

This example demonstrates how to get a raw list of commands using the --raw option, which is useful for embedding command runners.

```bash
castor composer list --raw
```

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

### Install PHPStan

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

Install PHPStan static analysis tool from the specified directory.

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

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

### macOS with Apple Silicon

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

Download and install the Castor phar for macOS with Apple Silicon.

```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 a specific version

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

By default, the installer will install the latest version of Castor. You can install a specific version of Castor by using the `--version` option.

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

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

### Console autocompletion example

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

This console example shows how autocompletion works with the `--file` argument, demonstrating directory and glob pattern filtering.

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

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

### Complex Task Example

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

An example of a more complex task 'destroy' with confirmation and Docker command execution.

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

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

### Linux AMD64 (x86-64)

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

Download and install the Castor static binary for Linux AMD64.

```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 to a specific directory

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

By default, the installer will install Castor in the current user's `$HOME/.local/bin` directory. You can change that by using the `--install-dir` option.

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

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

### Task Execution Example

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

How to execute a task named 'hello' from the command line.

```bash
$ castor hello
Hello from castor.
```

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

### Namespace Task Example

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

Example demonstrating how namespaces are used to create task namespaces.

```php
<?php

namespace usage\with\long\namespace;

use Castor\Attribute\AsTask;

#[AsTask]
function hello(): void
{
    echo "Hello from castor.";
}
```

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

### Using .castor/ directory

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

Example of organizing tasks within a .castor/ directory and importing them.

```php
<?php

namespace App\Console;

use Castor\Attribute\AsTask;

#[AsTask]
function hello(): void
{
    echo "Hello from castor.";
}

import(__DIR__ . '/../tasks');

```

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

### YAML Parse and Dump Example

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

This example demonstrates how to parse YAML content from a file, manipulate it, and then dump it back to the file using Castor's yaml_parse() and yaml_dump() 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));
}
```

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

### List commands for a specific namespace

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

This example demonstrates how to list commands within a specific namespace, using 'test' as an example.

```bash
castor composer list test
```

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

### Composer Global Bin Directory

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

This snippet shows how to find and add the Composer global bin directory to your PATH.

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

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

### Linux AMD64 (x86-64)

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

Download and install the Castor phar for Linux AMD64.

```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))
```

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

### Custom Logo Example (Simple String)

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

Example of a PHP file returning a simple string to be used as a custom logo during PHAR repackaging.

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

<?php

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

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

### SSH Command Example

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

An example of an SSH command used to execute 'ls -alh' on a remote server.

```bash
ssh -p 2222 debian@server-1.example.com 'bash -se' << \EOF-SPATIE-SSH
cd /var/www && ls -alh
EOF-SPATIE-SSH
```

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

### Simple Task Example

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

An example of a basic castor.php file defining a single task.

```php
<?php

namespace App\Console;

use Castor\Attribute\AsTask;

#[AsTask]
function hello(): void
{
    echo "Hello from castor.";
}
```

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

### Custom Logo Example (Closure)

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

Example of a PHP file returning a closure that generates a custom logo string, receiving application name and version.

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

<?php

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

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

    LOGO;
};

```

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

### Basic file watching

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

This example demonstrates how to watch a directory and execute a callback when a file changes.

```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}");
    });
}
```

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

### Install PHP CS fixer

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

Install PHP CS fixer tool from the specified directory.

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

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

### Watching multiple paths

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

This example shows how to watch multiple directories simultaneously.

```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}");
    });
}
```

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

### Using the context() function

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

Demonstrates how to get the initial context and modify it using `withWorkingDirectory`.

```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"
}
```

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

### Command Output

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

Example of command output indicating a process did not finish successfully.

```text
Re-run with -v, -vv, -vvv for different output.
foo
In exception.php line XXXX:

 [ERROR] The following process did not finish successfully (exit code XX):

echo foo; echo bar>&2;exit 1
```

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

### SCP Command Example

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

This shows the scp command that was executed and resulted in an error.

```bash
scp -r .../examples/basic/ssh/upload.php debian@server-1.example.com:/var/www/index.html
```

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

### Get help for supported shells

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

This command displays help information for enabling autocompletion in various shells.

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

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

### Command Execution Example

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

Demonstrates the command that is executed when verbose arguments are enabled and a command fails.

```bash
bash -c i_do_not_exist -x -e
```

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

### Recursive watch

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

This example shows how to watch a directory and its subdirectories recursively.

```php
use Castor\Attribute\AsTask;

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

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

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

### Using the official setup-castor action

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

Example of setting up Castor using the official setup-castor action in a GitHub Actions workflow.

```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
```

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

### Passing Verbose Arguments

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

Example of passing verbose arguments to the underlying process using `withVerboseArguments()`.

```php
use Castor\Attribute\AsTask;

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

#[AsTask()]
function foo(): void
{
    run('php bin/console do:some:task', context: context()->withVerboseArguments(['--verbose']));
}
```

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

### Namespace Task Execution Example

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

How to execute a task defined within a nested namespace.

```bash
$ castor usage:with:long:namespace:hello
Hello from castor.
```

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

### Executing a PHAR file

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

Example of how to execute a PHAR file with arguments using the `run_php()` function.

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

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

### Running a Basic Task

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

Shows how to run the 'hello' task from the command line.

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

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

### Importing Tasks from a Directory

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

Example of using the import() function to load tasks from a directory.

```php
<?php

namespace usage;

use Castor\Attribute\AsTask;

#[AsTask]
function hello(): void
{
    echo "Hello from castor.";
}

import(__DIR__);

```

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

### Using the command builder

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

How to use the Ls command builder.

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

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

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

### Display project help

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

Run castor usage:about to display this project help.

```bash
castor usage:about
```

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

### Example of repetitive code with workingDirectory argument

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

Illustrates a scenario where `mount()` can be beneficial by showing repetitive code that explicitly sets the working directory for each task.

```php
use Castor\Attribute\AsTask;

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

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

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

### Using finder()

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

Illustrates how to use the `finder()` function to search for files. This example counts the number of PHP files in the current directory.

```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());
}
```

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

### Getting a specific context

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

You can get a specific context by its name using the context() function. The expression can use the var() function to get the value of a variable and the context() function to get a context by its name.

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

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

#[AsContext(name: 'my_context')]
function create_my_context(): Context
{
    return new Context(['foo' => 'bar'], workingDirectory: '/tmp');
}

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

    io()->writeln($context['foo']); // will print bar even if you do not use the --context option
    run('pwd', context: $context); // will print /tmp
}
```

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

### Option mode configuration

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

Demonstrates configuring the mode of an option.

```php
<?php

namespace arguments;

use Castor\Attribute\AsOption;

#[AsOption(name: "force", description: "Force the command", mode: AsOption::VALUE_NONE)]
function option_mode(bool $force = false)
{
    if ($force) {
        echo "Command has been forced.";
    }
}

```

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

### Compile Command

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

To compile your Castor application, navigate to your project directory and run:

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

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

### Helper function for command builder

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

A recommended way to provide a helper function to create command builders.

```php
use CommandBuilder\Ls;

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

...

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

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

### Display Castor help for a command

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

Run castor help [command] to display Castor help.

```bash
castor help [command]
```

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

### List all commands

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

This example shows how to list all available commands using the 'castor composer list' command.

```bash
castor composer list
```

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

### Multiple Tasks in Same File Example

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

Example of defining multiple tasks in different namespaces within the same file.

```php
<?php

namespace foo1;

use Castor\Attribute\AsTask;

#[AsTask]
function hello1(): void
{
    echo "Hello 1.";
}

namespace foo2;

#[AsTask]
function hello2(): void
{
    echo "Hello 2.";
}
```

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

### PHP include for path option with filter example

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

This PHP include directive demonstrates how to set up the path option with a filter for arguments.

```php
{% include "/examples/basic/arguments/path-option-with-filter.php" start="<?php\n\nnamespace arguments;\n\n" %}
```

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

### Using fs() and Path

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

Demonstrates the usage of the `fs()` function for filesystem operations like creating directories, touching files, and removing them. It also shows how to use `Symfony\Component\Filesystem\Path` for path manipulation and checking absolute paths.

```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));
}
```

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

### Watching multiple directories in parallel

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

This example shows how to use `parallel()` with the `watch()` function to monitor changes in multiple directories simultaneously.

```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
            });
        },
    );
}
```

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

### Load .env file and display DATABASE_URL

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

This task demonstrates how to load a .env file using load_dot_env() and then access a specific environment variable like DATABASE_URL.

```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'));
}
```

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

### Timeout

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

Example of setting a timeout for a process using `withTimeout()`.

```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 command list

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

Run castor list to display the command list.

```bash
castor list
```

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

### Handling signals with SIGUSR2

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

Example of handling SIGUSR2 signal in a Castor task.

```php
use Castor\Attribute\AsTask;

use function Castor\io;

#[AsTask(onSignals: [\SIGUSR2 => 'onSigUsr2'])]
function foo(): void
{
    // Do something...
}

function onSigUsr2(int $signal): int|false
{
    io()->writeln("SIGUSR2 received\n");

    return false;
}
```

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

### PTY & TTY (TTY)

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

Example of using a TTY instead of a PTY with `withTty()`.

```php
use Castor\Attribute\AsTask;

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

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

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

### Environment Variables

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

Example of adding or overriding environment variables using `withEnvironment()`.

```php
use Castor\Attribute\AsTask;

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

#[AsTask()]
function foo(): void
{
    run('echo $FOO', context: context()->withEnvironment(['FOO' => 'bar'])); // will print "bar"
}
```

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

### Working Directory

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

Examples of changing the working directory for a process using `withWorkingDirectory()`.

```php
use Castor\Attribute\AsTask;

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

#[AsTask()]
function foo(): void
{
    run('pwd', context: context()->withWorkingDirectory('../')); // run the process in the parent directory of the castor.php file
    run('pwd', context: context()->withWorkingDirectory('/tmp')); // run the process in the /tmp directory
}
```

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

### Open a URL

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

This task opens a URL in the user's default application.

```php
use Castor\Attribute\AsTask;

use function Castor\open;

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

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

### Path argument example

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

Defines a task with a path argument that supports autocompletion.

```php
<?php

namespace arguments;

use Castor\Attribute\AsPathArgument;

function path_argument(#[AsPathArgument] string $path)
{
    echo "The provided path is: " . $path;
}

```

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

### Enable bash autocomplete

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

This command enables bash autocompletion for Castor by installing a completion script.

```bash
castor completion | sudo tee /etc/bash_completion.d/castor
```

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

### Running multiple functions in parallel

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

This example demonstrates how to use the `parallel()` function to execute two `run()` commands concurrently and then process their outputs.

```php
use Castor\Attribute\AsTask;

use function Castor\context;
use function Castor\io;
use function Castor\parallel;

#[AsTask()]
function foo(): void
{
    [$foo, $bar] = parallel(
        function () {
            return run('sleep 2 && echo foo', context: context()->withQuiet());
        },
        function () {
            return run('sleep 2 && echo bar', context: context()->withQuiet());
        }
    );

    io()->writeln($foo->getOutput()); // will print foo
    io()->writeln($bar->getOutput()); // will print bar
}
```

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

### Slugify a string

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

Example of using the slug() function to create a URL-safe string.

```php
<?php

namespace slug;

use function Castor\slug;

function main(): void
{
    $text = 'This is a title with special characters!';
    $slug = slug($text);

    echo "Original: {$text}\n";
    echo "Slug: {$slug}\n";
}

```

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

### wait_for_url() function

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

Example of using `wait_for_url()` to wait for a URL to be accessible.

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

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

### Running the compiled binary

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

Once the compilation is finished, your Castor application is transformed into a static binary named `castor` by default (you can use the `--binary-path` option to change it). This binary is now ready to be distributed and run in environments that do not have PHP installed. You can simply run it like any other executable:

```bash
./castor
```

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

### Disable stub generation via environment variable

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

Command to disable stub generation for Castor.

```bash
CASTOR_GENERATE_STUBS=0 castor
```