Add user interface to view executed jobs (#104)

* Add user interface to view executed jobs

* Allow symfony/css-selector ^5.0

* Fixed potentially non existing assert method

* Fixed missing array structure declaration in ConfigurableTemplating

* Fixed code style

* Fixed some details on bootstrap4 rendering

* Add screenshots of UI

* Allow to access child jobs on their own

* Pluralize job routing

* Add screenshot of warnings

* Fixed tests

* Screenshots gallery

* Screenshots gallery

* Move sonata screenshot gallery

* Added HTTP method requirements to routes

* Fixed typo in Yokai

* Fixed breadcrumb building errors

* Fixed wrong implementation of TemplatingInterface in documentation

* Apply doc typo suggestions from code review

Co-authored-by: Benoit Jouhaud <[email protected]>

* Add test for not finding child job

* Inline NotFoundHttpException

* Fixed response statuses priorities

---------

Co-authored-by: Yann Eugoné <[email protected]>
Co-authored-by: Benoit Jouhaud <[email protected]>

Author: yann-eugone

README.md

@@ -25,6 +25,7 @@ composer require yokai/batch-symfony-framework
 This package provides:
 
 - [integration](docs/getting-started.md) with Symfony framework
+- a [UI](docs/ui.md) with Symfony framework
 
 
 ## Contribution

composer.json

@@ -25,8 +25,21 @@
         }
     },
     "require-dev": {
+        "sonata-project/admin-bundle": "^4.0",
+        "symfony/filesystem": "^5.0|^6.0",
+        "symfony/form": "^5.0|^6.0",
+        "symfony/security-bundle": "^5.0|^6.0",
+        "symfony/translation": "^5.0|^6.0",
+        "symfony/twig-bundle": "^5.0|^6.0",
         "phpunit/phpunit": "^9.5"
     },
+    "suggest": {
+        "sonata-project/admin-bundle": "If you want a SonataAdmin like rendering in the user interface",
+        "symfony/form": "If you want the JobExecution form filter in the user interface",
+        "symfony/security-bundle": "If you want to secure the access to JobExecution in the user interface",
+        "symfony/translation": "Required if you want to enable the user interface",
+        "symfony/twig-bundle": "Required if you want to enable the user interface"
+    },
     "autoload-dev": {
         "psr-4": {
             "Yokai\\Batch\\Tests\\Bridge\\Symfony\\Framework\\": "tests/"

docs/images/bootstrap4-children.png

@@ -0,0 +1,196 @@
+# User Interface
+
+The package is shipped with few routes that will allow you and your users, to watch for `JobExecution`.
+
+<img src="images/bootstrap4-list.png" alt="Bootstrap 4 - List action" width="23%"> <img src="images/bootstrap4-details.png" alt="Bootstrap 4 - Detail : Information" width="23%"> <img src="images/bootstrap4-children.png" alt="Bootstrap 4 - Detail : Children" width="23%"> <img src="images/bootstrap4-warnings.png" alt="Bootstrap 4 - Detail : Warnings" width="23%">
+
+
+## Installation
+
+For the UI to be enabled, it is required that you install some dependencies:
+```shell
+composer require symfony/translation symfony/twig-bundle
+```
+
+
+## Configuration
+
+The UI is disabled by default, you must enable it explicitely:
+```yaml
+# config/packages/yokai_batch.yaml
+yokai_batch:
+  ui:
+    enabled: true
+```
+
+You will also need to import bundle routes:
+```yaml
+# config/routes/yokai_batch.yaml
+_yokai_batch:
+  resource: "@YokaiBatchBundle/Resources/routing/ui.xml"
+```
+
+### Templating
+
+The templating service is used by the [JobController](../src/UserInterface/Controller/JobController.php) to render its templates.
+It's a wrapper around [Twig](https://twig.symfony.com/), for you to control templates used, and variables passed.
+
+> By default
+> - the templating will find templates like `@YokaiBatch/bootstrap4/*.html.twig`
+> - the template base view will be `base.html.twig`
+
+You can configure a prefix for all templates:
+```yaml
+# config/packages/yokai_batch.yaml
+yokai_batch:
+  ui:
+    templating:
+      prefix: 'batch/job/'
+```
+> With this configuration, we will look for templates like `batch/job/*.html.twig`.
+
+You can also configure the name of the base template for the root views of that bundle:
+```yaml
+# config/packages/yokai_batch.yaml
+yokai_batch:
+  ui:
+    templating:
+      base_template: 'layout.html.twig'
+```
+> With this configuration, the template base view will be `layout.html.twig`.
+
+If these are not enough, or if you need to add more variables to context, you can configure a service:
+```yaml
+# config/packages/yokai_batch.yaml
+yokai_batch:
+  ui:
+    templating:
+      service: 'App\Batch\AppTemplating'
+```
+
+And create the class that will cover the templating:
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Batch;
+
+use Yokai\Batch\Bridge\Symfony\Framework\UserInterface\Templating\TemplatingInterface;
+
+final class AppTemplating implements TemplatingInterface
+{
+    public function name(string $name): string
+    {
+        return "another-$name"; // change $name if you want
+    }
+
+    public function context(array $context): array;
+    {
+        return \array_merge($context, ['foo' => 'bar']); // add variables to $context if you want
+    }
+}
+```
+
+> **Note** You can also use the `Yokai\Batch\Bridge\Symfony\Framework\UserInterface\Templating\ConfigurableTemplating` that will cover both prefix and static variables at construction.
+
+
+### Filtering
+
+The `JobExecution` list includes a filter form, but you will need another optional dependency:
+```shell
+composer require symfony/form
+```
+
+### Security
+
+There is no access control over `JobExecution` by default, you will need another optional dependency:
+```shell
+composer require symfony/security-bundle
+```
+
+Every security attribute the bundle is using is configurable:
+```yaml
+# config/packages/yokai_batch.yaml
+yokai_batch:
+  ui:
+    security:
+      attributes:
+        list: ROLE_JOB_LIST # defaults to IS_AUTHENTICATED
+        view: ROLE_JOB_VIEW # defaults to IS_AUTHENTICATED
+        traces: ROLE_JOB_TRACES # defaults to IS_AUTHENTICATED
+        logs: ROLE_JOB_LOGS # defaults to IS_AUTHENTICATED
+```
+
+Optionally, you can register a voter for these attributes.
+This is especially useful if you need different access control rules per `JobExecution`.
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Security;
+
+use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
+use Symfony\Component\Security\Core\Authorization\Voter\Voter;
+use Yokai\Batch\JobExecution;
+
+final class JobVoter extends Voter
+{
+    protected function supports(string $attribute, mixed $subject): bool
+    {
+        return \str_starts_with($attribute, 'JOB_');
+    }
+
+    /**
+     * @param JobExecution|null $subject
+     */
+    protected function voteOnAttribute(string $attribute, mixed $subject, TokenInterface $token): bool
+    {
+        // TODO: Implement voteOnAttribute() method.
+    }
+}
+```
+
+
+## Integration with SonataAdminBundle
+
+If you are on a [SonataAdmin](https://symfony.com/bundles/SonataAdminBundle/current/index.html) project.
+The bundle got you covered with a dedicated templating services and templates.
+
+<img src="images/sonata-list.png" alt="Sonata - List action" width="23%"> <img src="images/sonata-details.png" alt="Sonata - Detail : Information" width="23%"> <img src="images/sonata-children.png" alt="Sonata - Detail : Children" width="23%"> <img src="images/sonata-warnings.png" alt="Sonata - Detail : Warnings" width="23%">
+
+```shell
+composer require sonata-project/admin-bundle
+```
+
+```yaml
+# config/packages/yokai_batch.yaml
+yokai_batch:
+  ui:
+    templating: sonata
+```
+> With this configuration, we will look for templates like `@YokaiBatch/sonata/*.html.twig`.
+
+
+## Customizing templates
+
+You can override templates like [described it Symfony's documentation](https://symfony.com/doc/current/bundles/override.html).
+Examples:
+- `templates/bundles/YokaiBatchBundle/bootstrap4/list.html.twig`
+- `templates/bundles/YokaiBatchBundle/bootstrap4/show/_parameters.html.twig`
+
+But you can also register job name dedicated templates if you need some specific view for one of your jobs:
+- `templates/bundles/YokaiBatchBundle/bootstrap4/show/{job name}/_children-executions.html.twig`
+- `templates/bundles/YokaiBatchBundle/bootstrap4/show/{job name}/_failures.html.twig`
+- `templates/bundles/YokaiBatchBundle/bootstrap4/show/{job name}/_general.html.twig`
+- `templates/bundles/YokaiBatchBundle/bootstrap4/show/{job name}/_information.html.twig`
+- `templates/bundles/YokaiBatchBundle/bootstrap4/show/{job name}/_parameters.html.twig`
+- `templates/bundles/YokaiBatchBundle/bootstrap4/show/{job name}/_summary.html.twig`
+- `templates/bundles/YokaiBatchBundle/bootstrap4/show/{job name}/_warnings.html.twig`
+
+## On the same subject
+
+- [What is a job execution storage ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/job-execution-storage.md)
+- [What is a job ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/job.md)
+- [What is a job launcher ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/job-launcher.md)

docs/images/bootstrap4-details.png

@@ -30,6 +30,11 @@ public function process(ContainerBuilder $container): void
 
         $container->getDefinition('yokai_batch.job_registry')
             ->setArgument('$jobs', ServiceLocatorTagPass::register($container, $jobs));
+
+        if ($container->hasDefinition('yokai_batch.ui.filter_form')) {
+            $container->getDefinition('yokai_batch.ui.filter_form')
+                ->setArgument('$jobs', \array_keys($jobs));
+        }
     }
 
     /**

docs/images/bootstrap4-list.png

@@ -10,6 +10,38 @@
 
 /**
  * Configuration for yokai/batch Symfony Bundle.
+ *
+ * @phpstan-type Config array{
+ *      storage: StorageConfig,
+ *      ui: UserInterfaceConfig,
+ *  }
+ * @phpstan-type StorageConfig array{
+ *      service?: string,
+ *      dbal?: array{
+ *          connection: string,
+ *          table: string,
+ *      },
+ *      filesystem: array{
+ *          serializer: string,
+ *          dir: string,
+ *      },
+ *  }
+ * @phpstan-type UserInterfaceConfig array{
+ *      enabled: bool,
+ *      security: array{
+ *          attributes: array{
+ *              list: string,
+ *              view: string,
+ *              traces: string,
+ *              logs: string,
+ *          },
+ *      },
+ *      templating: array{
+ *          prefix: string|null,
+ *          service: string|null,
+ *          base_template: string|null,
+ *      },
+ *  }
  */
 final class Configuration implements ConfigurationInterface
 {
@@ -21,6 +53,7 @@ public function getConfigTreeBuilder(): TreeBuilder
         $root
             ->children()
                 ->append($this->storage())
+                ->append($this->ui())
             ->end()
         ;
 
@@ -63,4 +96,74 @@ private function storage(): ArrayNodeDefinition
 
         return $node;
     }
+
+    private function ui(): ArrayNodeDefinition
+    {
+        /** @var ArrayNodeDefinition $node */
+        $node = (new TreeBuilder('ui'))->getRootNode();
+
+        $node
+            ->addDefaultsIfNotSet()
+            ->canBeEnabled()
+            ->children()
+                ->arrayNode('templating')
+                    ->addDefaultsIfNotSet()
+                    ->beforeNormalization()
+                        ->always(function (string|array $value) {
+                            if (is_string($value)) {
+                                $value = match ($value) {
+                                    'bootstrap4' => ['prefix' => '@YokaiBatch/bootstrap4', 'service' => null],
+                                    'sonata' => ['service' => 'yokai_batch.ui.sonata_templating', 'prefix' => null],
+                                    default => throw new \InvalidArgumentException(
+                                        \sprintf('Unknown templating shortcut "%s".', $value),
+                                    ),
+                                };
+                            }
+
+                            if (!isset($value['service']) && !isset($value['prefix'])) {
+                                throw new \InvalidArgumentException(
+                                    'You must either configure "service" or "prefix".',
+                                );
+                            } elseif (isset($value['service']) && isset($value['prefix'])) {
+                                throw new \InvalidArgumentException(
+                                    'You cannot configure "service" and "prefix" at the same time.',
+                                );
+                            }
+
+                            return $value;
+                        })
+                    ->end()
+                    ->children()
+                        ->scalarNode('service')->defaultNull()->end()
+                        ->scalarNode('prefix')->defaultValue('@YokaiBatch/bootstrap4')->end()
+                        ->scalarNode('base_template')->defaultValue('base.html.twig')->end()
+                    ->end()
+                ->end()
+                ->arrayNode('security')
+                    ->addDefaultsIfNotSet()
+                    ->children()
+                        ->arrayNode('attributes')
+                            ->addDefaultsIfNotSet()
+                            ->children()
+                                ->scalarNode('list')
+                                    ->defaultValue('IS_AUTHENTICATED')
+                                ->end()
+                                ->scalarNode('view')
+                                    ->defaultValue('IS_AUTHENTICATED')
+                                ->end()
+                                ->scalarNode('traces')
+                                    ->defaultValue('IS_AUTHENTICATED')
+                                ->end()
+                                ->scalarNode('logs')
+                                    ->defaultValue('IS_AUTHENTICATED')
+                                ->end()
+                            ->end()
+                        ->end()
+                    ->end()
+                ->end()
+            ->end()
+        ;
+
+        return $node;
+    }
 }