chore: deprecate 'path' wording in favor of currentDirectory in some functions and Context

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Not released yet
 
+* Deprecate `Context::withPath()` in favor of `Context::withCurrentDirectory()`
+* Deprecate `path` argument in `capture()`, `exit_code()`, `run()`, `with()` in favor of `currentDirectory`
+
 ## 0.14.0 (2024-03-08)
 
 * Add a `yaml_dump()` function to dump any PHP value to a YAML string

doc/getting-started/context.md

@@ -29,7 +29,7 @@ function foo(): void
 
     echo $context->currentDirectory; // will print the directory of the castor.php file
 
-    $context = $context->withPath('/tmp'); // will create a new context where the current directory is /tmp
+    $context = $context->withCurrentDirectory('/tmp'); // will create a new context where the current directory is /tmp
     run('pwd', context: $context); // will print "/tmp"
 }
 ```

examples/cd.php

@@ -10,6 +10,6 @@
 function directory(): void
 {
     run(['pwd']);
-    run(['pwd'], path: 'src/Attribute');
+    run(['pwd'], currentDirectory: 'src/Attribute');
     run(['pwd']);
 }

examples/failure.php

@@ -9,7 +9,7 @@
 #[AsTask(description: 'A failing task not authorized to fail')]
 function failure(): void
 {
-    run('i_do_not_exist', path: '/tmp', pty: false);
+    run('i_do_not_exist', currentDirectory: '/tmp', pty: false);
 }
 
 #[AsTask(description: 'A failing task authorized to fail')]

src/Context.php

@@ -75,7 +75,14 @@ public function withEnvironment(array $environment, bool $keepExisting = true):
 
     public function withPath(string $path): self
     {
-        return $this->with(currentDirectory: str_starts_with($path, '/') ? $path : PathHelper::realpath($this->currentDirectory . '/' . $path));
+        trigger_deprecation('castor', '0.15', 'The method "%s()" is deprecated, use "%s::withCurrentDirectory()" instead.', __METHOD__, __CLASS__);
+
+        return $this->withCurrentDirectory($path);
+    }
+
+    public function withCurrentDirectory(string $currentDirectory): self
+    {
+        return $this->with(currentDirectory: str_starts_with($currentDirectory, '/') ? $currentDirectory : PathHelper::realpath($this->currentDirectory . '/' . $currentDirectory));
     }
 
     public function withTty(bool $tty = true): self

src/functions.php

@@ -112,7 +112,7 @@ function parallel(callable ...$callbacks): array
 function run(
     string|array $command,
     ?array $environment = null,
-    ?string $path = null,
+    ?string $currentDirectory = null,
     ?bool $tty = null,
     ?bool $pty = null,
     ?float $timeout = null,
@@ -121,15 +121,24 @@ function run(
     ?bool $notify = null,
     ?callable $callback = null,
     ?Context $context = null,
+    ?string $path = null,
 ): Process {
     $context ??= GlobalHelper::getContext();
 
     if (null !== $environment) {
         $context = $context->withEnvironment($environment);
     }
 
+    if ($currentDirectory) {
+        $context = $context->withCurrentDirectory($currentDirectory);
+        if ($path) {
+            throw new \LogicException('You cannot use both the "path" and "currentDirectory" arguments at the same time.');
+        }
+    }
     if ($path) {
-        $context = $context->withPath($path);
+        trigger_deprecation('castor', '0.15', 'The "path" argument is deprecated, use "currentDirectory" instead.');
+
+        $context = $context->withCurrentDirectory($path);
     }
 
     if (null !== $tty) {
@@ -249,11 +258,12 @@ function run(
 function capture(
     string|array $command,
     ?array $environment = null,
-    ?string $path = null,
+    ?string $currentDirectory = null,
     ?float $timeout = null,
     ?bool $allowFailure = null,
     ?string $onFailure = null,
     ?Context $context = null,
+    ?string $path = null,
 ): string {
     $hasOnFailure = null !== $onFailure;
     if ($hasOnFailure) {
@@ -263,10 +273,19 @@ function capture(
         $allowFailure = true;
     }
 
+    if ($currentDirectory && $path) {
+        throw new \LogicException('You cannot use both the "path" and "currentDirectory" arguments at the same time.');
+    }
+    if ($path) {
+        trigger_deprecation('castor', '0.15', 'The "path" argument is deprecated, use "currentDirectory" instead.');
+
+        $currentDirectory = $path;
+    }
+
     $process = run(
         command: $command,
         environment: $environment,
-        path: $path,
+        currentDirectory: $currentDirectory,
         timeout: $timeout,
         allowFailure: $allowFailure,
         context: $context,
@@ -287,15 +306,25 @@ function capture(
 function exit_code(
     string|array $command,
     ?array $environment = null,
-    ?string $path = null,
+    ?string $currentDirectory = null,
     ?float $timeout = null,
     ?bool $quiet = null,
     ?Context $context = null,
+    ?string $path = null,
 ): int {
+    if ($currentDirectory && $path) {
+        throw new \LogicException('You cannot use both the "path" and "currentDirectory" arguments at the same time.');
+    }
+    if ($path) {
+        trigger_deprecation('castor', '0.15', 'The "path" argument is deprecated, use "currentDirectory" instead.');
+
+        $currentDirectory = $path;
+    }
+
     $process = run(
         command: $command,
         environment: $environment,
-        path: $path,
+        currentDirectory: $currentDirectory,
         timeout: $timeout,
         allowFailure: true,
         context: $context,
@@ -801,14 +830,15 @@ function with(
     callable $callback,
     ?array $data = null,
     ?array $environment = null,
-    ?string $path = null,
+    ?string $currentDirectory = null,
     ?bool $tty = null,
     ?bool $pty = null,
     ?float $timeout = null,
     ?bool $quiet = null,
     ?bool $allowFailure = null,
     ?bool $notify = null,
     Context|string|null $context = null,
+    ?string $path = null,
 ): mixed {
     $contextRegistry = GlobalHelper::getContextRegistry();
 
@@ -830,8 +860,16 @@ function with(
         $context = $context->withEnvironment($environment);
     }
 
+    if ($currentDirectory) {
+        $context = $context->withCurrentDirectory($currentDirectory);
+        if ($path) {
+            throw new \LogicException('You cannot use both the "path" and "currentDirectory" arguments at the same time.');
+        }
+    }
     if ($path) {
-        $context = $context->withPath($path);
+        trigger_deprecation('castor', '0.15', 'The "path" argument is deprecated, use "currentDirectory" instead.');
+
+        $context = $context->withCurrentDirectory($path);
     }
 
     if (null !== $tty) {