🚧 V2: Rewrite for PHP 8.1 Enum

[ogizanagi]

First step was made in #165 to rewrite the lib with the new native enum types & adding some integrations based on it and our specificities (readables, flags, …).

📚 See current V2 documentation here

🚧 More work to come. Help welcome to integrate what could be useful, from 1.x features or whole new ones.

Will probable create a 2.0.0-alpha1 tag in the next weeks.

---

V2 Features

Core features

From V1, core features extending the PHP 8.1 native enum capabilities

• Readable enums ➜ Done in V2: Rewrite with PHP 8.1 enums #165.
• Flag enums ➜ Done in V2: Rewrite with PHP 8.1 enums #165.
  It requires a new FlagBag object to manipulate flags, since PHP native enums are restricted to their cases and cannot dynamically declare combinations.

New features

Whole new features or integration, leveraging new enum capabilities

• Overblog GraphQL type? Might be supported by them directly.
• ???

(Pending) official integrations

From V1, likely to be dropped in the future, or already having an official integration

• Serializer integration
  Core PR: [Serializer] Support for PHP 8.1 enums symfony/symfony#40241
• Doctrine DBAL Types & types generator:
  Doctrine is likely to provide DBAL types for enums in the future, but the current type system lacks a way to easily register it.
  ➜ Doctrine guys found a workaround in Add support for PHP 8.1 enums. doctrine/orm#9304.
  We might consider dropping our implementation, but collection and flag bag support is still valid. Also our current implementation supports specifying a default on null.
  • Basic \BackedEnum support
    ➜ Done in V2: Rewrite with PHP 8.1 enums #165. Documentation
  • Collection of enums (csv & json)
  • FlagBag DBAL type for persisting flag enums combination ➜ Initial DBAL FlagBag support #186
• Doctrine ODM Types & types generator:
  • Basic \BackedEnum support: ➜ Add Doctrine ODM integration #176
  • Collection of enums: ➜ Add Doctrine ODM integration #176
  • FlagBag ODM type for persisting flag enums combination
• HTTP Kernel Controller Argument Resolver
  Nothing in Symfony core yet?
  • Core PR => [HttpKernel] Add a controller argument resolver for backed enums symfony/symfony#44831
  • V2 PR: [HttpKernel] Add a controller argument resolver for backed enums #169
• API Platform
  no specificity for readable or flagged enum? Anything else to consider?
  Core PR: PHP 8.1 Backed enums api-platform/core#4349
• Faker
  could be contributed to FakerPHP directly for native enum support
  ➜ rejected in add Enum generator FakerPHP/Faker#421.
  We might only want to port randomEnum from V1 to get a random enum case from given enum FQCN.
  Porting the namespace aliases feature might not be relevant, since it was targeting Nelmio Alice's fixtures generator DSL, but Foundry is getting more popularity now.
  ➜ add Faker provider #177
• Validator constraint.
  Rejected for now in [Validator] Support enums in Choice constraints symfony/symfony#43047. Could provide the alternative here and re-discuss in Symfony's core later if proven useful.

Extra integrations

From V1, might still be relevant/adapted

• VarDumper casters
  Core PR: [VarDumper] add support for enums on PHP 8.1 symfony/symfony#40238)
  • Add VarDumper caster for readables #167
  • Add VarDumper caster for flag bag #168
• Symfony Form Type
  Core PR: [Form] Add the EnumType symfony/symfony#43095
  • Extend core EnumType for readable enums
    ➜ Done in V2: Rewrite with PHP 8.1 enums #165. Documentation
  • FlagBag Form type to combine flag enums
    ➜ Done in FlagBagType support #183
• Javascript generator
• Twig extension ? Any needs ?
• translation extractor & config for readables

Extra tasks

• Write an UPGRADE-2.x.md guide, with most basic hints for upgrading your application code from 1.x to 2.x

[jensstalder]

Tried my hands with porting the ApiPlatform bridge over. Maybe it helps?

<?php

/*
 * This file is part of the "elao/enum" package.
 *
 * Copyright (C) Elao
 *
 * @author Elao <contact@elao.com>
 */

namespace App\ApiPlatform\Core\JsonSchema\Type;

use ApiPlatform\Core\JsonSchema\Schema;
use ApiPlatform\Core\JsonSchema\TypeFactoryInterface;
use Elao\Enum\ReadableEnumInterface;
use Symfony\Component\PropertyInfo\Type;

final class ElaoEnumType implements TypeFactoryInterface
{
    /** @var TypeFactoryInterface */
    private $decorated;

    public function __construct(TypeFactoryInterface $decorated)
    {
        $this->decorated = $decorated;
    }

    /**
     * {@inheritdoc}
     */
    public function getType(Type $type, string $format = 'json', ?bool $readableLink = null, ?array $serializerContext = null, Schema $schema = null): array
    {
        if (!is_a($enum = $type->getClassName(), ReadableEnumInterface::class, true)) {
            return $this->decorated->getType($type, $format, $readableLink, $serializerContext, $schema);
        }

        $ref = new \ReflectionEnum($type->getClassName());
        $docType = '';
        switch ($ref->getBackingType()) {
            case 'string': $docType = 'string'; break;
            case 'int': $docType = 'integer'; break;
            case null:
            default:
                $docType = 'string';
                break;
        }
        $schema = [];
        $cases = $enum::cases();
        if ($type->isNullable() && !$type->isCollection()) {
            $cases[] = null;
        }
        $readableCases = [];
        foreach ($cases as $case) {
            //$readableCases[$case->value] = $case->getReadable();
            $readableCases[$case->value] = $case->value . '=' . $case->name;
        }
        $enumSchema = [
            'type' => $docType,
            'enum' => $readableCases,
            'example' => $cases[0]->value,
        ];

        if ($type->isCollection()) {
            $schema['type'] = 'array';
            $schema['items'] = $enumSchema;
        } else {
            $schema = $enumSchema;
        }

        if ($type->isNullable()) {
            $schema['nullable'] = true;
        }

        return $schema;
    }
}

[ogizanagi]

Hi @jensstalder . Thank you very much for looking at this.

Could you please explain me a bit more what would be the purpose of such a bridge now with native PHP enum?
I see the $readableCases used as $enumSchema.enum in your sample, but is that correct?
An API would rely on the backed value (as in the previous version of this library), not the readable one. But is there some places where the readable label could be relevant?

You might have more clues than me on what could be relevant to provide in such a bridge regarding the features that are specific to this lib v2 extending native enums capabilities. So, your help is appreciated :)

[jensstalder]

@ogizanagi Good question. The only benefit I see in relation to JsonSchema is that it shows up in the open API docs. My original goal was to extend the graphql implementation so that the types also get interpreted as enum. I have not found a solution for that yet. But thinking about it, it's true that API platform core should instead simply handle native enums better for both cases (JsonSchema and GraphQL), and it might not be necessary to do this within this package. But this might be a bit to opinionated from the view of the platform? As far as I can tell though, API platform currently only considers the backing type as if it were a simple string or int field? And Graphql endpoint hides the enum typed field completely (but that could be another issue).

[michnovka]

For Doctrine there is one issue affecting this lib

• ENUMs cannot be used as IDs (I made a PR Support Enum IDs and search by Enum fields doctrine/orm#9629 which hopefully will be merged soon)

Please add it on the list

EDIT: merged

[michnovka]

@ogizanagi the doctrine/orm#9629 has been merged in doctrine/orm 2.12.x , so you can remove the known issue from the list