diff --git a/config/db_tools.standalone.complete.sample.yaml b/config/db_tools.standalone.complete.sample.yaml index 3301a9f..8a60571 100644 --- a/config/db_tools.standalone.complete.sample.yaml +++ b/config/db_tools.standalone.complete.sample.yaml @@ -33,12 +33,13 @@ # Default timeout for restore process. #restore_timeout: 2400 # default 1800 -# List here tables (you don't want in your backups. +# List here tables you don't want in your backups. # If you have more than one connection, it is strongly advised to configure # this for each connection instead. #backup_excluded_tables: ['table1', 'table2'] -# Specify here paths to backup and restore binaries and command line options. +# Specify here paths to backup and restoration binaries and command line +# options. # Warning: this will apply to all connections disregarding their database # vendor. If you have more than one connection and if they use different # database vendors or versions, please configure those for each connection @@ -54,7 +55,7 @@ # Connection name will be "default" when configured this way. connections: "pgsql://username:password@hostname:port?version=16.0&other_option=..." -# Alternatively, you are allowed to have more than one connections, case +# Alternatively, you are allowed to have more than one connection, case # in which you might synthesize the configuration as this: #connections: # connection_one: "pgsql://username:password@hostname:port?version=16.0&other_option=..." @@ -66,7 +67,8 @@ connections: "pgsql://username:password@hostname:port?version=16.0&other_option= #connections: # connection_one: # # Connection URL for connecting. -# # Please refer to makinacorpus/db-query-builder or documentation for more information. +# # Please refer to makinacorpus/db-query-builder or documentation for +# # more information. # # Any URL built for doctrine/dbal usage should work. # # URL is the sole mandatory parameter. # # Complete list of accepted parameters follows. @@ -85,14 +87,15 @@ connections: "pgsql://username:password@hostname:port?version=16.0&other_option= # url: "mysql://username:password@hostname:port?version=8.1&other_option=..." # # ... -# You can explicitely set which will be default connection in use when -# none providen in the command line options. If you omit this configuration +# You can explicitly set which will be default connection in use when none +# is provided in the command line options. If you omit this configuration # value, then the first one in the list will be used. #default_connection: connection_one -# Update this configuration if you want to look for anonymizers in a custom folder. +# Update this configuration if you want to look for anonymizers in a custom +# folder. #anonymizer_paths: - #- ./src/Anonymization/Anonymizer' +# - ./src/Anonymizer # For simple needs, you may simply write the anonymization configuration here. # Keys are connection names, values are structures which are identical to what @@ -112,8 +115,8 @@ anonymization: # You can for organisation purpose delegate anonymization config into extra # YAML configuration files, and simply reference them here. -# Pathes can be either relative or absolute. Relative paths are relative to -# the workdir option if specified, or from this configuration file directory +# Paths can be either relative or absolute. Relative paths are relative to +# the workdir option if specified, or from this configuration file directory # otherwise. # See the "anonymizations.sample.yaml" in this folder for an example. anonymization_files: diff --git a/config/db_tools.standalone.sample.yaml b/config/db_tools.standalone.sample.yaml index 86e283d..53bae9c 100644 --- a/config/db_tools.standalone.sample.yaml +++ b/config/db_tools.standalone.sample.yaml @@ -1,10 +1,10 @@ # This configuration file is an example for standalone usage. -# Only required parameter is the connection URL. +# The only required parameter is the connection URL. # If you have a single connection, you can use this syntax. # Connection name will be "default" when configured this way. # If you have multiple connections, please refer to the exhaustive -# sample in 'db_tools.standalone.complete.sample.yaml'. +# sample in 'db_tools.standalone.complete.sample.yaml'. connections: "pgsql://username:password@hostname:port?version=16.0&other_option=..." # Where to put generated backups. @@ -27,21 +27,22 @@ connections: "pgsql://username:password@hostname:port?version=16.0&other_option= # (Use relative date/time formats : https://www.php.net/manual/en/datetime.formats.relative.php) #backup_expiration_age: '6 months ago' # default '3 months ago' -# List here tables (you don't want in your backups. +# List here tables you don't want in your backups. # If you have more than one connection, it is strongly advised to configure # this for each connection instead. #backup_excluded_tables: ['table1', 'table2'] -# Update this configuration if you want to look for anonymizers in a custom folder. +# Update this configuration if you want to look for anonymizers in a custom +# folder. #anonymizer_paths: - #- ./src/Anonymization/Anonymizer' +# - ./src/Anonymizer' # Write the anonymization configuration here. # You may also write anonymization configuration in extra files instead, please -# see the 'db_tools.standalone.complete.sample.yaml' for more documentation. +# see the 'db_tools.standalone.complete.sample.yaml' for more documentation. #anonymization: -# # Keys are connection names, values are structures which are identical to what -# # you may find in the "anonymizations.sample.yaml" example. +# # Keys are connection names, values are structures which are identical to +# # what you may find in the "anonymizations.sample.yaml" example. # # If you only specified one URL in the "connections" parameter above, the # # connection name is "default". # default: diff --git a/config/packages/db_tools.yaml b/config/packages/db_tools.yaml index 573742f..2d0a0f4 100644 --- a/config/packages/db_tools.yaml +++ b/config/packages/db_tools.yaml @@ -16,7 +16,8 @@ db_tools: # - "default": alias of "datetime". # - "datetime": implementation is "%db_tools.storage_directory%/YYYY/MM/-.". # - CLASS_NAME: a class name to use that implements a strategy. - # - SERVICE_ID: A service identifier registered in container that implements a strategy. + # - SERVICE_ID: A service identifier registered in container that + # implements a strategy. #storage_filename_strategy: default # When old backups are considered obsolete. @@ -29,12 +30,13 @@ db_tools: # Default timeout for restore process. #restore_timeout: 2400 # default 1800 - # List here tables (you don't want in your backups. + # List here tables you don't want in your backups. # If you have more than one connection, it is strongly advised to configure # this for each connection instead. #backup_excluded_tables: ['table1', 'table2'] - # Specify here paths to backup and restore binaries and command line options. + # Specify here paths to backup and restoration binaries and command line + # options. # Warning: this will apply to all connections disregarding their database # vendor. If you have more than one connection and if they use different # database vendors or versions, please configure those for each connection @@ -67,16 +69,17 @@ db_tools: # connection_two: # # ... - # Update this configuration if you want to look for anonymizers in a custom folder. - # These are default paths that will always be registered even if you override - # the setting so please don't repeat them: + # Update this configuration if you want to look for anonymizers in a custom + # folder. + # Be aware that DbToolsBundle will always take a look at the default folder + # dedicated to your custom anonymizers: %kernel.project_dir%/src/Anonymizer, + # so you don't have to repeat it. #anonymizer_paths: - #- '%kernel.project_dir%/vendor/makinacorpus/db-tools-bundle/src/Anonymization/Anonymizer/Core' - #- '%kernel.project_dir%/src/Anonymization/Anonymizer' + # - '%kernel.project_dir%/src/Database/Anonymizer' - # For simple needs, you may simply write the anonymization configuration here. - # Keys are connection names, values are structures which are identical to what - # you may find in the "anonymizations.sample.yaml" example. + # For simple needs, you may simply write the anonymization configuration + # here. Keys are connection names, values are structures which are identical + # to what you may find in the "anonymizations.sample.yaml" example. #anonymization: # connection_one: # table1: @@ -92,8 +95,8 @@ db_tools: # You can for organisation purpose delegate anonymization config into extra # YAML configuration files, and simply reference them here. - # Pathes can be either relative or absolute. Relative paths are relative to - # the workdir option if specified, or from this configuration file directory + # Paths can be either relative or absolute. Relative paths are relative to + # the workdir option if specified, or from this configuration file directory # otherwise. # See the "anonymizations.sample.yaml" in this folder for an example. #anonymization_files: diff --git a/docs/README.md b/docs/README.md index 77a2f6b..8fe8dfa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,4 +9,5 @@ To build it locally : ```sh nvm use npm ci -npm run docs:dev \ No newline at end of file +npm run docs:dev +``` diff --git a/docs/content/anonymization/custom-anonymizers.md b/docs/content/anonymization/custom-anonymizers.md index a91e58f..c21b8a3 100644 --- a/docs/content/anonymization/custom-anonymizers.md +++ b/docs/content/anonymization/custom-anonymizers.md @@ -6,7 +6,7 @@ To create one, you will need to -1. add a class in the `src/Anonymizer` directory extends `AbstractAnonymizer` +1. add a class extending `AbstractAnonymizer` in the `src/Anonymizer` directory 2. add the `AsAnonymizer` attribute on it ```php @@ -24,8 +24,8 @@ use MakinaCorpus\DbToolsBundle\Attribute\AsAnonymizer; )] class MyAnonymizer extends AbstractAnonymizer { - - // ... + // ... +} ``` To understand how an `Anonymizer` works, read `vendor/makinacorpus/db-tools-bundle/src/Anonymizer/AbstractAnonymizer.php` @@ -40,7 +40,7 @@ with the [*Anonymizer paths* configuration](../configuration/basics#anonymizer-p ::: tip To generate its update queries, *DbToolsBundle* uses the *[makinacorpus/query-builder-bundle](https://github.com/makinacorpus/query-builder-bundle) package*. -If you want to create your own anonymizers, you will problably need to take a look at +If you want to create your own anonymizers, you will probably need to take a look at [its basic uses](https://php-query-builder.readthedocs.io/en/stable/introduction/usage.html). ::: @@ -70,21 +70,19 @@ use MakinaCorpus\DbToolsBundle\Attribute\AsAnonymizer; )] class MyEnumAnonymizer extends AbstractEnumAnonymizer { - #[\Override] protected function getSample(): array { // Generate here your sample. - return ['Foo', 'Bar', 'Baz']; } } ``` -## Mutlicolumn Anonymizers +## Multicolumn Anonymizers -As for an enum anonymizer, if you need to create a mutlicolumn anonymizer based on a big sample, you can extend the -*AbstractMultipleColumnAnonymizer*. +As for an enum anonymizer, if you need to create a multicolumn anonymizer based +on a big sample, you can extend the *AbstractMultipleColumnAnonymizer*. Here is a complete example: @@ -106,8 +104,7 @@ class MyMulticolumnAnonymizer extends AbstractMultipleColumnAnonymizer #[\Override] protected function getColumnNames(): array { - // Declare here name fo each part of your multicolumn - // anonymizer + // Declare here name of each part of your multicolumn anonymizer. return [ 'part_one', 'part_two', @@ -119,13 +116,12 @@ class MyMulticolumnAnonymizer extends AbstractMultipleColumnAnonymizer protected function getSample(): array { // Generate here your sample. - return [ - ['Foo', 'Bar', 'Baz'], - ['Foo1', 'Bar1', 'Baz1'], - ['Foo2', 'Bar2', 'Baz2'], - ['Foo3', 'Bar3', 'Baz3'], + ['Foo', 'Bar', 'Baz'], + ['Foo1', 'Bar1', 'Baz1'], + ['Foo2', 'Bar2', 'Baz2'], + ['Foo3', 'Bar3', 'Baz3'], ]; } } -``` \ No newline at end of file +``` diff --git a/docs/content/anonymization/workflow.md b/docs/content/anonymization/workflow.md index b86ce0a..62d896e 100644 --- a/docs/content/anonymization/workflow.md +++ b/docs/content/anonymization/workflow.md @@ -50,7 +50,7 @@ For example, you can automate this workflow **as a CI job** and therefore use a to play the *intermediate environment* role. This approach has many benefits: -* You don't need to backup and restore initial state of this environment: +* You don't need to back up and restore initial state of this environment: the `vendor/bin/db-tools anonymize``php bin/console db-tools:anonymize` will be faster, * You can store the anonymized backup as a CI artefact, it will then be automatically available for diff --git a/docs/content/backup_restore.md b/docs/content/backup_restore.md index 4f93146..9ca02f7 100644 --- a/docs/content/backup_restore.md +++ b/docs/content/backup_restore.md @@ -1,7 +1,7 @@ -# Backup and Restore +# Back up and Restore -*DbToolsBundle* comes with two commands to back up and restore -your database but also a tiny backups manager which handle backup files for you. +*DbToolsBundle* comes with two commands to back up and restore your database +but also a tiny backups manager which handle backup files for you. ## Backup command @@ -36,7 +36,7 @@ You can specify the behavior of the command with some options detailed below.
-By default, the command will backup the database from the default connection. +By default, the command will back up the database from the default connection. If you configured several ones, you can choose to back up a database from a specific connection with `--connection` option: @@ -48,7 +48,7 @@ vendor/bin/db-tools backup --connection other_connection_name
-By default, the command will backup the database from the default DBAL connection. +By default, the command will back up the database from the default DBAL connection. You can choose to back up a database from another connection with `--connection` option: diff --git a/docs/content/configuration/basics.md b/docs/content/configuration/basics.md index e8b7a8b..a7728c2 100644 --- a/docs/content/configuration/basics.md +++ b/docs/content/configuration/basics.md @@ -8,15 +8,15 @@ Select below your target:
-*DbToolsBundle* let you configure some of its behaviors. As with any classic Symfony Bundle, -all will take place in the `config/packages/db_tools.yaml` file. +*DbToolsBundle* let you configure some of its behaviors. As with any classic +Symfony Bundle, all will take place in the `config/packages/db_tools.yaml` file. :::tip -A complete example of this file can be found in the bundle sources in: `vendor/makinacorpus/db-tools-bundle/config/packages/db_tools.yaml`. +A complete example of this file can be found in the bundle sources in: +`vendor/makinacorpus/db-tools-bundle/config/packages/db_tools.yaml`. :::
-
*DbToolsBundle* let you configure some of its behaviors @@ -25,7 +25,8 @@ all will take place in your configuration file, usually `db_tools.yaml`. :::tip **In this page, all paths are relative to the `db_tools.yaml` configuration file.** -A complete example of this file can be found in the library sources in: `vendor/makinacorpus/db-tools-bundle/config/db_tools.standalone.complete.sample.yaml`. +A complete example of this file can be found in the library sources in: +`vendor/makinacorpus/db-tools-bundle/config/db_tools.standalone.complete.sample.yaml`. :::
@@ -34,8 +35,9 @@ For detailed information about configuration options, please see the [configuration reference](../configuration/reference). :::tip -**Almost every configuration option can be configured at the connection level** for example the -backup excluded tables can either be configured top-level (for all connections): +**Almost every configuration option can be configured at the connection level**. +For example, the backup excluded tables can either be configured top-level (for +all connections):
@@ -78,8 +80,8 @@ connections:
-When working with multiple connections, any connection which does not specify the option -will inherit from the default. +When working with multiple connections, any connection which does not specify +the option will inherit from the default. ::: ## Backup configuration @@ -94,21 +96,21 @@ The `storage_directory` parameter let you choose where to put the generated dump
-Default value is `'%kernel.project_dir%/var/db_tools'`. +Default value is `%kernel.project_dir%/var/db_tools`.
-
-Default value is `./var/db_tools'`. +Default value is `./var/db_tools`.
#### File and directory naming strategy -Default behavior will store your backup using this strategy: -`%storage_directory%///-.` -where `` is the file extension depending upon the database vendor (mostly `.sql` or `.dump`). +Default behavior will store your backup under the [storage root directory](#root-directory) +by using this filename strategy: +`//-.` +where `` is the file extension depending upon the database backend (mostly `.sql` or `.dump`).
@@ -133,22 +135,30 @@ class FooFilenameStrategy extends AbstractFilenameStrategy } ``` -Then registered this way, on a per-connection basis: +Then registered this way to impact all connections: ```yaml # config/packages/db_tools.yaml db_tools: - storage: - filename_strategy: - connection_name: App\DbTools\Storage\FooFilenameStrategy + storage_filename_strategy: App\DbTools\Storage\FooFilenameStrategy +``` + +Or for a specific connection: + +```yaml +# config/packages/db_tools.yaml +db_tools: + connections: + connection_name: + storage_filename_strategy: App\DbTools\Storage\FooFilenameStrategy ``` -Value can be a container service identifier, or directly a class name in case this -has no constructor arguments. +Value can be a container service identifier, or directly a class name in case +this has no constructor arguments. -If you need to store your dumps outside of the `%storage_directory%` directory, -then implement the `MakinaCorpus\DbToolsBundle\Storage\FilenameStrategyInterface` directly -and add the following method: +If you need to store your dumps outside the `%storage_directory%` directory, +then implement the `MakinaCorpus\DbToolsBundle\Storage\FilenameStrategyInterface` +directly and add the following method: ```php namespace App\DbTools\Storage; @@ -170,15 +180,14 @@ class FooFilenameStrategy implements FilenameStrategyInterface } ``` -This will allow the restore command to find your backups. +This will allow the _restore_ command to find your backups.
-
:::warning -There is as of now no way to implement a custom filename strategy when using *DbToolsBundle* as a standalone -CLI tool. +There is as of now no way to implement a custom filename strategy when using +*DbToolsBundle* as a standalone CLI tool. If you need this feature, please let us know by [filing an issue](https://github.com/makinacorpus/DbToolsBundle/issues). ::: @@ -186,8 +195,8 @@ If you need this feature, please let us know by [filing an issue](https://github
:::info -More filename strategies may be implemented in core in the future. If you have any -suggestions, please [open an discussion](https://github.com/makinacorpus/DbToolsBundle/issues) about it. +More filename strategies may be implemented in core in the future. If you have +any suggestions, please [open a discussion](https://github.com/makinacorpus/DbToolsBundle/issues) about it. ::: ### Excluded tables @@ -240,8 +249,8 @@ connections:
:::tip -Note that you can override this configuration while running the `db-tools:backup` command using -the `--exclude` option. +Note that you can override this configuration while running the `db-tools:backup` +command using the `--exclude` option. ::: ### Binary options @@ -250,7 +259,8 @@ See the [default binary options](#default-binary-options) section. ### Backup expiration age -The `backup_expiration_age` parameter let you choose when a backup is considered as obsolete. +The `backup_expiration_age` parameter let you choose when a backup is considered +as obsolete. Default value is `'3 months ago'`. @@ -300,10 +310,10 @@ connections: ``` -### Backup and restore timeout +### Backup and restoration timeout -The `backup_timeout` and `restore_timeout` options let you choose what is the backup and restore -processes timeout in seconds. +The `backup_timeout` and `restore_timeout` options let you choose what is the +backup and restoration processes timeout in seconds. Default value is `600` (seconds) for backup, `1800` (seconds) for restore. @@ -396,8 +406,9 @@ php vendor/bin/db-tools database:check If the `db-tools:check` command returns you some errors: - * if your binaries are present on your system but *DbToolsBundle* can't find them you will need - to specify path for these binaries: + +* if your binaries are present on your system but *DbToolsBundle* can't find + them you will need to specify path for these binaries:
@@ -417,9 +428,9 @@ If the `db-tools:check` command returns you some errors: ```
- * Backup and restore binaries, as well as command line arguments and options are - configured on a per-connection basis. If you have more than one connection, - use the following syntax instead: +* Backup and restoration binaries, as well as command line arguments and + options, are configured on a per-connection basis. If you have more than + one connection, use the following syntax instead:
@@ -449,7 +460,8 @@ If the `db-tools:check` command returns you some errors: ```
- * Or, if your binaries are not present on your system: you will need to install them. +* Or, if your binaries are not present on your system: you will need to install + them. :::tip If your app lives in the [official PHP docker image](https://hub.docker.com/_/php/), @@ -500,10 +512,10 @@ db_tools: connections: connection_one: backup_options: '--an-option' - restor_options: '-xyz --another' + restore_options: '-xyz --another' connection_two: backup_options: '--a-first-one --a-second-one' - restor_options: '-O sample-value' + restore_options: '-O sample-value' ```
@@ -523,10 +535,10 @@ Or set a specific value list for each connection: connections: connection_one: backup_options: '--an-option' - restor_options: '-xyz --another' + restore_options: '-xyz --another' connection_two: backup_options: '--a-first-one --a-second-one' - restor_options: '-O sample-value' + restore_options: '-O sample-value' ```
@@ -548,68 +560,67 @@ according to the database vendor:
-By default, *DbToolsBundle* will look for custom *anonymizers* in 2 directories: - -* `%kernel.project_dir%/vendor/makinacorpus/db-tools-bundle/src/Anonymizer` -* `%kernel.project_dir%/src/Anonymizer` - -If you want to put custom anonymizers in another directory or if you want to load -a pack of anonymizers from an external library, you can modify/add paths: +By default, *DbToolsBundle* will look for custom *anonymizers* in the +`%kernel.project_dir%/src/Anonymizer` directory. +If you want to put custom anonymizers in another directory or if you want to +load a pack of anonymizers from an external library, you can add paths to the +`anonymizer_paths` parameter: ```yml # config/packages/db_tools.yaml db_tools: anonymizer_paths: - - '%kernel.project_dir%/src/Anonymizer' - - '%kernel.project_dir%/vendor/myAnonymizerProvider/anonymizers/src' + - '%kernel.project_dir%/src/Database/Anonymizer' + - '%kernel.project_dir%/vendor/anonymizer-provider/src' # ... ```
-By default, *DbToolsBundle* when used as a standalone CLI tool will not lookup for -custom *anonymizers*. - -If you want to write custom anonymizers, in order for them to be found, you must specify -paths where the source code lies: +By default, *DbToolsBundle* will only consider core *anonymizers* when used as +a standalone CLI tool. It won't look for any custom anonymizers. +If you want to write custom anonymizers, you will have to tell *DbToolsBundle* +where to find their implementations by specifying concerned directories through +the `anonymizer_paths` parameter: ```yml # db_tools.yaml -db_tools: - anonymizer_paths: - - './src/Anonymizer' - - './vendor/myAnonymizerProvider/anonymizers/src' - # ... +anonymizer_paths: + - './src/Anonymizer' + - './vendor/anonymizer-provider/src' + # ... ```
:::tip -Core provided anonymizers and anonymizers that are in packs installed using composer -will always be looked-up. +Core provided anonymizers as well as those contained in packs installed with +composer will always be loaded automatically. ::: :::warning -Packs must be installed using composer: *DbToolsBundle* uses composer generated metadata -about installed packages to find them. +Packs must be installed using composer: *DbToolsBundle* uses composer generated +metadata about installed packages to find them. ::: ## Anonymization
-Per default, **DbToolsBundle** will only look for anonymization configurations from PHP attributes on Doctrine Entities. +By default, *DbToolsBundle* will only look for anonymization configurations +from PHP attributes on Doctrine Entities. -But *DbToolsBundle* does not necessary need Doctrine ORM to anonymize your data, it can do it just with a DBAL connection. -In this case (or if you prefer YAML over attributes): you can configure *DbToolsBundle* to look for anonymization -configurations in a YAML file: +But *DbToolsBundle* does not necessary need Doctrine ORM to anonymize your data, +it can do it just with a DBAL connection. In this case (or if you prefer YAML +over attributes): you can configure *DbToolsBundle* to look for anonymization +configurations in YAML files: ```yml # config/packages/db_tools.yaml db_tools: - # When you have a single connection, and a single file: + # When you have a single connection and prefer a single configuration file: anonymization_files: '%kernel.project_dir%/config/anonymizations.yaml' # Or with multiple connections: @@ -617,7 +628,7 @@ db_tools: connection_one: '%kernel.project_dir%/config/anonymizations/connection_one.yaml' connection_two: '%kernel.project_dir%/config/anonymizations/connection_two.yaml' - # Each connection may have multiple files: + # Each connection may have multiple files: anonymization_files: connection_one: - '%kernel.project_dir%/config/anonymizations/connection_one_1.yaml' @@ -628,13 +639,14 @@ db_tools:
-You need to register your anonymization configuration for the anonymization feature to work: +You need to register your anonymization configuration for the anonymization +feature to work: ```yml # config/packages/db_tools.yaml db_tools: - # When you have a single connection, and a single file: + # When you have a single connection and prefer a single configuration file: anonymization_files: './anonymizations.yaml' # Or with multiple connections: @@ -642,16 +654,17 @@ db_tools: connection_one: './anonymizations/connection_one.yaml' connection_two: './anonymizations/connection_two.yaml' - # Each connection may have multiple files: + # Each connection may have multiple files: anonymization_files: connection_one: - - './config/anonymizations/connection_one_1.yaml' - - './config/anonymizations/connection_one_2.yaml' + - './anonymizations/connection_one_1.yaml' + - './anonymizations/connection_one_2.yaml' # ... ```
:::tip -For more information about anonymization and configuration file structure, refer to the [Anonymization section](../anonymization/essentials). +For more information about anonymization and configuration file structure, +refer to the [Anonymization section](../anonymization/essentials). ::: diff --git a/docs/content/configuration/reference.md b/docs/content/configuration/reference.md index 018fa82..7df6f97 100644 --- a/docs/content/configuration/reference.md +++ b/docs/content/configuration/reference.md @@ -122,7 +122,7 @@ db_tools: connection_one: '%kernel.project_dir%/config/anonymizations/connection_one.yaml' connection_two: '%kernel.project_dir%/config/anonymizations/connection_two.yaml' -# Each connection may have multiple files: +# Each connection may have multiple files: db_tools: anonymization_files: connection_one: @@ -152,7 +152,7 @@ anonymization_files: connection_one: './anonymizations/connection_one.yaml' connection_two: './anonymizations/connection_two.yaml' -# Each connection may have multiple files: +# Each connection may have multiple files: anonymization_files: connection_one: - './anonymizations/connection_one_1.yaml' @@ -165,14 +165,15 @@ Whenever you have a single unamed connection, its name will be `default`. ::: :::tip -File paths can be relative, any relative path will be relative to this configuration -file directory. +File paths can be relative, any relative path will be relative to this +configuration file directory. ::: :::tip -For more information about anonymization and configuration file structure, refer to the [Anonymization section](../anonymization/essentials). +For more information about anonymization and configuration file structure, +refer to the [Anonymization section](../anonymization/essentials). ::: @@ -183,17 +184,20 @@ PHP source folders in which custom anonymizer implementations will be looked-up. This allows you to write custom implementations and use it. Path are local filesystem arbitrary paths, and you are allowed to set any path. -A recursive file system iterator will lookup in those folders and find classes -that extend the `MakinaCorpus\DbToolsBundle\Anonymization\Anonymizer\AbstractAnonymizer` -class within, then register those as anonymizers. +A recursive filesystem iterator will look in those folders for classes extending +the `MakinaCorpus\DbToolsBundle\Anonymization\Anonymizer\AbstractAnonymizer` +class and register them as anonymizers.
+Be aware that DbToolsBundle will always take a look at the default folder +dedicated to your custom anonymizers: `%kernel.project_dir%/src/Anonymizer`, +so you don't have to repeat it. + ```yaml db_tools: anonymizer_paths: - - '%kernel.project_dir%/vendor/makinacorpus/db-tools-bundle/src/Anonymizer' - - '%kernel.project_dir%/src/Anonymization/Anonymizer' + - '%kernel.project_dir%/src/Database/Anonymizer' ``` :::tip @@ -205,25 +209,22 @@ File paths must be absolute, use Symfony parameters to refer the project root. ```yaml anonymizer_paths: - - './vendor/makinacorpus/db-tools-bundle/src/Anonymizer' - - './src/Anonymization/Anonymizer' + - './src/Anonymizer' ``` :::tip -File paths can be relative, any relative path will be relative to this configuration -file directory. +File paths can be relative, any relative path will be relative to this +configuration file directory. :::
- ## `backup_binary` Path to backup command in filesystem. -Defaults are the well known executable names without absolute file path, which should -work in most Linux distributions. - +Defaults are the well known executable names without absolute file path, which +should work in most Linux distributions.
@@ -242,11 +243,11 @@ backup_binary: /usr/bin/pg_dump :::warning This top level parameter applies to all connections per default. -If you need a different value per connection, the setting can also be configured on a -per connection basis under the `connections.CONNECTION.backup_binary` name. +If you need a different value per connection, the setting can also be configured +on a per-connection basis under the `connections.CONNECTION.backup_binary` name. -If you have more than one connection using different database vendor, it is strongly -advised to override at the connection level. +If you have more than one connection using different database vendor, it is +strongly advised to override at the connection level. ::: diff --git a/docs/content/contribute/pack.md b/docs/content/contribute/pack.md index 1c9978b..1f4b115 100644 --- a/docs/content/contribute/pack.md +++ b/docs/content/contribute/pack.md @@ -129,16 +129,18 @@ Learn more about how to develop them reading the [Custom Anonymizers section](.. ## 3. Test your anonymizers -After you built your anonymizers, don't forget to test them. We recommend doing at least one functionnal test per anonymizer. -To inspire you doing these tests, read [existing tests in DbToolsBundle](https://github.com/makinacorpus/DbToolsBundle/tree/main/tests/Functional/Anonymizer/Core) +After you built your anonymizers, don't forget to test them. We recommend doing +at least one functional test per anonymizer. To inspire you doing these tests, +read [existing tests in DbToolsBundle](https://github.com/makinacorpus/DbToolsBundle/tree/main/tests/Functional/Anonymizer/Core) or in official packs. -To help you launchning these tests, use provided `dev.sh` script, see [Development guide section](./guide) to learn how to use it. - +To help you launch these tests, use provided `dev.sh` script, see +[Development guide section](./guide) to learn how to use it. ## 5. Share your pack on packagist -If you want to share it and make it easily installable, share your package on [Packagist](https://packagist.org/). +If you want to share it and make it easily installable, share your package on +[Packagist](https://packagist.org/). ## 6. Make it an official pack @@ -146,12 +148,13 @@ If: * you find your package good enough, * it is well tested, -* you think it is generic enough to interest a large number of people, +* you think it is generic enough to interest a large number of people. Then, you should consider to add it to the official packs list. -Doing so, your package will be more visible (it will be added to this documentation) but it will also be automatically tested -by a CI every week from the [packs-status repository](https://github.com/DbToolsBundle/packs-status). +Doing so, your package will be more visible (it will be added to this +documentation) but it will also be automatically tested by a CI every week +from the [packs-status repository](https://github.com/DbToolsBundle/packs-status). This CI will: @@ -163,5 +166,6 @@ This CI will: To ask your package to be part of official list, [open an issue on the packs-status repository](https://github.com/DbToolsBundle/packs-status/issues). :::info -Note that to have your pack becoming an official one, you will need to transfere the repository to the [DbToolsBundle Organization](https://github.com/DbToolsBundle). +Note that to have your pack becoming an official one, you will need to transfer +the repository to the [DbToolsBundle Organization](https://github.com/DbToolsBundle). ::: diff --git a/docs/content/getting-started/installation.md b/docs/content/getting-started/installation.md index f650729..6ea6848 100644 --- a/docs/content/getting-started/installation.md +++ b/docs/content/getting-started/installation.md @@ -98,8 +98,8 @@ Feel free to read this configuration file, it will learn you basics about this b **That's it, *DbToolsBundle* is now ready to be used.** -But before starting to use it, check if it succeeds to find -backup and restore binaries for your(s) Doctrine connection(s): +But before starting to use it, check if it succeeds to find backup and +restoration binaries for your Doctrine connection(s):
diff --git a/docs/content/stats.md b/docs/content/stats.md index c9596a8..df62e30 100644 --- a/docs/content/stats.md +++ b/docs/content/stats.md @@ -8,8 +8,8 @@ All statistics values are tagged using one of the following tags: - `info`: display global information, - `read`: read statistics, - `write`: write statistics, - - `maint`: maintainance statistics, such as PostgreSQL VACUUM, - - `code`: occasionaly display SQL code, such as CREATE statements. + - `maint`: maintenance statistics, such as PostgreSQL VACUUM, + - `code`: occasionally display SQL code, such as CREATE statements. Per default, all commands will display values using the `info` and `read` tags. @@ -58,7 +58,7 @@ The `vendor/bin/db-tools stats table` $data) { list($callback, $description, $aliases) = $data; @@ -233,7 +233,7 @@ public static function bootstrap(array $config = [], array $configFiles = [], ?L $databaseSessionRegistry = self::createDatabaseSessionRegistry($configRegistry); - $anonymizerRegistry = self::createAnonymizeRegistry($config); + $anonymizerRegistry = self::createAnonymizerRegistry($config); $anonymizatorFactory = new AnonymizatorFactory($databaseSessionRegistry, $anonymizerRegistry, $logger); foreach (($config['anonymization_files'] ?? []) as $connectionName => $file) { @@ -472,7 +472,7 @@ private static function getEnv(string $name): string|null /** * Create anonymizer registry and register custom code and additional packs. */ - private static function createAnonymizeRegistry(array $config): AnonymizerRegistry + private static function createAnonymizerRegistry(array $config): AnonymizerRegistry { return new AnonymizerRegistry($config['anonymizer_paths']); } diff --git a/src/Bridge/Symfony/DependencyInjection/DbToolsConfiguration.php b/src/Bridge/Symfony/DependencyInjection/DbToolsConfiguration.php index 901ee48..c67ed07 100644 --- a/src/Bridge/Symfony/DependencyInjection/DbToolsConfiguration.php +++ b/src/Bridge/Symfony/DependencyInjection/DbToolsConfiguration.php @@ -18,17 +18,12 @@ public function __construct( /** * Append values in configuration we cannot set a default. * - * For example, 'anonymizer_paths', if set by the user, will loose the - * default anonymizer paths, and we need them to be set in all cases. - * * So we act after configuration has been processed and restore missing * values from here. This also allows the standalone configuration doing - * it outside of Symfony extension context. + * it outside the Symfony extension context. */ public static function appendPostConfig(array $config): array { - $config['anonymizer_paths'][] = \realpath(\dirname(__DIR__, 3)) . '/Anonymization/Anonymizer'; - return $config; } @@ -137,11 +132,11 @@ public function getConfigTreeBuilder(): TreeBuilder $rootNode ->children() ->scalarNode('workdir') - ->info('Directory path all other files will be relative to, if none providen then the configuration file directory will be used instead.') + ->info('Directory path all other files will be relative to, if none provided then the configuration file directory will be used instead.') ->defaultNull() ->end() ->scalarNode('default_connection') - ->info('Default connection name. If none providen, first one is used instead.') + ->info('Default connection name. If none provided, first one is used instead.') ->defaultNull() ->end() ->end() diff --git a/src/Bridge/Symfony/DependencyInjection/DbToolsExtension.php b/src/Bridge/Symfony/DependencyInjection/DbToolsExtension.php index 741c860..d978d5e 100644 --- a/src/Bridge/Symfony/DependencyInjection/DbToolsExtension.php +++ b/src/Bridge/Symfony/DependencyInjection/DbToolsExtension.php @@ -78,7 +78,7 @@ public function load(array $configs, ContainerBuilder $container): void } } // Only set the default provided one if the folder exists in order to - // prevent "directory does not exists" errors. + // prevent "directory does not exist" errors. $defaultDirectory = $container->getParameterBag()->resolveValue('%kernel.project_dir%/src/Anonymizer'); if (\is_dir($defaultDirectory)) { $anonymizerPaths[] = '%kernel.project_dir%/src/Anonymizer'; @@ -88,20 +88,20 @@ public function load(array $configs, ContainerBuilder $container): void // Register filename strategies. $strategies = []; - foreach (($config['storage']['filename_strategy'] ?? []) as $connectioName => $strategyId) { + foreach (($config['storage']['filename_strategy'] ?? []) as $connectionName => $strategyId) { // Default is handled directly by the storage service. if ($strategyId !== null && $strategyId !== 'default' && $strategyId !== 'datetime') { if ($container->hasDefinition($strategyId)) { - $strategies[$connectioName] = new Reference($strategyId); + $strategies[$connectionName] = new Reference($strategyId); } elseif (\class_exists($strategyId)) { if (!\is_subclass_of($strategyId, FilenameStrategyInterface::class)) { - throw new InvalidArgumentException(\sprintf('"db_tools.connections.%s.filename_strategy": class "%s" does not implement "%s"', $connectioName, $strategyId, FilenameStrategyInterface::class)); + throw new InvalidArgumentException(\sprintf('"db_tools.connections.%s.filename_strategy": class "%s" does not implement "%s"', $connectionName, $strategyId, FilenameStrategyInterface::class)); } $serviceId = '.db_tools.filename_strategy.' . \sha1($strategyId); $container->setDefinition($serviceId, (new Definition())->setClass($strategyId)); - $strategies[$connectioName] = new Reference($serviceId); + $strategies[$connectionName] = new Reference($serviceId); } else { - throw new InvalidArgumentException(\sprintf('"db_tools.connections.%s.filename_strategy": class or service "%s" does not exist or is not registered in container', $connectioName, $strategyId)); + throw new InvalidArgumentException(\sprintf('"db_tools.connections.%s.filename_strategy": class or service "%s" does not exist or is not registered in container', $connectionName, $strategyId)); } break; } diff --git a/src/Bridge/Symfony/Resources/config/services.yaml b/src/Bridge/Symfony/Resources/config/services.yaml index 10e6c39..ecad5cc 100644 --- a/src/Bridge/Symfony/Resources/config/services.yaml +++ b/src/Bridge/Symfony/Resources/config/services.yaml @@ -1,5 +1,5 @@ parameters: - # All allowed environement variables. + # All allowed environment variables. # When conflicting with options in the Symfony configuration, the Symfony # configuration will override the environment variables. env(DBTOOLS_BACKUP_BINARY): ~