feat(yaml): add yaml parse and dump functions

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Not released yet
 
+* Add a `yaml_dump()` function to dump any PHP value to a YAML string
+* Add a `yaml_parse()` function to parse a YAML string to a PHP value
+
 ## 0.13.1 (2024-02-27)
 
 * Fix instruction for downloading new castor version as a phar

composer.json

@@ -45,7 +45,8 @@
         "symfony/process": "^6.4.3",
         "symfony/string": "^6.4.3",
         "symfony/translation-contracts": "^3.4.1",
-        "symfony/var-dumper": "^6.4.3"
+        "symfony/var-dumper": "^6.4.3",
+        "symfony/yaml": "^6.4.3"
     },
     "conflict": {
         "symfony/console": "6.4.3"

doc/going-further/helpers/yaml.md

@@ -0,0 +1,18 @@
+# YAML
+
+Castor provides a `yaml_parse()` and `yaml_dump()` functions that will parse or 
+dump YAML content and returns an array using the [symfony/yaml](https://symfony.com/doc/current/components/yaml.html) component:
+
+```php
+use Castor\Attribute\AsTask;
+
+use function Castor\{yaml_parse, yaml_dump};
+
+#[AsTask()]
+function yaml_parse_and_dump(): void
+{
+    $content = yaml_parse(file_get_contents('file.yaml'));
+
+    file_put_contents('file.yaml', yaml_dump($content));
+}
+```

doc/reference.md

@@ -44,6 +44,8 @@ Castor provides the following built-in functions:
 - [`wait_for_url`](going-further/helpers/wait-for.md#the-wait_for_url-function)
 - [`watch`](going-further/helpers/watch.md)
 - [`with`](going-further/interacting-with-castor/advanced-context.md#the-with-function)
+- [`yaml_dump`](going-further/helpers/yaml.md)
+- [`yaml_parse`](going-further/helpers/yaml.md)
 
 ## Attributes
 

examples/yaml.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace yaml;
+
+use Castor\Attribute\AsTask;
+
+use function Castor\yaml_dump;
+use function Castor\yaml_parse;
+
+#[AsTask(description: 'Parse a YAML content')]
+function parse(): void
+{
+    $data = yaml_parse(<<<'YAML'
+foo: bar
+YAML);
+    echo $data['foo'] . "\n";
+}
+
+#[AsTask(description: 'Dump a YAML content')]
+function dump(): void
+{
+    $data = ['foo' => 'bar'];
+    echo yaml_dump($data) . "\n";
+}

src/functions.php

@@ -24,6 +24,7 @@
 use Symfony\Component\Finder\Finder;
 use Symfony\Component\Process\Exception\ProcessFailedException;
 use Symfony\Component\Process\Process;
+use Symfony\Component\Yaml\Yaml;
 use Symfony\Contracts\Cache\CacheInterface;
 use Symfony\Contracts\Cache\CallbackInterface;
 use Symfony\Contracts\Cache\ItemInterface;
@@ -1029,6 +1030,22 @@ function wait_for_docker_container(
     );
 }
 
+/**
+ * @see Yaml::parse()
+ */
+function yaml_parse(string $content, int $flags = 0): mixed
+{
+    return Yaml::parse($content, $flags);
+}
+
+/**
+ * @see Yaml::dump()
+ */
+function yaml_dump(mixed $input, int $inline = 2, int $indent = 4, int $flags = 0): string
+{
+    return Yaml::dump($input, $inline, $indent, $flags);
+}
+
 function guard_min_version(string $minVersion): void
 {
     $currentVersion = GlobalHelper::getApplication()->getVersion();

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

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

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

@@ -72,3 +72,5 @@ wait-for:wait-for-url-with-status-code-only                       Wait for an UR
 watch:fs-change                                                   Watches on filesystem changes
 watch:parallel-change                                             Watches on filesystem changes with 2 watchers in parallel
 watch:stop                                                        Watches on filesystem changes and stop after first change
+yaml:dump                                                         Dump a YAML content
+yaml:parse                                                        Parse a YAML content

tests/Examples/Generated/YamlDumpTest.php

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

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

@@ -0,0 +1,2 @@
+foo: bar
+

tests/Examples/Generated/YamlParseTest.php

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

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

@@ -0,0 +1 @@
+bar