feature: file enum anonymizer, inject samples in database from a plain text or csv file

Author: pounard

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Next
 
+* [feature] 🌟 File enum anonymizer, inject samples in database from a plain text or CSV file.
 * [feature] 🌟 String pattern anonymizer, build complex strings by fetching values from other anonymizers.
 * [internal] introduce anonymizer context for carrying environment configuration to anonymizers (#235).
 * [bc] Salt in `AbstractAnonymizer::$option->get('salt')` in now in `AbstractAnonymizer::$context->salt` (#235).

docs/content/anonymization/core-anonymizers.md

@@ -14,6 +14,7 @@ This page list all *Anonymizers* provided by *DbToolsBundle*.
 <!--@include: ./core-anonymizers/md5.md-->
 <!--@include: ./core-anonymizers/string.md-->
 <!--@include: ./core-anonymizers/pattern.md-->
+<!--@include: ./core-anonymizers/file-enum.md-->
 <!--@include: ./core-anonymizers/lastname.md-->
 <!--@include: ./core-anonymizers/firstname.md-->
 <!--@include: ./core-anonymizers/lorem-ipsum.md-->

docs/content/anonymization/core-anonymizers/address.md

@@ -95,6 +95,13 @@ customer:
   #...
 ```
 :::
+
+:::warning
+This anonymizer works at the *table level* which means that the PHP attribute
+cannot target object properties: you must specify table column names and not
+PHP class property names.
+:::
+
 @@@
 
 :::tip

docs/content/anonymization/core-anonymizers/file-enum.md

@@ -0,0 +1,79 @@
+## File enum
+
+This anonymizer will fill configured column with a random value from a given sample fetched
+from a plain text or a CSV file.
+
+Given the following file:
+
+```txt
+none
+bad
+good
+expert
+```
+
+Then:
+
+@@@ standalone docker
+
+```yaml [YAML]
+# db_tools.config.yaml
+anonymization:
+    default:
+        customer:
+            level:
+                anonymizer: file_enum
+                options: {source: ./resources/levels.txt}
+  #...
+```
+
+@@@
+@@@ symfony
+
+::: code-group
+```php [Attribute]
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use MakinaCorpus\DbToolsBundle\Attribute\Anonymize;
+
+#[ORM\Entity()]
+#[ORM\Table(name: 'customer')]
+class Customer
+{
+    // ...
+
+    #[ORM\Column(length: 255)]
+    #[Anonymize(type: 'string', options: ['source' => "./resources/levels.txt"])] // [!code ++]
+    private ?string $level = null;
+
+    // ...
+}
+```
+
+```yaml [YAML]
+# config/anonymization.yaml
+customer:
+    level:
+        anonymizer: file_enum
+        options: {source: ./resources/levels.txt}
+#...
+```
+:::
+
+@@@
+
+File will be read this way:
+ - When using a plain text file, each line is a value, no matter what's inside.
+ - When using a CSV file, the first column will be used instead.
+
+When parsing a file file, you can set the following options as well:
+  - `file_csv_enclosure`: if file is a CSV, use this as the enclosure character (default is `'"'`).
+  - `file_csv_escape`: if file is a CSV, use this as the escape character (default is `'\\'`).
+  - `file_csv_separator`: if file is a CSV, use this as the separator character (default is `','`).
+  - `file_skip_header`: when reading any file, set this to true to skip the first line (default is `false`).
+
+:::tip
+The filename can be absolute, or relative. For relative file resolution
+please see [*File name resolution*](#file-name-resolution)
+:::

docs/content/anonymization/core-anonymizers/iban-bic.md

@@ -74,4 +74,10 @@ customer:
 ```
 :::
 
+:::warning
+This anonymizer works at the *table level* which means that the PHP attribute
+cannot target object properties: you must specify table column names and not
+PHP class property names.
+:::
+
 @@@

src/Anonymization/AnonymizatorFactory.php

@@ -5,6 +5,7 @@
 namespace MakinaCorpus\DbToolsBundle\Anonymization;
 
 use MakinaCorpus\DbToolsBundle\Anonymization\Anonymizer\AnonymizerRegistry;
+use MakinaCorpus\DbToolsBundle\Anonymization\Anonymizer\Context;
 use MakinaCorpus\DbToolsBundle\Anonymization\Config\AnonymizationConfig;
 use MakinaCorpus\DbToolsBundle\Anonymization\Config\Loader\LoaderInterface;
 use MakinaCorpus\DbToolsBundle\Database\DatabaseSessionRegistry;
@@ -21,8 +22,24 @@ public function __construct(
         private DatabaseSessionRegistry $registry,
         private AnonymizerRegistry $anonymizerRegistry,
         private ?LoggerInterface $logger = null,
+        /**
+         * @todo
+         *   This is not the right place to set this, but any other alternative
+         *   would require a deep refactor of anonymizer options.
+         */
+        private ?string $basePath = null,
     ) {}
 
+    /**
+     * @internal
+     *   For Laravel dependency injection only.
+     *   This can change anytime.
+     */
+    public function setBasePath(?string $basePath): void
+    {
+        $this->basePath = $basePath;
+    }
+
     /**
      * Add configuration loader.
      */
@@ -49,7 +66,8 @@ public function getOrCreate(string $connectionName): Anonymizator
         $anonymizator = new Anonymizator(
             $this->registry->getDatabaseSession($connectionName),
             $this->anonymizerRegistry,
-            $config
+            $config,
+            new Context(basePath: $this->basePath),
         );
 
         if ($this->logger) {

src/Anonymization/Anonymizer/AnonymizerRegistry.php

@@ -17,6 +17,7 @@ class AnonymizerRegistry
         Core\ConstantAnonymizer::class,
         Core\DateAnonymizer::class,
         Core\EmailAnonymizer::class,
+        Core\FileEnumAnonymizer::class,
         Core\FirstNameAnonymizer::class,
         Core\FloatAnonymizer::class,
         Core\IbanBicAnonymizer::class,

src/Anonymization/Anonymizer/Context.php

@@ -7,11 +7,14 @@
 class Context
 {
     public readonly string $salt;
+    public readonly string $basePath;
 
     public function __construct(
         ?string $salt = null,
+        ?string $basePath = null,
     ) {
         $this->salt = $salt ?? self::generateRandomSalt();
+        $this->basePath = $basePath ?? \getcwd();
     }
 
     public static function generateRandomSalt(): string

src/Anonymization/Anonymizer/Core/FileEnumAnonymizer.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MakinaCorpus\DbToolsBundle\Anonymization\Anonymizer\Core;
+
+use MakinaCorpus\DbToolsBundle\Anonymization\Anonymizer\AbstractEnumAnonymizer;
+use MakinaCorpus\DbToolsBundle\Attribute\AsAnonymizer;
+use MakinaCorpus\DbToolsBundle\Helper\FileReader;
+
+#[AsAnonymizer(
+    name: 'file_enum',
+    pack: 'core',
+    description: <<<TXT
+    Anonymize any text value using a random element from the given file.
+    Options are:
+      - 'source': filename to load, filename must be absolute, or relative
+        to the configuration file directory.
+      - 'file_csv_enclosure': if file is a CSV, use this as the enclosure
+        character (default is '"').
+      - 'file_csv_escape': if file is a CSV, use this as the escape
+        character (default is '\\').
+      - 'file_csv_separator': if file is a CSV, use this as the separator
+        character (default is ',').
+      - 'file_skip_header': when reading any file, set this to true to skip
+        the first line (default is false).
+    TXT
+)]
+class FileEnumAnonymizer extends AbstractEnumAnonymizer
+{
+    private ?string $filename = null;
+
+    protected function getFilename(): string
+    {
+        if ($this->filename) {
+            return $this->filename;
+        }
+
+        $filename = $this->options->getString('source', null, true);
+        $filename = FileReader::ensurePathAbsolute($filename, $this->context->basePath);
+
+        FileReader::ensureFile($filename);
+
+        return $this->filename = $filename;
+    }
+
+    #[\Override]
+    protected function validateOptions(): void
+    {
+        parent::validateOptions();
+
+        $this->getFilename();
+    }
+
+    #[\Override]
+    protected function getSample(): array
+    {
+        return \iterator_to_array(
+            FileReader::readEnumFile(
+                $this->getFilename(),
+                $this->options,
+            )
+        );
+    }
+}

src/Bridge/Laravel/DbToolsServiceProvider.php

@@ -141,6 +141,8 @@ public function register(): void
         $this->app->resolving(
             AnonymizatorFactory::class,
             function (AnonymizatorFactory $factory, Application $app): void {
+                $factory->setBasePath($app->basePath());
+
                 /** @var Repository $config */
                 $config = $app->make('config');