diff --git a/CHANGELOG.md b/CHANGELOG.md index c6649c7d..6e1ab023 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ * Add a `yaml_dump()` function to dump any PHP value to a YAML string * Add a `yaml_parse()` function to parse a YAML string to a PHP value * Remove the default timeout of 60 seconds from the Context +* Add a `context_path()` function to get the path of the context with optional additional path ## 0.13.1 (2024-02-27) diff --git a/doc/getting-started/context.md b/doc/getting-started/context.md index 687e003d..1511f1fd 100644 --- a/doc/getting-started/context.md +++ b/doc/getting-started/context.md @@ -66,6 +66,42 @@ function foo(): void > [!TIP] > Related example: [context.php](https://github.com/jolicode/castor/blob/main/examples/context.php) +### The `castor_path()` function + +You can get the path of current context using the `castor_path()` function: + +> [!NOTE] +> +> This function accept a optional `string` argument to append to the current directory. +> +> It also accept a optional `context` argument to use a specific context instead of the current one. + +```php +use Castor\Attribute\AsTask; + +use function Castor\castor_path; + +#[AsTask()] +function foo(): void +{ + // Normally you generally use the `context()` function to get the current directory + $currentDirectory = context()->currentDirectory; // output: "/home/user/project" + + // But a proper way to get a computed path is to use the `castor_path()` function + $currentDirectory = castor_path(); // output: "/home/user/project" + $computedPath = castor_path('foo/bar'); // output: "/home/user/project/foo/bar" + + // You can also provide a context to the `castor_path()` function + $computedPath = castor_path('foo/bar', context: my_tmp_context()); // output: "/tmp/foo/bar" + + // Same as: + $computedPath = my_tmp_context()->getPath('foo/bar'); +} +``` + +> [!NOTE] +> The `castor_path()` function is a shortcut to `context()->getPath()`. + ## Creating a new context You can create a new context by declaring a function with diff --git a/doc/reference.md b/doc/reference.md index 87bb718e..b00c8880 100644 --- a/doc/reference.md +++ b/doc/reference.md @@ -10,6 +10,7 @@ Castor provides the following built-in functions: - [`cache`](going-further/helpers/cache.md#the-cache-function) - [`capture`](getting-started/run.md#the-capture-function) - [`context`](getting-started/context.md#the-context-function) +- [`context_path`](getting-started/context.md#the-castor_path-function) - [`exit_code`](getting-started/run.md#the-exit_code-function) - [`finder`](going-further/helpers/filesystem.md#the-finder-function) - [`fingerprint`](going-further/helpers/fingerprint.md#the-fingerprint-function) diff --git a/src/Attribute/AsCommandArgument.php b/src/Attribute/AsCommandArgument.php index e1ea8963..180f7ae2 100644 --- a/src/Attribute/AsCommandArgument.php +++ b/src/Attribute/AsCommandArgument.php @@ -5,7 +5,7 @@ abstract class AsCommandArgument { public function __construct( - public readonly string|null $name = null, + public readonly ?string $name = null, ) { } } diff --git a/src/Attribute/AsOption.php b/src/Attribute/AsOption.php index 870e1e68..fa93cfa4 100644 --- a/src/Attribute/AsOption.php +++ b/src/Attribute/AsOption.php @@ -12,7 +12,7 @@ class AsOption extends AsCommandArgument public function __construct( ?string $name = null, public readonly string|array|null $shortcut = null, - public readonly int|null $mode = null, + public readonly ?int $mode = null, public readonly string $description = '', public readonly array $suggestedValues = [], ) { diff --git a/src/Attribute/AsTask.php b/src/Attribute/AsTask.php index 391bcae1..e681d0a1 100644 --- a/src/Attribute/AsTask.php +++ b/src/Attribute/AsTask.php @@ -11,7 +11,7 @@ class AsTask */ public function __construct( public string $name = '', - public string|null $namespace = null, + public ?string $namespace = null, public string $description = '', public array $aliases = [], public array $onSignals = [], diff --git a/src/Context.php b/src/Context.php index c34fbd12..5d7b4429 100644 --- a/src/Context.php +++ b/src/Context.php @@ -17,7 +17,7 @@ public function __construct( ?string $currentDirectory = null, public readonly bool $tty = false, public readonly bool $pty = true, - public readonly float|null $timeout = null, + public readonly ?float $timeout = null, public readonly bool $quiet = false, public readonly bool $allowFailure = false, public readonly bool $notify = false, @@ -132,7 +132,7 @@ public function withPty(bool $pty = true): self ); } - public function withTimeout(float|null $timeout): self + public function withTimeout(?float $timeout): self { return new self( $this->data, @@ -234,6 +234,21 @@ public function withName(string $name): self ); } + public function getPath(?string $path = null): string + { + $currentDirectory = $this->currentDirectory; + + if (null === $path) { + return $currentDirectory; + } + + if (str_starts_with($path, '/')) { + return "{$currentDirectory}{$path}"; + } + + return "{$currentDirectory}/{$path}"; + } + public function offsetExists(mixed $offset): bool { return \array_key_exists($offset, $this->data); diff --git a/src/SectionOutput.php b/src/SectionOutput.php index b3c0a24e..3a37a6a0 100644 --- a/src/SectionOutput.php +++ b/src/SectionOutput.php @@ -14,7 +14,7 @@ class SectionOutput private OutputInterface|ConsoleSectionOutput $consoleOutput; - private ConsoleOutput|null $mainOutput; + private ?ConsoleOutput $mainOutput; /** @var \SplObjectStorage */ private \SplObjectStorage $sections; diff --git a/src/functions.php b/src/functions.php index 29e1cf67..54e39669 100644 --- a/src/functions.php +++ b/src/functions.php @@ -1055,3 +1055,10 @@ function guard_min_version(string $minVersion): void throw new MinimumVersionRequirementNotMetException($minVersion, $currentVersion); } } + +function context_path(?string $path = null, ?Context $context = null): string +{ + $context ??= context(); + + return $context->getPath($path); +}