From 9cf49d1396969566fee40d9ddb1f27e46b5c71f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9goire=20Pineau?= Date: Sat, 9 Mar 2024 08:58:38 +0100 Subject: [PATCH] chore: deprecate 'path' wording in favor of currentDirectory in some functions and Context --- CHANGELOG.md | 3 ++ doc/getting-started/context.md | 2 +- examples/cd.php | 2 +- examples/failure.php | 2 +- src/Context.php | 9 +++++- src/functions.php | 54 +++++++++++++++++++++++++++++----- 6 files changed, 60 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d42fd116..d414d5ac 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/doc/getting-started/context.md b/doc/getting-started/context.md index 687e003d..27febdee 100644 --- a/doc/getting-started/context.md +++ b/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" } ``` diff --git a/examples/cd.php b/examples/cd.php index bef2b8f7..c9a9ae46 100644 --- a/examples/cd.php +++ b/examples/cd.php @@ -10,6 +10,6 @@ function directory(): void { run(['pwd']); - run(['pwd'], path: 'src/Attribute'); + run(['pwd'], currentDirectory: 'src/Attribute'); run(['pwd']); } diff --git a/examples/failure.php b/examples/failure.php index 4073c714..030d90a8 100644 --- a/examples/failure.php +++ b/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')] diff --git a/src/Context.php b/src/Context.php index b1fd9ad1..7a8ee474 100644 --- a/src/Context.php +++ b/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 diff --git a/src/functions.php b/src/functions.php index 6a70a24e..b3407765 100644 --- a/src/functions.php +++ b/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,6 +121,7 @@ function run( ?bool $notify = null, ?callable $callback = null, ?Context $context = null, + ?string $path = null, ): Process { $context ??= GlobalHelper::getContext(); @@ -128,8 +129,16 @@ function run( $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,7 +830,7 @@ 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, @@ -809,6 +838,7 @@ function with( ?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) {