#180 - Mark the classes not meant to be extended @final and the infrastructure classes @internal

CHANGELOG.md

@@ -2,6 +2,7 @@ Latest
 ------
 
 ## Changes
+* [#180](https://github.com/cleverage/ui-process-bundle/issues/180) Define the public API (Symfony BC promise, as [cleverage/process-bundle#279](https://github.com/cleverage/process-bundle/issues/279)): `ProcessExecutionManager`, `ProcessExecutionRepository`, `ProcessScheduleRepository`, `ProcessExecuteMessage`, `ProcessExecutionNotification` and `CleverAgeUiProcessBundle` are marked `@final since 3.3`, they will be `final` in 4.0: extending them triggers a deprecation with the Symfony `DebugClassLoader`. The entities stay open (overriding them: [#37](https://github.com/cleverage/ui-process-bundle/issues/37)). The infrastructure classes are marked `@internal`: the extension, `Configuration`, the commands, the controllers, the EasyAdmin fields and filters, the form types, the Messenger handlers, the Monolog handlers, `HttpProcessExecuteValueResolver`, `HttpProcessExecutionAuthenticator`, `ProcessExecutionStopChecker`, `CronScheduler`, `ProcessEventSubscriber` and the Twig extensions, runtimes and components.
 * [#179](https://github.com/cleverage/ui-process-bundle/issues/179) `CleverAgeUiProcessExtension::findServices()` loads the service definition files with a glob pattern instead of a `Finder` (same files, as [cleverage/process-bundle#271](https://github.com/cleverage/process-bundle/issues/271)). Add tests.
 * [#172](https://github.com/cleverage/ui-process-bundle/issues/172) Prefix the route names of the bundle with `cleverage_ui_process_`, as required by the Symfony best practices for bundles: `cleverage_ui_process_login`, `cleverage_ui_process_logout`, `cleverage_ui_process_list`, `cleverage_ui_process_launch`, `cleverage_ui_process_http_execute`, and the dashboard `cleverage_ui_process`, so that the routes generated by EasyAdmin for the CRUD pages are `cleverage_ui_process_<crud>_<action>`. The former names (`process`, `process_<crud>_<action>`, `process_login`, `process_logout`, `process_list`, `process_launch`, `http_process_execute`) are deprecated route aliases (new `config/routes/deprecated_aliases.yaml`, loaded by the documented import, and internal `DeprecatedEasyAdminRouteAliasLoader` for the routes generated by EasyAdmin), removed in 4.0; `?routeName=<former name>` URLs keep working. Document that `easyadmin.routes` generates the routes of every dashboard. Update documentation and UPGRADE.md, add tests.
 * [#166](https://github.com/cleverage/ui-process-bundle/issues/166) Doctrine ORM 2: the entities have readonly properties (since v3.2), which the legacy proxies of ORM 2 cannot handle (`Cannot unset readonly property ... from scope Proxies\__CG__\...` when an entity proxy is loaded). The container compilation now fails with an explicit message when ORM 2 is used without `doctrine.orm.enable_lazy_ghost_objects: true` (new internal `CheckDoctrineLazyGhostObjectsPass`); nothing changes with ORM 3. Update documentation, add tests.

src/Admin/Field/ContextField.php

@@ -17,6 +17,9 @@
 use EasyCorp\Bundle\EasyAdminBundle\Field\FieldTrait;
 use Symfony\Contracts\Translation\TranslatableInterface;
 
+/**
+ * @internal
+ */
 class ContextField implements FieldInterface
 {
     use FieldTrait;

src/Admin/Field/EnumField.php

@@ -17,6 +17,9 @@
 use EasyCorp\Bundle\EasyAdminBundle\Field\FieldTrait;
 use Symfony\Contracts\Translation\TranslatableInterface;
 
+/**
+ * @internal
+ */
 class EnumField implements FieldInterface
 {
     use FieldTrait;

src/Admin/Field/LogLevelField.php

@@ -17,6 +17,9 @@
 use EasyCorp\Bundle\EasyAdminBundle\Field\FieldTrait;
 use Symfony\Contracts\Translation\TranslatableInterface;
 
+/**
+ * @internal
+ */
 class LogLevelField implements FieldInterface
 {
     use FieldTrait;

src/Admin/Filter/LogProcessFilter.php

@@ -23,6 +23,9 @@
 use EasyCorp\Bundle\EasyAdminBundle\Form\Type\ComparisonType;
 use Symfony\Contracts\Translation\TranslatableInterface;
 
+/**
+ * @internal
+ */
 class LogProcessFilter implements FilterInterface
 {
     use FilterTrait;

src/Admin/Filter/ProcessExecutionDurationFilter.php

@@ -21,6 +21,9 @@
 use EasyCorp\Bundle\EasyAdminBundle\Filter\FilterTrait;
 use EasyCorp\Bundle\EasyAdminBundle\Form\Filter\Type\NumericFilterType;
 
+/**
+ * @internal
+ */
 class ProcessExecutionDurationFilter implements FilterInterface
 {
     use FilterTrait;

src/CleverAgeUiProcessBundle.php

@@ -17,6 +17,9 @@
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\HttpKernel\Bundle\Bundle;
 
+/**
+ * @final since 3.3
+ */
 class CleverAgeUiProcessBundle extends Bundle
 {
     #[\Override]

src/Command/PurgeLogsCommand.php

@@ -33,6 +33,8 @@
  * "logs.file_max_days" days, both overridable by the "logs" option of each process. The process executions are kept.
  *
  * DBAL queries are used: the log records are deleted by batches, without loading them.
+ *
+ * @internal
  */
 #[AsCommand(
     name: 'cleverage:ui-process:purge-logs',

src/Command/UserCreateCommand.php

@@ -30,6 +30,9 @@
 use Symfony\Component\Validator\Constraints\NotBlank;
 use Symfony\Component\Validator\Validator\ValidatorInterface;
 
+/**
+ * @internal
+ */
 #[AsCommand(
     name: 'cleverage:ui-process:user-create',
     description: 'Command to create a new admin into database for ui process.'

src/Controller/Admin/LogRecordCrudController.php

@@ -34,6 +34,8 @@
 
 /**
  * @extends AbstractCrudController<LogRecord>
+ *
+ * @internal
  */
 #[IsGranted('ROLE_USER')]
 class LogRecordCrudController extends AbstractCrudController

src/Controller/Admin/Process/LaunchAction.php

@@ -32,6 +32,9 @@
 use Symfony\Component\Security\Http\Attribute\IsGranted;
 use Symfony\Component\Uid\Uuid;
 
+/**
+ * @internal
+ */
 #[Route(
     '/process/launch',
     name: 'cleverage_ui_process_launch',

src/Controller/Admin/Process/ListAction.php

@@ -22,6 +22,9 @@
 use Symfony\Component\Routing\Attribute\Route;
 use Symfony\Component\Security\Http\Attribute\IsGranted;
 
+/**
+ * @internal
+ */
 #[Route('/process/list', name: 'cleverage_ui_process_list')]
 #[IsGranted('ROLE_USER')]
 class ListAction extends AbstractController

src/Controller/Admin/ProcessDashboardController.php

@@ -25,6 +25,9 @@
 use Symfony\Component\Security\Http\Attribute\IsGranted;
 use Symfony\Component\Translation\LocaleSwitcher;
 
+/**
+ * @internal
+ */
 #[IsGranted('ROLE_USER')]
 #[AdminDashboard(routePath: '/process', routeName: 'cleverage_ui_process')]
 class ProcessDashboardController extends AbstractDashboardController

src/Controller/Admin/ProcessExecutionCrudController.php

@@ -38,6 +38,8 @@
 
 /**
  * @extends AbstractCrudController<ProcessExecution>
+ *
+ * @internal
  */
 #[IsGranted('ROLE_USER')]
 class ProcessExecutionCrudController extends AbstractCrudController

src/Controller/Admin/ProcessScheduleCrudController.php

@@ -40,6 +40,8 @@
 
 /**
  * @extends AbstractCrudController<ProcessSchedule>
+ *
+ * @internal
  */
 #[IsGranted('ROLE_USER')]
 class ProcessScheduleCrudController extends AbstractCrudController

src/Controller/Admin/Security/LoginController.php

@@ -18,6 +18,9 @@
 use Symfony\Component\Routing\Attribute\Route;
 use Symfony\Component\Security\Http\Authentication\AuthenticationUtils;
 
+/**
+ * @internal
+ */
 class LoginController extends AbstractController
 {
     #[Route('/process/login', name: 'cleverage_ui_process_login')]

src/Controller/Admin/Security/LogoutController.php

@@ -18,6 +18,9 @@
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\Routing\Attribute\Route;
 
+/**
+ * @internal
+ */
 class LogoutController extends AbstractController
 {
     public function __construct(private readonly Security $security)

src/Controller/Admin/UserCrudController.php

@@ -36,6 +36,8 @@
 
 /**
  * @extends AbstractCrudController<User>
+ *
+ * @internal
  */
 #[IsGranted('ROLE_USER')]
 class UserCrudController extends AbstractCrudController

src/Controller/ProcessExecuteController.php

@@ -28,6 +28,9 @@
 use Symfony\Component\Security\Http\Attribute\IsGranted;
 use Symfony\Component\Validator\Validator\ValidatorInterface;
 
+/**
+ * @internal
+ */
 #[IsGranted('ROLE_USER')]
 #[Route(path: '/http/process/execute', name: 'cleverage_ui_process_http_execute', methods: ['POST'])]
 class ProcessExecuteController extends AbstractController

src/DependencyInjection/CleverAgeUiProcessExtension.php

@@ -28,6 +28,9 @@
 use Symfony\Component\DependencyInjection\Loader\YamlFileLoader;
 use Symfony\Component\Notifier\NotifierInterface;
 
+/**
+ * @internal
+ */
 final class CleverAgeUiProcessExtension extends Extension implements PrependExtensionInterface
 {
     public function load(array $configs, ContainerBuilder $container): void

src/DependencyInjection/Configuration.php

@@ -19,6 +19,9 @@
 use Symfony\Component\Config\Definition\Builder\TreeBuilder;
 use Symfony\Component\Config\Definition\ConfigurationInterface;
 
+/**
+ * @internal
+ */
 class Configuration implements ConfigurationInterface
 {
     public function __construct(private readonly string $env)

src/EventSubscriber/ProcessEventSubscriber.php

@@ -25,6 +25,9 @@
 use Symfony\Component\Uid\Uuid;
 use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
 
+/**
+ * @internal
+ */
 final readonly class ProcessEventSubscriber implements EventSubscriberInterface
 {
     public function __construct(

src/Form/Type/LaunchType.php

@@ -25,6 +25,9 @@
 use Symfony\Component\Form\FormBuilderInterface;
 use Symfony\Component\OptionsResolver\OptionsResolver;
 
+/**
+ * @internal
+ */
 /** @template-extends AbstractType<array<string, mixed>> */
 class LaunchType extends AbstractType
 {

src/Form/Type/ProcessContextType.php

@@ -18,6 +18,9 @@
 use Symfony\Component\OptionsResolver\OptionsResolver;
 use Symfony\Component\Validator\Constraints\NotBlank;
 
+/**
+ * @internal
+ */
 /** @template-extends AbstractType<null> */
 class ProcessContextType extends AbstractType
 {

src/Http/ValueResolver/HttpProcessExecuteValueResolver.php

@@ -22,6 +22,9 @@
 use Symfony\Component\HttpKernel\ControllerMetadata\ArgumentMetadata;
 use Symfony\Component\Serializer\SerializerInterface;
 
+/**
+ * @internal
+ */
 #[AsTargetedValueResolver('http_process_execution')]
 readonly class HttpProcessExecuteValueResolver implements ValueResolverInterface
 {

src/Manager/ProcessExecutionManager.php

@@ -17,6 +17,9 @@
 use CleverAge\UiProcessBundle\Repository\ProcessExecutionRepository;
 use Symfony\Contracts\Service\ResetInterface;
 
+/**
+ * @final since 3.3
+ */
 class ProcessExecutionManager implements ResetInterface
 {
     private ?ProcessExecution $currentProcessExecution = null;

src/Message/CronProcessMessageHandler.php

@@ -19,6 +19,9 @@
 use Symfony\Component\Messenger\Attribute\AsMessageHandler;
 use Symfony\Component\Messenger\MessageBusInterface;
 
+/**
+ * @internal
+ */
 #[AsMessageHandler]
 final readonly class CronProcessMessageHandler
 {

src/Message/ProcessExecuteHandler.php

@@ -17,6 +17,9 @@
 use CleverAge\UiProcessBundle\Monolog\Handler\ProcessHandler;
 use Symfony\Component\Messenger\Attribute\AsMessageHandler;
 
+/**
+ * @internal
+ */
 #[AsMessageHandler]
 readonly class ProcessExecuteHandler
 {

src/Message/ProcessExecuteMessage.php

@@ -13,6 +13,9 @@
 
 namespace CleverAge\UiProcessBundle\Message;
 
+/**
+ * @final since 3.3
+ */
 readonly class ProcessExecuteMessage
 {
     /**

src/Monolog/Handler/DoctrineProcessHandler.php

@@ -21,6 +21,9 @@
 use Monolog\Level;
 use Monolog\LogRecord;
 
+/**
+ * @internal
+ */
 class DoctrineProcessHandler extends AbstractProcessingHandler
 {
     /** @var ArrayCollection<int, LogRecord> */

src/Monolog/Handler/ProcessHandler.php

@@ -18,6 +18,9 @@
 use Monolog\Level;
 use Monolog\LogRecord;
 
+/**
+ * @internal
+ */
 class ProcessHandler extends StreamHandler
 {
     private Level $reportIncrementLevel = Level::Warning;

src/Notifier/ProcessExecutionNotification.php

@@ -18,6 +18,8 @@
 
 /**
  * Notification sent at the end of a process execution.
+ *
+ * @final since 3.3
  */
 class ProcessExecutionNotification extends Notification
 {

src/Repository/ProcessExecutionRepository.php

@@ -26,6 +26,8 @@
  * @method ProcessExecution|null findOneBy(mixed[] $criteria, string[] $orderBy = null)
  * @method ProcessExecution[]    findAll()
  * @method ProcessExecution[]    findBy(mixed[] $criteria, string[] $orderBy = null, $limit = null, $offset = null)
+ *
+ * @final since 3.3
  */
 class ProcessExecutionRepository extends EntityRepository
 {

src/Repository/ProcessScheduleRepository.php

@@ -25,6 +25,8 @@
  * @method ProcessSchedule|null findOneBy(mixed[] $criteria, string[] $orderBy = null)
  * @method ProcessSchedule[]    findAll()
  * @method ProcessSchedule[]    findBy(mixed[] $criteria, string[] $orderBy = null, $limit = null, $offset = null)
+ *
+ * @final since 3.3
  */
 class ProcessScheduleRepository extends EntityRepository
 {

src/Scheduler/CronScheduler.php

@@ -23,6 +23,9 @@
 use Symfony\Component\Scheduler\ScheduleProviderInterface;
 use Symfony\Component\Validator\Validator\ValidatorInterface;
 
+/**
+ * @internal
+ */
 readonly class CronScheduler implements ScheduleProviderInterface
 {
     public function __construct(

src/Security/HttpProcessExecutionAuthenticator.php

@@ -26,6 +26,9 @@
 use Symfony\Component\Security\Http\Authenticator\Passport\Passport;
 use Symfony\Component\Security\Http\Authenticator\Passport\SelfValidatingPassport;
 
+/**
+ * @internal
+ */
 class HttpProcessExecutionAuthenticator extends AbstractAuthenticator
 {
     public function __construct(private readonly EntityManagerInterface $entityManager)

src/StopChecker/ProcessExecutionStopChecker.php

@@ -26,6 +26,8 @@
  *
  * DBAL queries are used: no ORM query per item, and the entity manager may have been cleared or closed by the process
  * tasks.
+ *
+ * @internal
  */
 class ProcessExecutionStopChecker implements ProcessStopCheckerInterface
 {

src/Twig/Components/BootstrapModal.php

@@ -13,6 +13,9 @@
 
 namespace CleverAge\UiProcessBundle\Twig\Components;
 
+/**
+ * @internal
+ */
 class BootstrapModal
 {
     public ?string $id = null;

src/Twig/Extension/LogLevelExtension.php

@@ -17,6 +17,9 @@
 use Twig\Extension\AbstractExtension;
 use Twig\TwigFunction;
 
+/**
+ * @internal
+ */
 class LogLevelExtension extends AbstractExtension
 {
     #[\Override]

src/Twig/Extension/MD5Extension.php

@@ -17,6 +17,9 @@
 use Twig\Extension\AbstractExtension;
 use Twig\TwigFilter;
 
+/**
+ * @internal
+ */
 class MD5Extension extends AbstractExtension
 {
     #[\Override]

src/Twig/Extension/ProcessExecutionExtension.php

@@ -17,6 +17,9 @@
 use Twig\Extension\AbstractExtension;
 use Twig\TwigFunction;
 
+/**
+ * @internal
+ */
 class ProcessExecutionExtension extends AbstractExtension
 {
     #[\Override]