#196 - Prefix the upload_directory parameter and the Twig functions and filter, deprecate the former names

CHANGELOG.md

@@ -2,6 +2,7 @@ Latest
 ------
 
 ## Changes
+* [#196](https://github.com/cleverage/ui-process-bundle/issues/196) Prefix the global names of the bundle, as required by the Symfony best practices for bundles: new `cleverage_ui_process.upload_directory` parameter, the `upload_directory` parameter is deprecated (when the application still sets it, its value is used with a deprecation, unless the new parameter is also set; new internal `UploadDirectoryParameterPass`); the Twig functions `log_label`, `log_translation`, `log_css_class`, `get_last_execution_date`, `get_process_source`, `get_process_target`, `resolve_ui_options` and the Twig filter `md5` are prefixed with `cleverage_ui_process_`, the former names are deprecated. The former names will be removed in 4.0. Update documentation and UPGRADE.md, add tests.
 * [#194](https://github.com/cleverage/ui-process-bundle/issues/194) The tables and columns of the entities have explicit names, those created by the migrations of the bundle: the schema no longer depends on the Doctrine naming strategy of the application (the `underscore_number_aware` strategy is no longer a prerequisite; with the Doctrine default one, the indexes referenced missing columns). Same names with the `underscore` / `underscore_number_aware` strategies, no new migration. Update documentation, add tests.
 * [#190](https://github.com/cleverage/ui-process-bundle/issues/190) Add aliases named after their class to `ProcessExecutionManager`, `ProcessConfigurationsManager`, `ProcessExecutionRepository` and `ProcessScheduleRepository` (as the Monolog handlers): they can be autowired. Update documentation, add tests.
 * [#192](https://github.com/cleverage/ui-process-bundle/issues/192) The controllers and the HTTP value resolver are defined explicitly, without autowiring nor autoconfiguration (Symfony best practices for bundles, as [cleverage/process-bundle#149](https://github.com/cleverage/process-bundle/issues/149)): same arguments, tags and calls. The `$context` binding of the controllers no longer registers the `AdminContextFactory` service for the `AdminContext $context` arguments of the EasyAdmin actions (never used: EasyAdmin resolves the context first). Add tests.

UPGRADE.md

@@ -22,6 +22,37 @@ The routes of the bundle are prefixed with `cleverage_ui_process_`. The former n
 The routes of the CRUD pages are generated by EasyAdmin from the dashboard route name, e.g.
 `process_process_execution_index` is now `cleverage_ui_process_process_execution_index`.
 
+### Upload directory parameter
+
+The `upload_directory` container parameter is deprecated, use `cleverage_ui_process.upload_directory`: it will be
+removed in 4.0. Setting `upload_directory` in your application still works (with a deprecation), unless
+`cleverage_ui_process.upload_directory` is also set.
+
+```yaml
+# config/services.yaml
+parameters:
+    # Before (deprecated)
+    upload_directory: '%kernel.project_dir%/var/imports'
+    # After
+    cleverage_ui_process.upload_directory: '%kernel.project_dir%/var/imports'
+```
+
+### Twig functions and filter
+
+The Twig functions and filter of the bundle are prefixed with `cleverage_ui_process_`. The former names are deprecated,
+removed in 4.0: update your templates (e.g. overridden templates of the bundle).
+
+| Before (deprecated)              | After                                                 |
+|----------------------------------|-------------------------------------------------------|
+| `log_label()`                    | `cleverage_ui_process_log_label()`                    |
+| `log_translation()`              | `cleverage_ui_process_log_translation()`              |
+| `log_css_class()`                | `cleverage_ui_process_log_css_class()`                |
+| `get_last_execution_date()`      | `cleverage_ui_process_get_last_execution_date()`      |
+| `get_process_source()`           | `cleverage_ui_process_get_process_source()`           |
+| `get_process_target()`           | `cleverage_ui_process_get_process_target()`           |
+| `resolve_ui_options()`           | `cleverage_ui_process_resolve_ui_options()`           |
+| `md5` (filter)                   | `cleverage_ui_process_md5` (filter)                   |
+
 ## v3.0
 
 ### Import routes

config/services/controller.yaml

@@ -23,7 +23,7 @@ services:
             $adminContextProvider: '@EasyCorp\Bundle\EasyAdminBundle\Provider\AdminContextProvider'
         bind:
             # Argument of the action
-            $uploadDirectory: '%upload_directory%'
+            $uploadDirectory: '%cleverage_ui_process.upload_directory%'
         calls:
             - [setContainer, ['@Psr\Container\ContainerInterface']]
         tags:

config/services/http_value_resolver.yaml

@@ -3,7 +3,7 @@ services:
         class: CleverAge\UiProcessBundle\Http\ValueResolver\HttpProcessExecuteValueResolver
         public: false
         arguments:
-            - '%upload_directory%'
+            - '%cleverage_ui_process.upload_directory%'
             - '@serializer'
         tags:
             # Targeted value resolver: #[ValueResolver('http_process_execution')], as #[AsTargetedValueResolver]

config/services/parameters.yaml

@@ -1,2 +1,4 @@
 parameters:
-  upload_directory: '%kernel.project_dir%/var/storage/uploads'
+  cleverage_ui_process.upload_directory: '%kernel.project_dir%/var/storage/uploads'
+  # Deprecated since 3.3, removed in 4.0 (see UploadDirectoryParameterPass)
+  upload_directory: '%cleverage_ui_process.upload_directory%'

docs/cookbooks/form_file_upload.md

@@ -63,7 +63,7 @@ How it works:
 - `ui_launch_mode: form` makes the "Launch" action of the process list open a form instead of a confirmation modal
   (see [launch modes](../reference/02-process_ui_options.md#launch-modes)).
 - `entrypoint_type: file` turns the `input` field into a file upload. As the process has an `entry_point`, the field
-  is required. The uploaded file is saved in the `upload_directory` directory and its path is sent to the
+  is required. The uploaded file is saved in the `cleverage_ui_process.upload_directory` directory and its path is sent to the
   `log_file` task (see [launch form](../reference/02-process_ui_options.md#launch-form)).
 - `default.context` pre-fills a `delimiter` line in the context collection
   (see [default values](../reference/02-process_ui_options.md#default-values)). It is injected into the
@@ -80,7 +80,7 @@ How it works:
   (see [process executions & logs](../reference/04-process_executions_and_logs.md)).
 
 Uploaded files are not removed after the execution: add a cleaning step at the end of the process (e.g. a
-[FileRemoverTask](https://github.com/cleverage/process-bundle/blob/main/docs/reference/tasks/file_remover_task.md)) or purge the `upload_directory` directory periodically.
+[FileRemoverTask](https://github.com/cleverage/process-bundle/blob/main/docs/reference/tasks/file_remover_task.md)) or purge the `cleverage_ui_process.upload_directory` directory periodically.
 
 The same process can also be launched through the [HTTP API](../reference/06-http_api.md), with a file upload:
 

docs/reference/01-bundle_configuration.md

@@ -94,16 +94,17 @@ See [stopping a process execution](04-process_executions_and_logs.md#stopping-a-
 Container parameters
 --------------------
 
-| Parameter          | Default                                        | Description                                                                                                                       |
-|--------------------|------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
-| `upload_directory` | `%kernel.project_dir%/var/storage/uploads`     | Directory where files uploaded from the launch form or the [HTTP API](06-http_api.md) are stored before being passed as process input. |
+| Parameter                               | Default                                   | Description |
+|-----------------------------------------|-------------------------------------------|-------------|
+| `cleverage_ui_process.upload_directory` | `%kernel.project_dir%/var/storage/uploads` | Directory where files uploaded from the launch form or the [HTTP API](06-http_api.md) are stored before being passed as process input. |
+| `upload_directory`                      | `%cleverage_ui_process.upload_directory%` | Deprecated since 3.3, removed in 4.0: use `cleverage_ui_process.upload_directory`. When your application still sets it, its value is used (unless `cleverage_ui_process.upload_directory` is also set), with a deprecation. |
 
 It can be overridden in your application:
 
 ```yaml
 # config/services.yaml
 parameters:
-    upload_directory: '%kernel.project_dir%/var/imports'
+    cleverage_ui_process.upload_directory: '%kernel.project_dir%/var/imports'
 ```
 
 Configuration added to other bundles

docs/reference/02-process_ui_options.md

@@ -79,7 +79,7 @@ The launch form (`/process/launch?process=<process_code>`) contains:
 - a `context` collection of key/value pairs (both are required when a line is added). Each pair becomes a process
   context value, like `-c key:value` on the `cleverage:process:execute` console command.
 
-When `entrypoint_type` is `file`, the uploaded file is saved to the `upload_directory` directory (see
+When `entrypoint_type` is `file`, the uploaded file is saved to the `cleverage_ui_process.upload_directory` directory (see
 [bundle configuration](01-bundle_configuration.md#container-parameters)) with a random name keeping the original
 extension, and its absolute path is passed as process input. The file is not removed after the execution.
 

docs/reference/06-http_api.md

@@ -31,7 +31,7 @@ Parameters can be sent either as a JSON body, or as form data (`application/x-ww
 | Parameter | Type                      | Required | Default | Description                                                                                                                                                           |
 |-----------|---------------------------|:--------:|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `code`    | `string`                  |    **X** |         | Code of the process. It must exist and be public.                                                                                                                    |
-| `input`   | `string` or file          |          | `null`  | Process input. With form data, it can be an uploaded file: the file is saved in the `upload_directory` directory (see [bundle configuration](01-bundle_configuration.md#container-parameters)) and its path is passed as input. |
+| `input`   | `string` or file          |          | `null`  | Process input. With form data, it can be an uploaded file: the file is saved in the `cleverage_ui_process.upload_directory` directory (see [bundle configuration](01-bundle_configuration.md#container-parameters)) and its path is passed as input. |
 | `context` | `object` or JSON `string` |          | `{}`    | Process context, as key/value pairs. A JSON string must decode to an object or an array (`422` otherwise). With form data, send one field per value: `context[key]=value`. |
 | `queue`   | `bool`                    |          | `true`  | `true`: the process is queued to the `execute_process` transport (see [messenger](08-messenger.md)). `false`: the process is executed during the HTTP request.      |
 

src/CleverAgeUiProcessBundle.php

@@ -14,6 +14,7 @@
 namespace CleverAge\UiProcessBundle;
 
 use CleverAge\UiProcessBundle\DependencyInjection\Compiler\CheckDoctrineLazyGhostObjectsPass;
+use CleverAge\UiProcessBundle\DependencyInjection\Compiler\UploadDirectoryParameterPass;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\HttpKernel\Bundle\Bundle;
 
@@ -34,5 +35,6 @@ public function build(ContainerBuilder $container): void
         parent::build($container);
 
         $container->addCompilerPass(new CheckDoctrineLazyGhostObjectsPass());
+        $container->addCompilerPass(new UploadDirectoryParameterPass());
     }
 }

src/DependencyInjection/Compiler/UploadDirectoryParameterPass.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the CleverAge/UiProcessBundle package.
+ *
+ * Copyright (c) Clever-Age
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace CleverAge\UiProcessBundle\DependencyInjection\Compiler;
+
+use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+
+/**
+ * The "upload_directory" parameter is deprecated since 3.3 for "cleverage_ui_process.upload_directory": when the
+ * application still overrides it, its value is used (unless the new parameter is also set), with a deprecation.
+ * Reading it is deprecated too.
+ *
+ * @internal
+ */
+final readonly class UploadDirectoryParameterPass implements CompilerPassInterface
+{
+    public const PARAMETER = 'cleverage_ui_process.upload_directory';
+    public const DEPRECATED_PARAMETER = 'upload_directory';
+    /** Default values, see config/services/parameters.yaml */
+    public const DEFAULT_VALUE = '%kernel.project_dir%/var/storage/uploads';
+    public const DEPRECATED_DEFAULT_VALUE = '%'.self::PARAMETER.'%';
+
+    public function process(ContainerBuilder $container): void
+    {
+        // Raw values: reading a deprecated parameter triggers its deprecation
+        $parameters = $container->getParameterBag()->all();
+        if (!\array_key_exists(self::DEPRECATED_PARAMETER, $parameters)) {
+            return;
+        }
+
+        $value = $parameters[self::DEPRECATED_PARAMETER];
+        if (self::DEPRECATED_DEFAULT_VALUE !== $value) {
+            trigger_deprecation('cleverage/ui-process-bundle', '3.3', 'Setting the "%s" parameter is deprecated, set "%s" instead. It will be ignored in 4.0.', self::DEPRECATED_PARAMETER, self::PARAMETER);
+            if (\is_string($value) && self::DEFAULT_VALUE === ($parameters[self::PARAMETER] ?? null)) {
+                $container->setParameter(self::PARAMETER, $value);
+            }
+        }
+
+        $container->deprecateParameter(self::DEPRECATED_PARAMETER, 'cleverage/ui-process-bundle', '3.3', 'The "%s" parameter is deprecated, use "'.self::PARAMETER.'" instead. It will be removed in 4.0.');
+    }
+}

src/Twig/Extension/LogLevelExtension.php

@@ -14,6 +14,7 @@
 namespace CleverAge\UiProcessBundle\Twig\Extension;
 
 use CleverAge\UiProcessBundle\Twig\Runtime\LogLevelExtensionRuntime;
+use Twig\DeprecatedCallableInfo;
 use Twig\Extension\AbstractExtension;
 use Twig\TwigFunction;
 
@@ -26,9 +27,13 @@ class LogLevelExtension extends AbstractExtension
     public function getFunctions(): array
     {
         return [
-            new TwigFunction('log_label', [LogLevelExtensionRuntime::class, 'getLabel']),
-            new TwigFunction('log_translation', [LogLevelExtensionRuntime::class, 'getTranslation']),
-            new TwigFunction('log_css_class', [LogLevelExtensionRuntime::class, 'getCssClass']),
+            new TwigFunction('cleverage_ui_process_log_label', [LogLevelExtensionRuntime::class, 'getLabel']),
+            new TwigFunction('cleverage_ui_process_log_translation', [LogLevelExtensionRuntime::class, 'getTranslation']),
+            new TwigFunction('cleverage_ui_process_log_css_class', [LogLevelExtensionRuntime::class, 'getCssClass']),
+            // Former names, removed in 4.0
+            new TwigFunction('log_label', [LogLevelExtensionRuntime::class, 'getLabel'], ['deprecation_info' => new DeprecatedCallableInfo('cleverage/ui-process-bundle', '3.3', 'cleverage_ui_process_log_label')]),
+            new TwigFunction('log_translation', [LogLevelExtensionRuntime::class, 'getTranslation'], ['deprecation_info' => new DeprecatedCallableInfo('cleverage/ui-process-bundle', '3.3', 'cleverage_ui_process_log_translation')]),
+            new TwigFunction('log_css_class', [LogLevelExtensionRuntime::class, 'getCssClass'], ['deprecation_info' => new DeprecatedCallableInfo('cleverage/ui-process-bundle', '3.3', 'cleverage_ui_process_log_css_class')]),
         ];
     }
 }

src/Twig/Extension/MD5Extension.php

@@ -14,6 +14,7 @@
 namespace CleverAge\UiProcessBundle\Twig\Extension;
 
 use CleverAge\UiProcessBundle\Twig\Runtime\MD5ExtensionRuntime;
+use Twig\DeprecatedCallableInfo;
 use Twig\Extension\AbstractExtension;
 use Twig\TwigFilter;
 
@@ -26,7 +27,9 @@ class MD5Extension extends AbstractExtension
     public function getFilters(): array
     {
         return [
-            new TwigFilter('md5', [MD5ExtensionRuntime::class, 'md5']),
+            new TwigFilter('cleverage_ui_process_md5', [MD5ExtensionRuntime::class, 'md5']),
+            // Former names, removed in 4.0
+            new TwigFilter('md5', [MD5ExtensionRuntime::class, 'md5'], ['deprecation_info' => new DeprecatedCallableInfo('cleverage/ui-process-bundle', '3.3', 'cleverage_ui_process_md5')]),
         ];
     }
 }

src/Twig/Extension/ProcessExecutionExtension.php

@@ -14,6 +14,7 @@
 namespace CleverAge\UiProcessBundle\Twig\Extension;
 
 use CleverAge\UiProcessBundle\Twig\Runtime\ProcessExecutionExtensionRuntime;
+use Twig\DeprecatedCallableInfo;
 use Twig\Extension\AbstractExtension;
 use Twig\TwigFunction;
 
@@ -26,18 +27,13 @@ class ProcessExecutionExtension extends AbstractExtension
     public function getFunctions(): array
     {
         return [
-            new TwigFunction(
-                'get_last_execution_date',
-                [ProcessExecutionExtensionRuntime::class, 'getLastExecutionDate']
-            ),
-            new TwigFunction(
-                'get_process_source',
-                [ProcessExecutionExtensionRuntime::class, 'getProcessSource']
-            ),
-            new TwigFunction(
-                'get_process_target',
-                [ProcessExecutionExtensionRuntime::class, 'getProcessTarget']
-            ),
+            new TwigFunction('cleverage_ui_process_get_last_execution_date', [ProcessExecutionExtensionRuntime::class, 'getLastExecutionDate']),
+            new TwigFunction('cleverage_ui_process_get_process_source', [ProcessExecutionExtensionRuntime::class, 'getProcessSource']),
+            new TwigFunction('cleverage_ui_process_get_process_target', [ProcessExecutionExtensionRuntime::class, 'getProcessTarget']),
+            // Former names, removed in 4.0
+            new TwigFunction('get_last_execution_date', [ProcessExecutionExtensionRuntime::class, 'getLastExecutionDate'], ['deprecation_info' => new DeprecatedCallableInfo('cleverage/ui-process-bundle', '3.3', 'cleverage_ui_process_get_last_execution_date')]),
+            new TwigFunction('get_process_source', [ProcessExecutionExtensionRuntime::class, 'getProcessSource'], ['deprecation_info' => new DeprecatedCallableInfo('cleverage/ui-process-bundle', '3.3', 'cleverage_ui_process_get_process_source')]),
+            new TwigFunction('get_process_target', [ProcessExecutionExtensionRuntime::class, 'getProcessTarget'], ['deprecation_info' => new DeprecatedCallableInfo('cleverage/ui-process-bundle', '3.3', 'cleverage_ui_process_get_process_target')]),
         ];
     }
 }

src/Twig/Extension/ProcessExtension.php

@@ -14,6 +14,7 @@
 namespace CleverAge\UiProcessBundle\Twig\Extension;
 
 use CleverAge\UiProcessBundle\Twig\Runtime\ProcessExtensionRuntime;
+use Twig\DeprecatedCallableInfo;
 use Twig\Extension\AbstractExtension;
 use Twig\TwigFunction;
 
@@ -26,10 +27,9 @@ class ProcessExtension extends AbstractExtension
     public function getFunctions(): array
     {
         return [
-            new TwigFunction(
-                'resolve_ui_options',
-                [ProcessExtensionRuntime::class, 'getUiOptions']
-            ),
+            new TwigFunction('cleverage_ui_process_resolve_ui_options', [ProcessExtensionRuntime::class, 'getUiOptions']),
+            // Former names, removed in 4.0
+            new TwigFunction('resolve_ui_options', [ProcessExtensionRuntime::class, 'getUiOptions'], ['deprecation_info' => new DeprecatedCallableInfo('cleverage/ui-process-bundle', '3.3', 'cleverage_ui_process_resolve_ui_options')]),
         ];
     }
 }

templates/admin/field/log_level.html.twig

@@ -1 +1 @@
-<span class="badge badge-{{ log_css_class(field.value) }}">{{ log_translation(log_label(field.value)) }}</span>
+<span class="badge badge-{{ cleverage_ui_process_log_css_class(field.value) }}">{{ cleverage_ui_process_log_translation(cleverage_ui_process_log_label(field.value)) }}</span>

templates/admin/field/process_source.html.twig

@@ -1 +1 @@
-{{ get_process_source(entity.instance.code) }}
+{{ cleverage_ui_process_get_process_source(entity.instance.code) }}