feat: add an open function

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)
 

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

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

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)

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

src/functions.php

@@ -1055,3 +1055,29 @@ function guard_min_version(string $minVersion): void
         throw new MinimumVersionRequirementNotMetException($minVersion, $currentVersion);
     }
 }
+
+/**
+ * @param string|non-empty-array<string> $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);
+}

tests/Examples/Generated/FilesystemFindTest.php.output.txt

@@ -1 +1 @@
-Number of PHP files: 28
+Number of PHP files: 29

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

tests/Examples/Generated/OpenDocumentationTest.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Castor\Tests\Examples\Generated;
+
+use Castor\Tests\TaskTestCase;
+
+class OpenDocumentationTest extends TaskTestCase
+{
+    // open:documentation
+    public function test(): void
+    {
+        $process = $this->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());
+        }
+    }
+}