Add enum support for DCAs and models

[SeverinGloeckle]

Implements #6546

A few notes on the implementation:

1. Usage of TranslatableMessage

The generation of translated references for the generated options is implemented via Symfony’s TranslatableMessage.

In my opinion, this is the most sane way to handle translations in a complex system with various sources of translation.

Using Symfony’s TranslatableInterface however is less restrictive, but does not provide the additional information on parameters and especially on the translation domain.

Although it is outside the scope of this PR, a forward-looking decision ought to be made on how Contao wants to deal with translations in the future. Up to now, neither of the two interfaces is being used.

2. Validation of enum values in the model

It’s not straightforward to define a proper handling of invalid enum values in the model. One could:

• simply return null for invalid values
• raise an exception explaining the invalid value (like implemented)
  • Since there is no built-in way to detect whether an enum is backed by strings or integers, only a generic exception for both types is possible (without adding somethin like an EnumUtil).
• let the call to BackedEnum::tryFrom() fail with the invalid value and let it throw its TypeError

I implemented the second way in order to give developers a proper hint pointing to the DCA configuration but the other two ways are reasonable as well.

3. Modifications & unit tests for legacy code

For the changes to the legacy code, I stuck to existing styles and structures as much as possible.

For the model, only a simple unit test is added for resolving the enum - if necessary, I can also add tests for the various exceptions.

4. Needs documentation

If this will be merged, I'll also add corresponding notes to the developer documentation.

[aschempp]

Any particular reason we need the DcaExtractor to read the enums? Why not just use the listener to convert enum to string options?

[SeverinGloeckle]

The DcaExtractor maps the individual fields to the configured enum classes and transfers this assignment to the model.

To resolve the enums via Model::getEnum(), the specific enum class is required in addition to the value of the field (see example in third section of #6546)

[leofeyer]

I can confirm that the code works. 👍

[leofeyer]

@aschempp Has your question above been answered?

@contao/developers Shall we add two example enums so people can use them as templates for their own enums?

namespace Contao\CoreBundle\DataContainer\Enum;

enum PageRobotsEnum: string
{
    case indexFollow = 'index,follow';
    case indexNofollow = 'index,nofollow';
    case noindexFollow = 'noindex,follow';
    case noindexNofollow = 'noindex,nofollow';
}

namespace Contao\CoreBundle\DataContainer\Enum;

use Contao\CoreBundle\Translation\TranslatableLabelInterface;
use Symfony\Component\Translation\TranslatableMessage;

enum PageRedirectEnum: string implements TranslatableLabelInterface
{
    case permanent = 'permanent';
    case temporary = 'temporary';

    public function label(): TranslatableMessage
    {
        return new TranslatableMessage('tl_page.'.$this->name, [], 'contao_tl_page');
    }
}

Do you agree with the namespace?

[Toflar]

@SeverinGloeckle any reason you did not go for 'options' -> Enum but a new key instead?

[SeverinGloeckle]

@contao/developers Shall we add two example enums so people can use them as templates for their own enums?

enum PageRobotsEnum: string

enum PageRedirectEnum: string implements TranslatableLabelInterface

The two examples are a very good idea. However, I would prefer to add them in a follow-up PR for an independent discussion (namespace, extensibility, possibly resolution within the PageModel).

I may create a follow-up PR as soon as this PR has been merged.

[SeverinGloeckle]

@SeverinGloeckle any reason you did not go for 'options' -> Enum but a new key instead?

From my point of view, the explicit tagging of the enum provides the following benefits:

1. unambiguous check whether a DCA field is linked to an enum (no type check)
2. generation of references even if the options were overwritten manually (see 90f9e22)
3. no side effects on third party code (which may rely on options being an array)

[Toflar]

I'm fine with that

[leofeyer]

Thank you @SeverinGloeckle.