feat: Add getPath() to Context, and castor_path() global function

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)
 

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

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)

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,
     ) {
     }
 }

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 = [],
     ) {

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 = [],

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

src/SectionOutput.php

@@ -14,7 +14,7 @@ class SectionOutput
 
     private OutputInterface|ConsoleSectionOutput $consoleOutput;
 
-    private ConsoleOutput|null $mainOutput;
+    private ?ConsoleOutput $mainOutput;
 
     /** @var \SplObjectStorage<Process, SectionDetails> */
     private \SplObjectStorage $sections;

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