Merge pull request #52 from andreaswolf/issue-5

[FEATURE] Fractor for Yaml files

Author: sabbelasichon

.github/workflows/lint_test_pull_requests.yaml

@@ -21,7 +21,7 @@ jobs:
             command: test:php
           - name: Rector
             command: 'rector --dry-run'
-        directory: [ 'extension-installer', 'fractor', 'fractor-xml', 'typo3-fractor', 'fractor-doc-generator' ]
+        directory: [ 'extension-installer', 'fractor', 'fractor-xml', 'typo3-fractor', 'fractor-doc-generator', 'fractor-yaml']
         exclude:
           - directory: extension-installer
             composer-command: {name: 'PHPUnit', command: 'test:php'}

README.md

@@ -6,7 +6,7 @@ Fractor is a generic tool for changing all kinds of files via defined rules—si
 
 The main package `a9f/fractor` provides infrastructure for configuring and running Fractor,
 but no rules for changing any files.
-These are provided by packages specific for filetypes (like `a9f/fractor-xml`) 
+These are provided by packages specific for filetypes (like `a9f/fractor-xml`)
 or ecosystems (like `a9f/typo3-fractor`).
 
 For different file types, different operation modes are possible.
@@ -24,17 +24,17 @@ there is no advanced support available right now.
 To utilize Fractor effectively, follow these steps:
 
 1. **Installation**:
-    - Install Fractor via Composer by running the following command in your terminal:
-      ```
-      composer require a9f/fractor a9f/fractor-xml
+   Install Fractor via Composer by running the following command in your terminal:
+```
+composer require a9f/fractor a9f/fractor-xml
 
-      # if you want to use Fractor with TYPO3, use this instead:
-      composer require a9f/typo3-fractor
-      ```
+# if you want to use Fractor with TYPO3, use this instead:
+composer require a9f/typo3-fractor
+```
 
 2. **Configuration**:
-    - Create a PHP configuration file (e.g., `fractor.php`) where you define the paths to your files.
-    - At minimum, a configuration file must specify the paths to process:
+   Create a PHP configuration file (e.g., `fractor.php`) where you define the paths to your files.
+   At minimum, a configuration file must specify the paths to process:
 ```php
 <?php
 
@@ -49,18 +49,18 @@ return FractorConfiguration::configure()
 ```
 
 3. **Running Fractor**:
-    - Execute Fractor from the command line, passing the path to your configuration file as an argument:
-      ```
-      ./vendor/bin/fractor process -f fractor.php
-      ```
+   Execute Fractor from the command line, passing the path to your configuration file as an argument:
+```
+./vendor/bin/fractor process -f fractor.php
+```
 
 4. **Review Changes**:
-    - Fractor will apply the rules specified in the configuration file to the targeted files.
-    - Review the changes made by Fractor to ensure they meet your expectations.
+   Fractor will apply the rules specified in the configuration file to the targeted files.
+   Review the changes made by Fractor to ensure they meet your expectations.
 
 5. **Customization**:
-    - You can modify existing rules or create new ones to tailor Fractor's behavior to your specific needs.
-    - See the "Extending Fractor" section for guidance on creating custom rules.
+   You can modify existing rules or create new ones to tailor Fractor's behavior to your specific needs.
+   See the "Extending Fractor" section for guidance on creating custom rules.
 
 ## Extending Fractor
 
@@ -71,27 +71,27 @@ Fractor can be extended with additional transformation rules and support for new
 Here's how you can extend Fractor with a custom rule:
 
 1. **Creating New Rules**:
-    - Create a new rule by subclassing the appropriate rule class for the file type,
-      e.g. `\a9f\FractorXml\XmlFractor` for XML files.
-    - Each rule should specify the conditions under which it should be applied and the corresponding changes to be made.
-    - Ideally, new rules also have a test case that validates that they work correctly.
+   - Create a new rule by subclassing the appropriate rule class for the file type,
+     e.g. `\a9f\FractorXml\XmlFractor` for XML files.
+   - Each rule should specify the conditions under which it should be applied and the corresponding changes to be made.
+   - Ideally, new rules also have a test case that validates that they work correctly.
 
 2. **Registering New Rules**:
-    - Register your custom rules within the Fractor configuration file.
+   - Register your custom rules within the Fractor configuration file.
 
 ### Supporting New File Types
 
 1. **Supporting New File Types**:
-    - To support a new file type, you will need to implement an instance of `\a9f\Fractor\Fractor\FileProcessor`. 
-      This processor must take care of decoding a file and then traversing the decoded file structure
-      (e.g. the DOM tree of an XML file; see `\a9f\FractorXml\XmlFileProcessor` for an example)
+   - To support a new file type, you will need to implement an instance of `\a9f\Fractor\Fractor\FileProcessor`.
+     This processor must take care of decoding a file and then traversing the decoded file structure
+     (e.g. the DOM tree of an XML file; see `\a9f\FractorXml\XmlFileProcessor` for an example)
 
 2. **Testing**:
-    - Thoroughly test your extensions to ensure they function as expected and do not introduce unintended side effects.
-    - Write unit tests for your custom rules and parsers to maintain code quality and stability.
+   - Thoroughly test your extensions to ensure they function as expected and do not introduce unintended side effects.
+   - Write unit tests for your custom rules and parsers to maintain code quality and stability.
 
 3. **Documentation**:
-    - Document your custom rules and file type extensions to aid other users in understanding and utilizing your contributions.
+   - Document your custom rules and file type extensions to aid other users in understanding and utilizing your contributions.
 
 By extending Fractor in this manner, you can enhance its capabilities and adapt it to handle a wider range of file formats and transformation scenarios.
 

fractor-yaml/.gitignore

@@ -0,0 +1,3 @@
+/vendor/
+/composer.lock
+.phpunit.cache

fractor-yaml/composer.json

@@ -0,0 +1,57 @@
+{
+    "name": "a9f/fractor-yaml",
+    "description": "YAML extension for the File Read-Analyse-Change TOol. Allows modifying YAML files",
+    "license": "MIT",
+    "type": "fractor-extension",
+    "authors": [
+        {
+            "name": "Andreas Wolf",
+            "email": "[email protected]",
+            "role": "Lead Developer"
+        }
+    ],
+    "require": {
+        "php": "^8.2",
+        "a9f/fractor": "@dev",
+        "a9f/fractor-extension-installer": "@dev",
+        "symfony/yaml": "^6.0",
+        "webmozart/assert": "^1.11"
+    },
+    "require-dev": {
+        "ergebnis/composer-normalize": "^2.42",
+        "phpstan/phpstan": "^1.10",
+        "phpunit/phpunit": "^10.5",
+        "rector/rector": "^1.0",
+        "symplify/easy-coding-standard": "^12.1"
+    },
+    "repositories": {
+        "fractor": {
+            "type": "path",
+            "url": "../*"
+        }
+    },
+    "autoload": {
+        "psr-4": {
+            "a9f\\FractorYaml\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "a9f\\FractorYaml\\Tests\\": "tests/"
+        }
+    },
+    "config": {
+        "allow-plugins": {
+            "a9f/fractor-extension-installer": true,
+            "ergebnis/composer-normalize": true
+        },
+        "sort-packages": true
+    },
+    "scripts": {
+        "analyze:php": "phpstan analyze",
+        "rector": "rector",
+        "style:php:check": "ecs",
+        "style:php:fix": "ecs --fix",
+        "test:php": "phpunit"
+    }
+}

fractor-yaml/config/application.php

@@ -0,0 +1,27 @@
+<?php
+
+use a9f\FractorYaml\Contract\YamlDumper;
+use a9f\FractorYaml\Contract\YamlFractorRule;
+use a9f\FractorYaml\Contract\YamlParser;
+use a9f\FractorYaml\SymfonyYamlDumper;
+use a9f\FractorYaml\SymfonyYamlParser;
+use a9f\FractorYaml\YamlFileProcessor;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+use function Symfony\Component\DependencyInjection\Loader\Configurator\tagged_iterator;
+
+return static function (ContainerConfigurator $containerConfigurator, ContainerBuilder $containerBuilder): void {
+    $services = $containerConfigurator->services();
+    $services->defaults()
+        ->autowire()
+        ->autoconfigure();
+
+    $services->load('a9f\\FractorYaml\\', __DIR__ . '/../src/');
+
+    $services->alias(YamlParser::class, SymfonyYamlParser::class);
+    $services->alias(YamlDumper::class, SymfonyYamlDumper::class);
+
+    $services->set(YamlFileProcessor::class)->arg('$rules', tagged_iterator('fractor.yaml_rule'));
+
+    $containerBuilder->registerForAutoconfiguration(YamlFractorRule::class)->addTag('fractor.yaml_rule');
+};

fractor-yaml/ecs.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+return (include __DIR__ . '/../.build/ecs.php')
+    ->withPaths([
+        __DIR__ . '/config',
+        __DIR__ . '/src',
+        __DIR__ . '/tests',
+    ])
+     ;

fractor-yaml/phpstan.neon

@@ -0,0 +1,6 @@
+parameters:
+    level: 8
+
+    paths:
+        - src/
+        - tests/

fractor-yaml/phpunit.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd" bootstrap="vendor/autoload.php" colors="true" cacheDirectory=".phpunit.cache">
+  <testsuites>
+    <testsuite name="fractor-yaml">
+      <directory>tests</directory>
+    </testsuite>
+  </testsuites>
+  <source>
+    <include>
+      <directory>./src</directory>
+    </include>
+  </source>
+</phpunit>

fractor-yaml/rector.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+return (include __DIR__ . '/../.build/rector.php')
+    ->withPaths([
+        __DIR__ . '/config',
+        __DIR__ . '/src',
+        __DIR__ . '/tests',
+    ]);

fractor-yaml/src/Contract/YamlDumper.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace a9f\FractorYaml\Contract;
+
+use a9f\Fractor\ValueObject\Indent;
+
+interface YamlDumper
+{
+    /**
+     * @param mixed[] $input
+     */
+    public function dump(array $input, Indent $indent): string;
+}

fractor-yaml/src/Contract/YamlFractorRule.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace a9f\FractorYaml\Contract;
+
+use a9f\Fractor\Application\Contract\FractorRule;
+
+interface YamlFractorRule extends FractorRule
+{
+    /**
+     * @param mixed[] $yaml
+     * @return mixed[]
+     */
+    public function refactor(array $yaml): array;
+}

fractor-yaml/src/Contract/YamlParser.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace a9f\FractorYaml\Contract;
+
+use a9f\Fractor\Application\ValueObject\File;
+use a9f\FractorYaml\Exception\ParseException;
+
+interface YamlParser
+{
+    /**
+     * @return mixed[]
+     * @throws ParseException
+     * /**
+     */
+    public function parse(File $file): array;
+}

fractor-yaml/src/Exception/ParseException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace a9f\FractorYaml\Exception;
+
+final class ParseException extends \RuntimeException
+{
+}

fractor-yaml/src/SymfonyYamlDumper.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace a9f\FractorYaml;
+
+use a9f\Fractor\ValueObject\Indent;
+use a9f\FractorYaml\Contract\YamlDumper;
+use Symfony\Component\Yaml\Yaml;
+
+final class SymfonyYamlDumper implements YamlDumper
+{
+    public function dump(array $input, Indent $indent): string
+    {
+        return Yaml::dump($input, 99, $indent->length());
+    }
+}

fractor-yaml/src/SymfonyYamlParser.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace a9f\FractorYaml;
+
+use a9f\Fractor\Application\ValueObject\File;
+use a9f\FractorYaml\Contract\YamlParser;
+use a9f\FractorYaml\Exception\ParseException;
+use Symfony\Component\Yaml\Exception\ParseException as YamlParseException;
+use Symfony\Component\Yaml\Yaml;
+
+final class SymfonyYamlParser implements YamlParser
+{
+    public function parse(File $file): array
+    {
+        try {
+            return Yaml::parse($file->getContent(), Yaml::PARSE_CUSTOM_TAGS) ?? [];
+        } catch (YamlParseException $parseException) {
+            $parseException->setParsedFile($file->getFilePath());
+
+            throw new ParseException($parseException->getMessage());
+        }
+    }
+}