From 0d1650cbb1c7e542907e6b98bca95625b9f74606 Mon Sep 17 00:00:00 2001
From: Jorick Pepin <jorick.pepin@gmail.com>
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/Exception/ExecutableNotFoundException.php |  2 +-
 src/functions.php                             | 23 +++++++++++++++++++
 .../FilesystemFindTest.php.output.txt         |  2 +-
 .../Generated/ListTest.php.output.txt         |  2 ++
 9 files changed, 65 insertions(+), 3 deletions(-)
 create mode 100644 doc/going-further/helpers/open.md
 create mode 100644 examples/open.php

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..bafdb998
--- /dev/null
+++ b/examples/open.php
@@ -0,0 +1,19 @@
+<?php
+
+namespace open;
+
+use Castor\Attribute\AsTask;
+
+use function Castor\open;
+
+#[AsTask(description: 'Open Castor documentation in the default browser')]
+function documentation(): void
+{
+    open('https://castor.jolicode.com');
+}
+
+#[AsTask(description: 'Open an URL and a file in the default applications')]
+function multiple(): void
+{
+    open('https://castor.jolicode.com', 'examples/open.php');
+}
diff --git a/src/Exception/ExecutableNotFoundException.php b/src/Exception/ExecutableNotFoundException.php
index 3027e0d8..8d74221c 100644
--- a/src/Exception/ExecutableNotFoundException.php
+++ b/src/Exception/ExecutableNotFoundException.php
@@ -7,6 +7,6 @@ class ExecutableNotFoundException extends \RuntimeException
     public function __construct(
         readonly string $executableName,
     ) {
-        parent::__construct("Executable {$executableName} not found. Please install it to use this feature.");
+        parent::__construct(sprintf('Executable "%s" not found. Please install it to use this feature.', $executableName));
     }
 }
diff --git a/src/functions.php b/src/functions.php
index 19436ce2..6a70a24e 100644
--- a/src/functions.php
+++ b/src/functions.php
@@ -4,6 +4,7 @@
 
 use Castor\Attribute\AsContextGenerator;
 use Castor\Console\Application;
+use Castor\Exception\ExecutableNotFoundException;
 use Castor\Exception\MinimumVersionRequirementNotMetException;
 use Castor\Exception\WaitFor\ExitedBeforeTimeoutException;
 use Castor\Exception\WaitFor\TimeoutReachedException;
@@ -23,6 +24,7 @@
 use Symfony\Component\Filesystem\Filesystem;
 use Symfony\Component\Finder\Finder;
 use Symfony\Component\Process\Exception\ProcessFailedException;
+use Symfony\Component\Process\ExecutableFinder;
 use Symfony\Component\Process\Process;
 use Symfony\Component\Yaml\Yaml;
 use Symfony\Contracts\Cache\CacheInterface;
@@ -1055,3 +1057,24 @@ function guard_min_version(string $minVersion): void
         throw new MinimumVersionRequirementNotMetException($minVersion, $currentVersion);
     }
 }
+
+function open(string ...$urls): void
+{
+    $command = match (true) {
+        OsHelper::isMacOS() => 'open',
+        OsHelper::isWindows() => 'start',
+        default => 'xdg-open',
+    };
+
+    if (null === (new ExecutableFinder())->find($command)) {
+        throw new ExecutableNotFoundException($command);
+    }
+
+    $parallelCallbacks = [];
+
+    foreach ($urls as $url) {
+        $parallelCallbacks[] = fn () => run([$command, $url], quiet: true);
+    }
+
+    parallel(...$parallelCallbacks);
+}
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..8155299e 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 default browser
+open:multiple                                                     Open an URL and a file in the default 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