From 5d8fd81544b21c44874f6ede8e4729eacc0ea6d1 Mon Sep 17 00:00:00 2001 From: Jorick Pepin Date: Tue, 5 Mar 2024 19:25:00 +0100 Subject: [PATCH] feat: add an `open` function --- CHANGELOG.md | 1 + CONTRIBUTING.md | 2 +- doc/going-further/helpers/open.md | 16 ++++++++++++ doc/reference.md | 1 + examples/open.php | 19 ++++++++++++++ src/functions.php | 26 +++++++++++++++++++ .../FilesystemFindTest.php.output.txt | 2 +- .../Generated/ListTest.php.output.txt | 2 ++ .../Generated/OpenDocumentationTest.php | 22 ++++++++++++++++ .../OpenDocumentationTest.php.output.txt | 0 10 files changed, 89 insertions(+), 2 deletions(-) create mode 100644 doc/going-further/helpers/open.md create mode 100644 examples/open.php create mode 100644 tests/Examples/Generated/OpenDocumentationTest.php create mode 100644 tests/Examples/Generated/OpenDocumentationTest.php.output.txt diff --git a/CHANGELOG.md b/CHANGELOG.md index d285a1ea..d8ae3666 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ * Remove the default timeout of 60 seconds from the Context * Add `bool` return type to `fingerprint()` function to indicate if the callable was run * Add a `recursive` parameter to the `withData()` method of `Context` to allow recursive merging for nested arrays +* Add an `open()` function to open a file or URL in the default application ## 0.13.1 (2024-02-27) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8d4f14c3..7ae6bc09 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -90,7 +90,7 @@ And run the tool to make your code compliant with castor's static analysis checks: ```shell -tools/phpstan/vendor/bin/phpstan fix --config=phpstan.neon +tools/phpstan/vendor/bin/phpstan --configuration=phpstan.neon ``` ## Update the Documentation diff --git a/doc/going-further/helpers/open.md b/doc/going-further/helpers/open.md new file mode 100644 index 00000000..53521b1f --- /dev/null +++ b/doc/going-further/helpers/open.md @@ -0,0 +1,16 @@ +# Open URLs and files + +Castor provides an `open()` function that will open one or more +URLs or files in the user's default application. + +```php +use Castor\Attribute\AsTask; + +use function Castor\open; + +#[AsTask()] +function open() +{ + open('https://castor.jolicode.com'); +} +``` diff --git a/doc/reference.md b/doc/reference.md index 87bb718e..47262d05 100644 --- a/doc/reference.md +++ b/doc/reference.md @@ -27,6 +27,7 @@ Castor provides the following built-in functions: - [`log`](going-further/interacting-with-castor/log.md#the-log-function) - [`logger`](going-further/interacting-with-castor/log.md#the-logger-function) - [`notify`](going-further/helpers/notify.md#the-notify-function) +- [`open`](going-further/helpers/open.md) - [`output`](going-further/helpers/console-and-io.md#the-output-function) - [`parallel`](going-further/helpers/parallel.md#the-parallel-function) - [`request`](going-further/helpers/http-request.md#the-request-function) diff --git a/examples/open.php b/examples/open.php new file mode 100644 index 00000000..ca46d7e6 --- /dev/null +++ b/examples/open.php @@ -0,0 +1,19 @@ + $url + */ +function open(string|array $url): void +{ + if (\is_array($url)) { + $parallelCallbacks = []; + + foreach ($url as $u) { + $parallelCallbacks[] = fn () => open($u); + } + + parallel(...$parallelCallbacks); + + return; + } + + $command = match (true) { + OsHelper::isMacOS() => 'open', + OsHelper::isWindows() => 'start', + default => 'xdg-open', + }; + + run([$command, $url], quiet: true); +} diff --git a/tests/Examples/Generated/FilesystemFindTest.php.output.txt b/tests/Examples/Generated/FilesystemFindTest.php.output.txt index 247c827f..d20e33cf 100644 --- a/tests/Examples/Generated/FilesystemFindTest.php.output.txt +++ b/tests/Examples/Generated/FilesystemFindTest.php.output.txt @@ -1 +1 @@ -Number of PHP files: 28 +Number of PHP files: 29 diff --git a/tests/Examples/Generated/ListTest.php.output.txt b/tests/Examples/Generated/ListTest.php.output.txt index 3ead54aa..f4f762d9 100644 --- a/tests/Examples/Generated/ListTest.php.output.txt +++ b/tests/Examples/Generated/ListTest.php.output.txt @@ -44,6 +44,8 @@ log:with-context Logs an "error not-rename:renamed Task that was renamed notify:notify-on-finish Sends a notification when the task finishes notify:send-notify Sends a notification +open:documentation Open Castor documentation in the preferred browser +open:multiple Open an URL and a file in the preferred applications output:output Plays with Symfony Style parallel:exception Sleep and throw an exception parallel:sleep Sleeps for 5, 7, and 10 seconds in parallel diff --git a/tests/Examples/Generated/OpenDocumentationTest.php b/tests/Examples/Generated/OpenDocumentationTest.php new file mode 100644 index 00000000..f9534ce2 --- /dev/null +++ b/tests/Examples/Generated/OpenDocumentationTest.php @@ -0,0 +1,22 @@ +runTask(['open:documentation']); + + $this->assertSame(0, $process->getExitCode()); + $this->assertStringEqualsFile(__FILE__ . '.output.txt', $process->getOutput()); + if (file_exists(__FILE__ . '.err.txt')) { + $this->assertStringEqualsFile(__FILE__ . '.err.txt', $process->getErrorOutput()); + } else { + $this->assertSame('', $process->getErrorOutput()); + } + } +} diff --git a/tests/Examples/Generated/OpenDocumentationTest.php.output.txt b/tests/Examples/Generated/OpenDocumentationTest.php.output.txt new file mode 100644 index 00000000..e69de29b