From 431e8b993f39a37573ab64ce157ae0f1aeb37cae Mon Sep 17 00:00:00 2001
From: nadar <git@nadar.io>
Date: Mon, 12 Oct 2026 14:52:49 +0300
Subject: [PATCH 1/4] feat(generator): name the options of block fields as
 class constants

Every content and config field of a block whose type is a union of
literals, a select field's `value` included, gets one constant per
option, named `<CONTENT|CONFIG>_<FIELD>_<OPTION>`:
`CONTENT_SIZE_SMALL = 'small'`, `CONFIG_SIZE_SMALL = 'small'`. The
values are the strings TypeMapper writes into the field's type, so
comparing a field with a constant type-checks wherever comparing it
with the literal does. A name that would stand for two different
options is not generated, with a warning, rather than numbered: a
number would silently move to another option once one is added.

Only flyo-generate-types generates them. The deprecated
flyo-generate-blocks keeps producing byte-identical files.

An enum member containing `*/` closed the docblock its type is
rendered into, so the generated file did not parse. Such an enum now
falls back to `string`, like one with a newline.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SjJHX6UBVjHdxaoMgHLZYC
---
 lib/Generator/BlockKind.php     |  53 ++++++++-
 lib/Generator/ConstantDef.php   |   3 +
 lib/Generator/EnumConstants.php | 189 ++++++++++++++++++++++++++++++++
 lib/Generator/Naming.php        |  28 ++++-
 lib/Generator/Profile.php       |   3 +-
 lib/Generator/Renderer.php      |   5 +-
 lib/Generator/TypeMapper.php    |  68 ++++++++----
 7 files changed, 317 insertions(+), 32 deletions(-)
 create mode 100644 lib/Generator/EnumConstants.php

diff --git a/lib/Generator/BlockKind.php b/lib/Generator/BlockKind.php
index bb900f7..1a6021b 100644
--- a/lib/Generator/BlockKind.php
+++ b/lib/Generator/BlockKind.php
@@ -8,7 +8,8 @@
  * Blocks: one class per `x-schema-type: block` schema, narrowing \Flyo\Model\Block.
  *
  * The deprecated `flyo-generate-blocks` renders these same classes, so any change to their output
- * shows up as drift in every consumer's `--check` and has to be deliberate.
+ * shows up as drift in every consumer's `--check` and has to be deliberate. That is why it plans
+ * them without the {@see EnumConstants}, which came later.
  */
 final class BlockKind implements Kind
 {
@@ -31,6 +32,21 @@ final class BlockKind implements Kind
     /** Never a real slot: the server adds it as a bookkeeping flag. */
     private const SLOT_FLAG = '_empty';
 
+    /**
+     * The block schema properties whose fields get {@see EnumConstants}: the two an editor fills
+     * in. `CONTENT_SIZE_SMALL` names an option of `content.size`, `CONFIG_SIZE_SMALL` one of
+     * `config.size`.
+     */
+    private const ENUM_OBJECTS = ['content', 'config'];
+
+    /**
+     * @param bool $enumConstants name the options of every content and config field that has a
+     *  fixed set of them; off for the deprecated flyo-generate-blocks, whose output stays as it was
+     */
+    public function __construct(private readonly bool $enumConstants = true)
+    {
+    }
+
     public function schemaType(): string
     {
         return 'block';
@@ -67,7 +83,14 @@ public function plan(Document $document, array $schemas, string $namespace, Warn
         // Pass 2: plan.
         $classes = [];
         foreach ($schemas as $schemaKey => $schema) {
-            $classes[] = $this->classDef($schemaKey, $schema, $classNames[$schemaKey], $namespace, $types);
+            $classes[] = $this->classDef(
+                $schemaKey,
+                $schema,
+                $classNames[$schemaKey],
+                $namespace,
+                $types,
+                $warnings,
+            );
         }
 
         return $classes;
@@ -82,6 +105,7 @@ private function classDef(
         string $className,
         string $namespace,
         TypeMapper $types,
+        Warnings $warnings,
     ): ClassDef {
         $required = Schema::requiredKeys($schema);
 
@@ -115,6 +139,12 @@ private function classDef(
         if ($slots !== []) {
             $constants[] = new ConstantDef('SLOTS', $slots);
         }
+        if ($this->enumConstants) {
+            $constants = [
+                ...$constants,
+                ...EnumConstants::plan($schemaKey, self::enumObjects($schema), $warnings),
+            ];
+        }
 
         return new ClassDef(
             $className,
@@ -131,6 +161,25 @@ private function classDef(
         );
     }
 
+    /**
+     * @param array<string, mixed> $schema
+     * @return array<string, array<string, mixed>>
+     */
+    private static function enumObjects(array $schema): array
+    {
+        $objects = [];
+
+        foreach (self::ENUM_OBJECTS as $property) {
+            $object = Schema::property($schema, $property);
+
+            if ($object !== null) {
+                $objects[$property] = $object;
+            }
+        }
+
+        return $objects;
+    }
+
     /**
      * The declared slot identifiers, in document order.
      *
diff --git a/lib/Generator/ConstantDef.php b/lib/Generator/ConstantDef.php
index 6485e38..7199648 100644
--- a/lib/Generator/ConstantDef.php
+++ b/lib/Generator/ConstantDef.php
@@ -14,10 +14,13 @@ final class ConstantDef
 {
     /**
      * @param string|list<string> $value
+     * @param string|null $group constants that share a group are rendered without a blank line
+     *  between them, like the options of one field
      */
     public function __construct(
         public readonly string $name,
         public readonly string|array $value,
+        public readonly ?string $group = null,
     ) {
     }
 }
diff --git a/lib/Generator/EnumConstants.php b/lib/Generator/EnumConstants.php
new file mode 100644
index 0000000..103827f
--- /dev/null
+++ b/lib/Generator/EnumConstants.php
@@ -0,0 +1,189 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flyo\Generator;
+
+/**
+ * Class constants naming the options of every field that has a fixed set of them.
+ *
+ * Each option becomes `<OBJECT>_<FIELD>_<OPTION>`: a block whose content has a `size` select with
+ * the options `small` and `large` gets `CONTENT_SIZE_SMALL = 'small'` and
+ * `CONTENT_SIZE_LARGE = 'large'`. The options are the field's own `enum`, or, for a select field,
+ * the `enum` of its `value`. `null` is never one: it means nothing is selected.
+ *
+ * The values are exactly the strings {@see TypeMapper} puts in the field's type, so comparing the
+ * field with a constant type-checks wherever comparing it with the literal does.
+ */
+final class EnumConstants
+{
+    /** The property a select field keeps the selected option in. */
+    private const SELECT_VALUE = 'value';
+
+    /** Keywords {@see TypeMapper::type()} acts on before it ever looks at an `enum`. */
+    private const PRECEDING_KEYWORDS = ['$ref', 'oneOf', 'anyOf', 'allOf'];
+
+    private function __construct()
+    {
+    }
+
+    /**
+     * The constants for the fields of some object schemas of one typed schema.
+     *
+     * A name that would stand for two different options is not generated at all, rather than
+     * numbered: a number would silently move to another option once one is added in Flyo, while a
+     * missing constant fails loudly wherever it is used.
+     *
+     * @param string $schemaKey the typed schema, for warnings
+     * @param array<string, array<string, mixed>> $objects property => the object schema whose
+     *  fields to scan, e.g. `content` => a block's content schema; the property names the prefix
+     * @return list<ConstantDef> in document order, grouped by field
+     */
+    public static function plan(string $schemaKey, array $objects, Warnings $warnings): array
+    {
+        /** @var array<string, list<array{string, string}>> $claims name => [field path, option] */
+        $claims = [];
+
+        foreach ($objects as $property => $object) {
+            $fields = $object['properties'] ?? null;
+
+            if (!is_array($fields)) {
+                continue;
+            }
+
+            $prefix = Naming::constantSegment($property);
+
+            foreach ($fields as $field => $fieldSchema) {
+                // A numeric-looking JSON key arrives as an int.
+                $field = (string) $field;
+                $options = is_array($fieldSchema) ? self::options($fieldSchema) : [];
+
+                if ($options === []) {
+                    continue;
+                }
+
+                $path = $property . '.' . $field;
+                $fieldSegment = Naming::constantSegment($field);
+
+                if ($fieldSegment === '') {
+                    $warnings->add(sprintf(
+                        '%s.%s: the field name has no letter or digit to name constants after, so its '
+                            . 'options get none.',
+                        $schemaKey,
+                        $path,
+                    ));
+
+                    continue;
+                }
+
+                foreach ($options as $option) {
+                    $optionSegment = Naming::constantSegment($option);
+
+                    if ($optionSegment === '') {
+                        $warnings->add(sprintf(
+                            '%s.%s: the option "%s" has no letter or digit to name a constant after, so '
+                                . 'it gets none.',
+                            $schemaKey,
+                            $path,
+                            $option,
+                        ));
+
+                        continue;
+                    }
+
+                    $claims[$prefix . '_' . $fieldSegment . '_' . $optionSegment][] = [$path, $option];
+                }
+            }
+        }
+
+        $constants = [];
+
+        foreach ($claims as $name => $claimants) {
+            $options = array_values(array_unique(array_column($claimants, 1)));
+
+            if (count($options) > 1) {
+                $rendered = [];
+                foreach ($claimants as [$path, $option]) {
+                    $rendered[] = sprintf('%s "%s"', $path, $option);
+                }
+
+                $warnings->add(sprintf(
+                    '%s: %s would stand for more than one option (%s), so it is not generated. '
+                        . 'Rename one of the options in Flyo to remove the ambiguity.',
+                    $schemaKey,
+                    $name,
+                    implode(', ', $rendered),
+                ));
+
+                continue;
+            }
+
+            $constants[] = new ConstantDef($name, $options[0], $claimants[0][0]);
+        }
+
+        return $constants;
+    }
+
+    /**
+     * The options of one field, or `[]` when it has no fixed set of them.
+     *
+     * @param array<string, mixed> $field
+     * @return list<string>
+     */
+    private static function options(array $field): array
+    {
+        $options = self::literals($field);
+
+        if ($options !== null) {
+            return $options;
+        }
+
+        // A select field: an object whose `value` is one of the options, or null.
+        if (($field['type'] ?? null) !== 'object' || self::isDeferred($field)) {
+            return [];
+        }
+
+        $value = Schema::property($field, self::SELECT_VALUE);
+
+        return $value === null ? [] : (self::literals($value) ?? []);
+    }
+
+    /**
+     * The non-null members of a node's `enum`, or null unless TypeMapper types the node as a union
+     * of exactly those literals: a node typed `string`, or not typed at all.
+     *
+     * @param array<string, mixed> $node
+     * @return list<string>|null
+     */
+    private static function literals(array $node): ?array
+    {
+        $type = $node['type'] ?? null;
+
+        if (($type !== null && $type !== 'string') || self::isDeferred($node)) {
+            return null;
+        }
+
+        $members = TypeMapper::enumMembers($node);
+
+        return $members === null ? null : array_values(array_filter(
+            $members,
+            static fn (?string $member): bool => $member !== null,
+        ));
+    }
+
+    /**
+     * Whether TypeMapper types the node by something other than its own keywords.
+     *
+     * @param array<string, mixed> $node
+     */
+    private static function isDeferred(array $node): bool
+    {
+        foreach (self::PRECEDING_KEYWORDS as $keyword) {
+            if (isset($node[$keyword])) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}
diff --git a/lib/Generator/Naming.php b/lib/Generator/Naming.php
index 3c1cdcb..58a3508 100644
--- a/lib/Generator/Naming.php
+++ b/lib/Generator/Naming.php
@@ -5,13 +5,13 @@
 namespace Flyo\Generator;
 
 /**
- * Derives generated class names from typed schemas.
+ * Derives generated class and constant names from typed schemas.
  *
- * The class name is the only identifier this generator invents, since nested shapes are described
- * inline rather than as named types. Every name keeps its kind's prefix (`BlockHero`,
- * `EntityArticle`, `ContainerMain`), exactly as the server keys the schema: that keeps a class
- * lined up with its schema, and it means no author-supplied name can ever produce a reserved word
- * such as `List` or `Default` as a class name.
+ * Class names and the names of {@see EnumConstants} are the only identifiers this generator
+ * invents, since nested shapes are described inline rather than as named types. Every class name
+ * keeps its kind's prefix (`BlockHero`, `EntityArticle`, `ContainerMain`), exactly as the server
+ * keys the schema: that keeps a class lined up with its schema, and it means no author-supplied
+ * name can ever produce a reserved word such as `List` or `Default` as a class name.
  */
 final class Naming
 {
@@ -45,6 +45,22 @@ public static function studly(string $raw): string
         return $out;
     }
 
+    /**
+     * One upper-case segment of a constant name: `background-color` and `backgroundColor` both
+     * become `BACKGROUND_COLOR`.
+     *
+     * Splits like {@see studly()}, and between a lower- and an upper-case letter as well. Returns
+     * `''` when there is no letter or digit to name anything after. A leading digit is fine, since
+     * a segment never starts a constant name.
+     */
+    public static function constantSegment(string $raw): string
+    {
+        $raw = preg_replace('/(\p{Ll})(\p{Lu})/u', '$1 $2', $raw) ?? '';
+        $parts = preg_split('/[^\p{L}\p{N}]+/u', $raw, -1, PREG_SPLIT_NO_EMPTY);
+
+        return mb_strtoupper(implode('_', $parts ?: []));
+    }
+
     /**
      * The class name each block schema gets, keyed by schema name.
      *
diff --git a/lib/Generator/Profile.php b/lib/Generator/Profile.php
index 9396665..2bcd815 100644
--- a/lib/Generator/Profile.php
+++ b/lib/Generator/Profile.php
@@ -55,7 +55,8 @@ public static function blocks(): self
     {
         return new self(
             program: 'flyo-generate-blocks',
-            kinds: [new BlockKind()],
+            // Frozen: enum constants came after this command was deprecated.
+            kinds: [new BlockKind(enumConstants: false)],
             flat: true,
             reportUnsupported: false,
             deprecation: 'flyo-generate-blocks is deprecated and will be removed in the next major '
diff --git a/lib/Generator/Renderer.php b/lib/Generator/Renderer.php
index 1da8886..bf20064 100644
--- a/lib/Generator/Renderer.php
+++ b/lib/Generator/Renderer.php
@@ -110,12 +110,15 @@ private function classDocblock(ClassDef $class): array
     private function constants(ClassDef $class): array
     {
         $lines = [];
+        $group = null;
 
         foreach ($class->constants as $constant) {
-            if ($lines !== []) {
+            if ($lines !== [] && ($constant->group === null || $constant->group !== $group)) {
                 $lines[] = '';
             }
 
+            $group = $constant->group;
+
             if (is_array($constant->value)) {
                 $values = array_map(static fn (string $value): string => self::literal($value), $constant->value);
 
diff --git a/lib/Generator/TypeMapper.php b/lib/Generator/TypeMapper.php
index edfe1fb..30d1df7 100644
--- a/lib/Generator/TypeMapper.php
+++ b/lib/Generator/TypeMapper.php
@@ -218,48 +218,72 @@ private function intType(array $schema): string
     }
 
     /**
-     * An `enum` rendered as a union of literal strings, or null when that is not safe.
+     * The members of an `enum` as the strings its literal union spells them, in document order and
+     * without duplicates, or null when the enum is absent, empty or not safe to render.
+     *
+     * A `null` member stays null. It is how OpenAPI 3.0 lets a nullable enum actually hold null
+     * (`nullable: true` alone does not), as a select field's `value` does.
      *
-     * A `null` member is how OpenAPI 3.0 lets a nullable enum actually hold null (`nullable: true`
-     * alone does not), as a select field's `value` does. It becomes a trailing `null` rather than
-     * disqualifying the whole enum.
+     * {@see EnumConstants} names its constants after these same strings, so a constant always has
+     * a type the field's own type accepts.
      *
      * @param array<string, mixed> $schema
+     * @return list<string|null>|null
      */
-    private function literalUnion(array $schema): ?string
+    public static function enumMembers(array $schema): ?array
     {
         $enum = $schema['enum'] ?? null;
         if (!is_array($enum) || $enum === []) {
             return null;
         }
 
-        $literals = [];
-        $hasNull = false;
+        $members = [];
         foreach ($enum as $value) {
-            if ($value === null) {
-                $hasNull = true;
-                continue;
+            if ($value !== null) {
+                // A block id may be a number even though the property is typed string.
+                if (!is_scalar($value)) {
+                    return null;
+                }
+
+                $value = is_bool($value) ? ($value ? '1' : '') : (string) $value;
+
+                // A newline or a comment terminator would break out of the docblock; not worth
+                // escaping for.
+                if (preg_match('/[\r\n]|\*\//', $value) === 1) {
+                    return null;
+                }
             }
 
-            // A block id may be a number even though the property is typed string.
-            if (!is_scalar($value)) {
-                return null;
+            if (!in_array($value, $members, true)) {
+                $members[] = $value;
             }
+        }
 
-            $string = is_bool($value) ? ($value ? '1' : '') : (string) $value;
+        return $members;
+    }
 
-            // A newline would break out of the docblock; not worth escaping for.
-            if (preg_match('/[\r\n]/', $string) === 1) {
-                return null;
-            }
+    /**
+     * An `enum` rendered as a union of literal strings, or null when that is not safe.
+     *
+     * A `null` member becomes a trailing `null` rather than disqualifying the whole enum.
+     *
+     * @param array<string, mixed> $schema
+     */
+    private function literalUnion(array $schema): ?string
+    {
+        $members = self::enumMembers($schema);
+        if ($members === null) {
+            return null;
+        }
 
-            $literal = "'" . str_replace(['\\', "'"], ['\\\\', "\\'"], $string) . "'";
-            if (!in_array($literal, $literals, true)) {
-                $literals[] = $literal;
+        $literals = [];
+        foreach ($members as $member) {
+            if ($member !== null) {
+                $literals[] = "'" . str_replace(['\\', "'"], ['\\\\', "\\'"], $member) . "'";
             }
         }
 
-        if ($hasNull) {
+        if (in_array(null, $members, true)) {
             $literals[] = 'null';
         }
 

From 11b2e7443440f40f6c44a5966b29b18c8251e082 Mon Sep 17 00:00:00 2001
From: nadar <git@nadar.io>
Date: Mon, 12 Oct 2026 14:55:15 +0300
Subject: [PATCH 2/4] test(generator): cover the enum constants and document
 them

A types/enums fixture with select and plain enum fields in content and
config, its golden file, and level 9 PHPStan assertions: a match over a
field with its constants as arms is only exhaustive when the constants
cover exactly the literals of the field's type.

Unit tests for EnumConstants (detection, naming, collisions, fields
that get none), Naming::constantSegment(), TypeMapper::enumMembers(),
hostile option values, and that the deprecated command generates no
enum constants.

README and UPGRADE describe the constants and the `*/` fix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SjJHX6UBVjHdxaoMgHLZYC
---
 phpstan-generated.neon                        |   1 +
 test/Generator/EnumConstantsTest.php          | 308 ++++++++++++++++++
 test/Generator/FixtureTrait.php               |   1 +
 test/Generator/GoldenTest.php                 |  43 +++
 test/Generator/NamingTest.php                 |  32 ++
 test/fixtures/types/enums/assertions.php      |  77 +++++
 .../types/enums/expected/Blocks/BlockCard.php | 124 +++++++
 test/fixtures/types/enums/openapi.json        |  96 ++++++
 8 files changed, 682 insertions(+)
 create mode 100644 test/Generator/EnumConstantsTest.php
 create mode 100644 test/fixtures/types/enums/assertions.php
 create mode 100644 test/fixtures/types/enums/expected/Blocks/BlockCard.php
 create mode 100644 test/fixtures/types/enums/openapi.json

diff --git a/phpstan-generated.neon b/phpstan-generated.neon
index 746fd1e..c3e5857 100644
--- a/phpstan-generated.neon
+++ b/phpstan-generated.neon
@@ -17,5 +17,6 @@ parameters:
     - test/fixtures/blocks/collisions
     # Output of flyo-generate-types, one sub-namespace per kind.
     - test/fixtures/types/site
+    - test/fixtures/types/enums
   bootstrapFiles:
     - vendor/autoload.php
diff --git a/test/Generator/EnumConstantsTest.php b/test/Generator/EnumConstantsTest.php
new file mode 100644
index 0000000..bb23e12
--- /dev/null
+++ b/test/Generator/EnumConstantsTest.php
@@ -0,0 +1,308 @@
+<?php
+
+namespace Flyo\Test\Generator;
+
+use Flyo\Generator\ConstantDef;
+use Flyo\Generator\EnumConstants;
+use Flyo\Generator\Warnings;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+class EnumConstantsTest extends TestCase
+{
+    public function testAFieldWithAnEnumGetsOneConstantPerOption(): void
+    {
+        $this->assertSame(
+            ['CONTENT_ALIGN_LEFT' => 'left', 'CONTENT_ALIGN_RIGHT' => 'right'],
+            self::constants(['content' => self::object([
+                'align' => ['type' => 'string', 'enum' => ['left', 'right']],
+            ])])
+        );
+    }
+
+    /**
+     * A select field is an object whose `value` holds the option, so the options come from there
+     * and the name leaves `value` out. `null` means nothing is selected; it is not an option.
+     */
+    public function testASelectFieldIsNamedAfterTheFieldNotItsValue(): void
+    {
+        $this->assertSame(
+            [
+                'CONTENT_SIZE_SMALL' => 'small',
+                'CONTENT_SIZE_MEDIUM' => 'medium',
+                'CONTENT_SIZE_LARGE' => 'large',
+            ],
+            self::constants(['content' => self::object([
+                'size' => self::select(['small', 'medium', 'large', null]),
+            ])])
+        );
+    }
+
+    public function testContentAndConfigGetAPrefixEach(): void
+    {
+        $this->assertSame(
+            [
+                'CONTENT_SIZE_SMALL' => 'small',
+                'CONTENT_SIZE_LARGE' => 'large',
+                'CONFIG_SIZE_SMALL' => 'small',
+            ],
+            self::constants([
+                'content' => self::object(['size' => self::select(['small', 'large', null])]),
+                'config' => self::object(['size' => self::select(['small', null])]),
+            ])
+        );
+    }
+
+    public function testNamesAreUpperSnakeCaseAndValuesStayVerbatim(): void
+    {
+        $this->assertSame(
+            [
+                'CONTENT_BACKGROUND_COLOR_DARK_BLUE' => 'darkBlue',
+                'CONTENT_BACKGROUND_COLOR_LIGHT_GRAY' => 'light-gray',
+                'CONTENT_BACKGROUND_COLOR_IT_S_RED' => "it's red",
+                'CONTENT_COLUMNS_2' => '2',
+            ],
+            self::constants(['content' => self::object([
+                'background-color' => self::select(['darkBlue', 'light-gray', "it's red"]),
+                'columns' => ['type' => 'string', 'enum' => ['2']],
+            ])])
+        );
+    }
+
+    /**
+     * The value must be the literal the field is typed with, so a number listed in a string enum
+     * becomes a string constant, the same way it becomes a string literal in the type.
+     */
+    public function testANumericMemberOfAStringEnumIsAString(): void
+    {
+        $constants = self::plan(['content' => self::object([
+            'columns' => ['type' => 'string', 'enum' => [1, 2]],
+        ])]);
+
+        $this->assertSame(['1', '2'], array_map(static fn (ConstantDef $c): string|array => $c->value, $constants));
+    }
+
+    /**
+     * @return array<string, array{array<string, mixed>}>
+     */
+    public static function fieldsWithoutOptions(): array
+    {
+        return [
+            'plain string' => [['type' => 'string']],
+            // Typed `int`, not as a union of literals.
+            'integer enum' => [['type' => 'integer', 'enum' => [1, 2]]],
+            // The whole enum falls back to `string`.
+            'enum with an object member' => [['type' => 'string', 'enum' => ['a', ['nested' => true]]]],
+            'enum with a newline' => [['type' => 'string', 'enum' => ["a\nb", 'c']]],
+            'enum with a comment terminator' => [['type' => 'string', 'enum' => ['a */ b', 'c']]],
+            'enum of only null' => [['type' => 'string', 'nullable' => true, 'enum' => [null]]],
+            'empty enum' => [['type' => 'string', 'enum' => []]],
+            // The type comes from the reference or the union, not from the enum next to it.
+            'enum beside a $ref' => [['$ref' => '#/components/schemas/Other', 'enum' => ['a']]],
+            'enum beside oneOf' => [['oneOf' => [['type' => 'string']], 'enum' => ['a']]],
+            // An untyped node with properties is typed `mixed`, so its `value` is never looked at.
+            'untyped select' => [['properties' => ['value' => ['type' => 'string', 'enum' => ['a']]]]],
+            'select with an integer value' => [[
+                'type' => 'object',
+                'properties' => ['value' => ['type' => 'integer', 'enum' => [1, 2]]],
+            ]],
+            // Options are only looked for on the field and on a select's `value`, nowhere deeper.
+            'enum nested deeper' => [[
+                'type' => 'object',
+                'properties' => ['inner' => ['type' => 'object', 'properties' => [
+                    'value' => ['type' => 'string', 'enum' => ['a']],
+                ]]],
+            ]],
+            'not a schema' => [['type' => 'object', 'properties' => ['value' => 'a']]],
+        ];
+    }
+
+    /**
+     * @param array<string, mixed> $field
+     */
+    #[DataProvider('fieldsWithoutOptions')]
+    public function testAFieldWithoutAFixedSetOfOptionsGetsNoConstants(array $field): void
+    {
+        $warnings = new Warnings();
+
+        $this->assertSame([], self::plan(['content' => self::object(['field' => $field])], $warnings));
+        $this->assertTrue($warnings->isEmpty());
+    }
+
+    public function testAnObjectWithoutPropertiesGetsNoConstants(): void
+    {
+        $this->assertSame([], self::plan(['content' => ['type' => 'object'], 'config' => []]));
+    }
+
+    /**
+     * Neither option gets the name: numbering one of them would silently hand the name to another
+     * option once an editor adds one in Flyo.
+     */
+    public function testOptionsThatWantTheSameNameGetNone(): void
+    {
+        $warnings = new Warnings();
+
+        $this->assertSame(
+            ['CONTENT_SIZE_LARGE' => 'large'],
+            self::constants(['content' => self::object([
+                'size' => self::select(['Small', 'small', 'large', null]),
+            ])], $warnings)
+        );
+        $this->assertSame(
+            ['BlockCard: CONTENT_SIZE_SMALL would stand for more than one option (content.size "Small", '
+                . 'content.size "small"), so it is not generated. Rename one of the options in Flyo to '
+                . 'remove the ambiguity.'],
+            $warnings->all()
+        );
+    }
+
+    public function testFieldsWhoseOptionsWantTheSameNameGetNone(): void
+    {
+        $warnings = new Warnings();
+
+        $this->assertSame(
+            ['CONTENT_SIZE_LARGE' => 'large'],
+            self::constants(['content' => self::object([
+                'size' => self::select(['small_wide', 'large']),
+                'size_small' => self::select(['wide']),
+            ])], $warnings)
+        );
+        $this->assertStringContainsString(
+            'CONTENT_SIZE_SMALL_WIDE would stand for more than one option (content.size "small_wide", '
+                . 'content.size_small "wide")',
+            implode("\n", $warnings->all())
+        );
+    }
+
+    /**
+     * Two spellings of one field name with the same option still mean the same string, so the one
+     * constant is right for both.
+     */
+    public function testTheSameOptionUnderTheSameNameIsNoCollision(): void
+    {
+        $warnings = new Warnings();
+
+        $this->assertSame(
+            ['CONTENT_FONT_SIZE_SMALL' => 'small'],
+            self::constants(['content' => self::object([
+                'font-size' => ['type' => 'string', 'enum' => ['small']],
+                'font_size' => ['type' => 'string', 'enum' => ['small']],
+            ])], $warnings)
+        );
+        $this->assertTrue($warnings->isEmpty());
+    }
+
+    public function testAnOptionWithNothingToNameItAfterIsSkippedWithAWarning(): void
+    {
+        $warnings = new Warnings();
+
+        $this->assertSame(
+            ['CONTENT_SIZE_LARGE' => 'large'],
+            self::constants(['content' => self::object(['size' => self::select(['', '--', 'large'])])], $warnings)
+        );
+        $this->assertSame(
+            [
+                'BlockCard.content.size: the option "" has no letter or digit to name a constant after, '
+                    . 'so it gets none.',
+                'BlockCard.content.size: the option "--" has no letter or digit to name a constant after, '
+                    . 'so it gets none.',
+            ],
+            $warnings->all()
+        );
+    }
+
+    public function testAFieldWithNothingToNameItAfterIsSkippedWithAWarning(): void
+    {
+        $warnings = new Warnings();
+
+        $this->assertSame(
+            [],
+            self::constants(['content' => self::object(['--' => self::select(['a', 'b'])])], $warnings)
+        );
+        $this->assertSame(
+            ['BlockCard.content.--: the field name has no letter or digit to name constants after, so its '
+                . 'options get none.'],
+            $warnings->all()
+        );
+    }
+
+    /**
+     * The options of one field are rendered as one block, so each carries the field as its group.
+     */
+    public function testConstantsAreGroupedByFieldInDocumentOrder(): void
+    {
+        $constants = self::plan([
+            'content' => self::object([
+                'size' => self::select(['small', 'large']),
+                'align' => ['enum' => ['left']],
+            ]),
+            'config' => self::object(['size' => self::select(['small'])]),
+        ]);
+
+        $this->assertSame(
+            [
+                ['CONTENT_SIZE_SMALL', 'content.size'],
+                ['CONTENT_SIZE_LARGE', 'content.size'],
+                ['CONTENT_ALIGN_LEFT', 'content.align'],
+                ['CONFIG_SIZE_SMALL', 'config.size'],
+            ],
+            array_map(static fn (ConstantDef $c): array => [$c->name, $c->group], $constants)
+        );
+    }
+
+    /**
+     * @param array<string, array<string, mixed>> $objects
+     * @return list<ConstantDef>
+     */
+    private static function plan(array $objects, ?Warnings $warnings = null): array
+    {
+        return EnumConstants::plan('BlockCard', $objects, $warnings ?? new Warnings());
+    }
+
+    /**
+     * @param array<string, array<string, mixed>> $objects
+     * @return array<string, string|list<string>> name => value
+     */
+    private static function constants(array $objects, ?Warnings $warnings = null): array
+    {
+        $constants = [];
+        foreach (self::plan($objects, $warnings) as $constant) {
+            $constants[$constant->name] = $constant->value;
+        }
+
+        return $constants;
+    }
+
+    /**
+     * @param array<string, mixed> $fields
+     * @return array<string, mixed>
+     */
+    private static function object(array $fields): array
+    {
+        return ['type' => 'object', 'properties' => $fields];
+    }
+
+    /**
+     * A select field, the way the server describes one.
+     *
+     * @param list<string|null> $options
+     * @return array<string, mixed>
+     */
+    private static function select(array $options): array
+    {
+        return [
+            'type' => 'object',
+            'required' => ['value', 'options', 'label'],
+            'properties' => [
+                'value' => ['type' => 'string', 'nullable' => true, 'enum' => $options],
+                'options' => [
+                    'oneOf' => [
+                        ['type' => 'object', 'additionalProperties' => ['type' => 'string']],
+                        ['type' => 'array', 'maxItems' => 0, 'items' => []],
+                    ],
+                ],
+                'label' => ['type' => 'string', 'nullable' => true],
+            ],
+        ];
+    }
+}
diff --git a/test/Generator/FixtureTrait.php b/test/Generator/FixtureTrait.php
index 41c934d..10de8c6 100644
--- a/test/Generator/FixtureTrait.php
+++ b/test/Generator/FixtureTrait.php
@@ -31,6 +31,7 @@ trait FixtureTrait
         'blocks/full' => ['Fixture\Full', 'blocks'],
         'blocks/collisions' => ['Fixture\Collisions', 'blocks'],
         'types/site' => ['Fixture\Site', 'types'],
+        'types/enums' => ['Fixture\Enums', 'types'],
     ];
 
     /**
diff --git a/test/Generator/GoldenTest.php b/test/Generator/GoldenTest.php
index 2681cc3..6b81265 100644
--- a/test/Generator/GoldenTest.php
+++ b/test/Generator/GoldenTest.php
@@ -183,6 +183,49 @@ public function testABlockClassIsTheSameUnderBothCommands(): void
         );
     }
 
+    /**
+     * The enum constants came after flyo-generate-blocks was deprecated, and its output stays as it
+     * was. Apart from them, a block with options is the same class under both commands.
+     */
+    public function testOnlyTheTypesCommandGeneratesEnumConstants(): void
+    {
+        $raw = self::loadDocument('types/enums');
+
+        $legacy = self::renderAll($raw, 'App\Blocks', 'blocks')['BlockCard.php'];
+        $types = self::renderAll($raw, 'App', 'types')['Blocks/BlockCard.php'];
+
+        $this->assertStringNotContainsString('public const CONTENT_', $legacy);
+        $this->assertStringNotContainsString('public const CONFIG_', $legacy);
+        $this->assertStringContainsString("    public const CONTENT_SIZE_SMALL = 'small';\n", $types);
+        $this->assertStringContainsString("    public const CONFIG_SIZE_SMALL = 'small';\n", $types);
+
+        $withoutEnumConstants = preg_replace('/\n(    public const CON(TENT|FIG)_\w+ = .+;\n)+/', '', $types);
+
+        $this->assertSame(
+            str_replace('vendor/bin/flyo-generate-blocks', 'vendor/bin/flyo-generate-types', $legacy),
+            $withoutEnumConstants
+        );
+    }
+
+    /**
+     * The options of one field are rendered as one block of constants, a blank line between fields.
+     */
+    public function testEnumConstantsAreGroupedByField(): void
+    {
+        $types = self::renderAll(self::loadDocument('types/enums'), 'App', 'types')['Blocks/BlockCard.php'];
+
+        $this->assertStringContainsString(
+            "    public const COMPONENT = 'Card';\n"
+                . "\n"
+                . "    public const CONTENT_SIZE_SMALL = 'small';\n"
+                . "    public const CONTENT_SIZE_MEDIUM = 'medium';\n"
+                . "    public const CONTENT_SIZE_LARGE = 'large';\n"
+                . "\n"
+                . "    public const CONTENT_ALIGN_LEFT = 'left';\n",
+            $types
+        );
+    }
+
     /**
      * A schema type added server-side after this release must be named, not skipped silently.
      */
diff --git a/test/Generator/NamingTest.php b/test/Generator/NamingTest.php
index 6f75345..cf5e817 100644
--- a/test/Generator/NamingTest.php
+++ b/test/Generator/NamingTest.php
@@ -176,6 +176,38 @@ public function testPrefixedKeyName(string $prefix, string $key, string $expecte
         $this->assertSame($expected, Naming::prefixedKeyName($prefix, $key));
     }
 
+    /**
+     * @return array<string, array{string, string}>
+     */
+    public static function constantSegments(): array
+    {
+        return [
+            'lowercase' => ['small', 'SMALL'],
+            'snake case' => ['background_color', 'BACKGROUND_COLOR'],
+            'kebab case' => ['background-color', 'BACKGROUND_COLOR'],
+            'camel case' => ['backgroundColor', 'BACKGROUND_COLOR'],
+            'spaced' => ['Extra Large', 'EXTRA_LARGE'],
+            'runs of separators' => ['a -- b__c', 'A_B_C'],
+            'leading and trailing separators' => ['_empty_', 'EMPTY'],
+            // A segment never starts a constant name, so a leading digit needs no prefix.
+            'only digits' => ['2', '2'],
+            'leading digit' => ['2col', '2COL'],
+            'already upper case' => ['XL', 'XL'],
+            'acronym is not split' => ['HTMLBlock', 'HTMLBLOCK'],
+            'apostrophe' => ["it's", 'IT_S'],
+            'umlaut' => ['grün', 'GRÜN'],
+            'accented camel case' => ['étéChaud', 'ÉTÉ_CHAUD'],
+            'empty' => ['', ''],
+            'punctuation only' => ['---', ''],
+        ];
+    }
+
+    #[DataProvider('constantSegments')]
+    public function testConstantSegment(string $raw, string $expected): void
+    {
+        $this->assertSame($expected, Naming::constantSegment($raw));
+    }
+
     public function testResolveNamesTheKindAndHowToFixItInTheCollisionWarning(): void
     {
         $warnings = new Warnings();
diff --git a/test/fixtures/types/enums/assertions.php b/test/fixtures/types/enums/assertions.php
new file mode 100644
index 0000000..5b72ae2
--- /dev/null
+++ b/test/fixtures/types/enums/assertions.php
@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Fixture\Enums;
+
+use Fixture\Enums\Blocks\BlockCard;
+
+/**
+ * Type assertions over the enum constants in ./expected.
+ *
+ * Analysed by phpstan-generated.neon at level 9, never executed. A `match` over a field is only
+ * exhaustive when its constants cover exactly the literals of the field's type, and a strict
+ * comparison against a value the field cannot hold is reported, so a constant that drifted from
+ * its field fails the build here.
+ */
+
+/** A select field's options are named after the field, without its `value`. */
+function contentSize(BlockCard $block): string
+{
+    return match ($block->getContent()->size->value) {
+        BlockCard::CONTENT_SIZE_SMALL => 'S',
+        BlockCard::CONTENT_SIZE_MEDIUM => 'M',
+        BlockCard::CONTENT_SIZE_LARGE => 'L',
+        null => '',
+    };
+}
+
+/** The same field name in config gets constants of its own, for its own options. */
+function configSize(BlockCard $block): string
+{
+    return match ($block->getConfig()->size->value) {
+        BlockCard::CONFIG_SIZE_SMALL => 'S',
+        BlockCard::CONFIG_SIZE_LARGE => 'L',
+        null => '',
+    };
+}
+
+/** A field with an `enum` of its own. */
+function contentAlign(BlockCard $block): string
+{
+    return match ($block->getContent()->align) {
+        BlockCard::CONTENT_ALIGN_LEFT => 'text-left',
+        BlockCard::CONTENT_ALIGN_CENTER => 'text-center',
+        BlockCard::CONTENT_ALIGN_RIGHT => 'text-right',
+        null => '',
+    };
+}
+
+/** Kebab-case field and camelCase option alike end up as upper snake case. */
+function contentIsDarkBlue(BlockCard $block): bool
+{
+    $value = $block->getContent()->{'background-color'}?->value;
+
+    return $value === BlockCard::CONTENT_BACKGROUND_COLOR_DARK_BLUE;
+}
+
+/** A numeric option keeps its string value, the literal the field is typed with. */
+function contentColumns(BlockCard $block): int
+{
+    return match ($block->getContent()->columns) {
+        BlockCard::CONTENT_COLUMNS_1 => 1,
+        BlockCard::CONTENT_COLUMNS_2 => 2,
+        BlockCard::CONTENT_COLUMNS_3 => 3,
+        null => 0,
+    };
+}
+
+/** A constant's type is its literal, not just `string`. */
+function constantIsALiteral(): string
+{
+    $small = BlockCard::CONTENT_SIZE_SMALL;
+
+    return match ($small) {
+        'small' => $small,
+    };
+}
diff --git a/test/fixtures/types/enums/expected/Blocks/BlockCard.php b/test/fixtures/types/enums/expected/Blocks/BlockCard.php
new file mode 100644
index 0000000..19634bb
--- /dev/null
+++ b/test/fixtures/types/enums/expected/Blocks/BlockCard.php
@@ -0,0 +1,124 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Fixture\Enums\Blocks;
+
+/**
+ * Card
+ *
+ * Block definition "card" (component: Card).
+ *
+ * Documentation-only type: at runtime a block is always a \Flyo\Model\Block, and the values these
+ * getters return are plain \stdClass objects. Annotate a variable with @var; do not instantiate
+ * this class.
+ *
+ * @generated by flyo/nitro-php - do not edit; regenerate with `vendor/bin/flyo-generate-types`.
+ */
+class BlockCard extends \Flyo\Model\Block
+{
+    public const IDENTIFIER = 'card';
+
+    public const COMPONENT = 'Card';
+
+    public const CONTENT_SIZE_SMALL = 'small';
+    public const CONTENT_SIZE_MEDIUM = 'medium';
+    public const CONTENT_SIZE_LARGE = 'large';
+
+    public const CONTENT_ALIGN_LEFT = 'left';
+    public const CONTENT_ALIGN_CENTER = 'center';
+    public const CONTENT_ALIGN_RIGHT = 'right';
+
+    public const CONTENT_BACKGROUND_COLOR_DARK_BLUE = 'darkBlue';
+    public const CONTENT_BACKGROUND_COLOR_LIGHT_GRAY = 'light-gray';
+
+    public const CONTENT_COLUMNS_1 = '1';
+    public const CONTENT_COLUMNS_2 = '2';
+    public const CONTENT_COLUMNS_3 = '3';
+
+    public const CONFIG_SIZE_SMALL = 'small';
+    public const CONFIG_SIZE_LARGE = 'large';
+
+    /**
+     * Block content fields.
+     *
+     * @return object{
+     *     title: string|null,
+     *     size: object{
+     *         value: 'small'|'medium'|'large'|null,
+     *         options: \stdClass|array{},
+     *         label: string|null
+     *     },
+     *     align: 'left'|'center'|'right'|null,
+     *     'background-color': object{
+     *         value: 'darkBlue'|'light-gray'|null,
+     *         options: \stdClass|array{},
+     *         label: string|null
+     *     }|null,
+     *     columns: '1'|'2'|'3'|null,
+     *     priority: int|null,
+     *     _empty: bool|null
+     * }
+     */
+    public function getContent()
+    {
+        /**
+         * @var object{
+         *     title: string|null,
+         *     size: object{
+         *         value: 'small'|'medium'|'large'|null,
+         *         options: \stdClass|array{},
+         *         label: string|null
+         *     },
+         *     align: 'left'|'center'|'right'|null,
+         *     'background-color': object{
+         *         value: 'darkBlue'|'light-gray'|null,
+         *         options: \stdClass|array{},
+         *         label: string|null
+         *     }|null,
+         *     columns: '1'|'2'|'3'|null,
+         *     priority: int|null,
+         *     _empty: bool|null
+         * }
+         */
+        return parent::getContent();
+    }
+
+    /**
+     * Block configuration fields.
+     *
+     * @return object{
+     *     size: object{
+     *         value: 'small'|'large'|null,
+     *         options: \stdClass|array{},
+     *         label: string|null
+     *     },
+     *     _empty: bool|null
+     * }
+     */
+    public function getConfig()
+    {
+        /**
+         * @var object{
+         *     size: object{
+         *         value: 'small'|'large'|null,
+         *         options: \stdClass|array{},
+         *         label: string|null
+         *     },
+         *     _empty: bool|null
+         * }
+         */
+        return parent::getConfig();
+    }
+
+    /**
+     * Iterated content pool items mapped to block fields.
+     *
+     * @return array<int, object{title: string|null}>
+     */
+    public function getItems()
+    {
+        /** @var array<int, object{title: string|null}> */
+        return parent::getItems();
+    }
+}
diff --git a/test/fixtures/types/enums/openapi.json b/test/fixtures/types/enums/openapi.json
new file mode 100644
index 0000000..5b14365
--- /dev/null
+++ b/test/fixtures/types/enums/openapi.json
@@ -0,0 +1,96 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Flyo Nitro - Enum constants",
+    "description": "A block whose content and config fields have fixed options, for the enum constants.",
+    "version": "edge"
+  },
+  "paths": {},
+  "components": {
+    "schemas": {
+      "BlockCard": {
+        "title": "Card",
+        "type": "object",
+        "description": "Block definition \"card\" (component: Card).",
+        "required": ["identifier", "uid", "component", "content", "config", "items", "slots"],
+        "properties": {
+          "identifier": { "enum": ["card"], "type": "string" },
+          "uid": { "type": "string" },
+          "component": { "enum": ["Card"], "type": "string" },
+          "content": {
+            "type": "object",
+            "description": "Block content fields.",
+            "required": ["size"],
+            "properties": {
+              "title": { "type": "string" },
+              "size": {
+                "type": "object",
+                "required": ["value", "options", "label"],
+                "properties": {
+                  "value": { "enum": ["small", "medium", "large", null], "type": "string", "nullable": true },
+                  "options": {
+                    "oneOf": [
+                      { "type": "object", "additionalProperties": { "type": "string" } },
+                      { "maxItems": 0, "type": "array", "items": {} }
+                    ]
+                  },
+                  "label": { "type": "string", "nullable": true }
+                }
+              },
+              "align": { "enum": ["left", "center", "right"], "type": "string" },
+              "background-color": {
+                "type": "object",
+                "required": ["value", "options", "label"],
+                "properties": {
+                  "value": { "enum": ["darkBlue", "light-gray", null], "type": "string", "nullable": true },
+                  "options": {
+                    "oneOf": [
+                      { "type": "object", "additionalProperties": { "type": "string" } },
+                      { "maxItems": 0, "type": "array", "items": {} }
+                    ]
+                  },
+                  "label": { "type": "string", "nullable": true }
+                }
+              },
+              "columns": { "enum": ["1", "2", "3"], "type": "string" },
+              "priority": { "enum": [1, 2, 3], "type": "integer" },
+              "_empty": { "type": "boolean" }
+            }
+          },
+          "config": {
+            "type": "object",
+            "description": "Block configuration fields.",
+            "required": ["size"],
+            "properties": {
+              "size": {
+                "type": "object",
+                "required": ["value", "options", "label"],
+                "properties": {
+                  "value": { "enum": ["small", "large", null], "type": "string", "nullable": true },
+                  "options": {
+                    "oneOf": [
+                      { "type": "object", "additionalProperties": { "type": "string" } },
+                      { "maxItems": 0, "type": "array", "items": {} }
+                    ]
+                  },
+                  "label": { "type": "string", "nullable": true }
+                }
+              },
+              "_empty": { "type": "boolean" }
+            }
+          },
+          "items": {
+            "type": "array",
+            "description": "Iterated content pool items mapped to block fields.",
+            "items": { "type": "object", "properties": { "title": { "type": "string" } } }
+          },
+          "slots": {
+            "type": "object",
+            "properties": { "_empty": { "type": "boolean" } }
+          }
+        },
+        "x-schema-type": "block"
+      }
+    }
+  }
+}

From e8070fd81e7941b821dc7d96ea05ca341964012e Mon Sep 17 00:00:00 2001
From: nadar <git@nadar.io>
Date: Mon, 12 Oct 2026 14:58:08 +0300
Subject: [PATCH 3/4] test(generator): cover enumMembers() and hostile options,
 document the constants

The remaining files of the previous commit: TypeMapperTest gains the
`*/` case and a direct test of enumMembers(), DegenerateSchemaTest
checks that quotes, backslashes, `?>`, `$`, tabs and umlauts in options
still render valid constants, and that an option with `*/` falls back
to `string` without constants. README and UPGRADE describe both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SjJHX6UBVjHdxaoMgHLZYC
---
 README.md                               | 28 ++++++++++++++-
 UPGRADE.md                              | 40 +++++++++++++++++++++-
 test/Generator/DegenerateSchemaTest.php | 45 +++++++++++++++++++++++++
 test/Generator/TypeMapperTest.php       | 21 ++++++++++++
 4 files changed, 132 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 8c37789..7344c00 100644
--- a/README.md
+++ b/README.md
@@ -160,7 +160,33 @@ match ($block->getIdentifier()) {
 };
 ```
 
-Each block class also carries `IDENTIFIER`, `COMPONENT` and `SLOTS` constants.
+Each block class also carries `IDENTIFIER`, `COMPONENT` and `SLOTS` constants, plus one constant
+per option of every content and config field that has a fixed set of them, named
+`CONTENT_<FIELD>_<OPTION>` and `CONFIG_<FIELD>_<OPTION>`:
+
+```php
+use App\Flyo\Blocks\BlockHero;
+
+/** @var BlockHero $block */
+$modifier = match ($block->getContent()->size->value) {
+    BlockHero::CONTENT_SIZE_SMALL => 'hero--small',       // 'small'
+    BlockHero::CONTENT_SIZE_MEDIUM => 'hero--medium',     // 'medium'
+    BlockHero::CONTENT_SIZE_LARGE => 'hero--large',       // 'large'
+    null => '',
+};
+
+if ($block->getConfig()->theme === BlockHero::CONFIG_THEME_DARK) {
+    // ...
+}
+```
+
+A select field's constants are named after the field, not after its `value`. Names are upper snake
+case: the field `background-color` with the option `darkBlue` gives
+`CONTENT_BACKGROUND_COLOR_DARK_BLUE`, whose value is `'darkBlue'`, the option exactly as Flyo lists
+it. PHPStan knows each constant's literal value, so it reports a `match` that misses an option. If
+two options would get the same name, neither gets a constant and the generator prints a warning, so
+a name never quietly starts to mean a different option. Only `flyo-generate-types` generates these
+constants; the deprecated `flyo-generate-blocks` does not.
 
 **Entities** narrow `getModel()`, the part of an entity response whose shape depends on its type:
 
diff --git a/UPGRADE.md b/UPGRADE.md
index 6610a34..d2fbf2f 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -1,5 +1,43 @@
 # Upgrade
 
+## From 3.7 to 3.8
+
+### Generated types: constants for field options
+
+`flyo-generate-types` gives every block class one constant per option of each content and config
+field that has a fixed set of them, select fields included. A constant is named
+`<CONTENT|CONFIG>_<FIELD>_<OPTION>` and holds the option exactly as Flyo lists it:
+
+```diff
+  class BlockHero extends \Flyo\Model\Block
+  {
+      public const IDENTIFIER = 'hero';
+
+      public const COMPONENT = 'Hero';
++
++     public const CONTENT_SIZE_SMALL = 'small';
++     public const CONTENT_SIZE_MEDIUM = 'medium';
++     public const CONTENT_SIZE_LARGE = 'large';
++
++     public const CONFIG_THEME_LIGHT = 'light';
++     public const CONFIG_THEME_DARK = 'dark';
+```
+
+If two options would get the same name (`Small` and `small`), neither gets a constant and the
+generator prints a warning. Numbering them instead would let a name silently move to another option
+once one is added in Flyo.
+
+This changes the generated file of every block with such a field, so `--check` reports them as out
+of date until you regenerate once. The deprecated `flyo-generate-blocks` does not generate the
+constants, and its output stays as it was.
+
+### Generated types: an option containing `*/`
+
+An option whose value contains `*/` closed the docblock the field's type is written into, so the
+generated file did not parse. Such a field is now typed `string`, like a field with an option that
+spans lines, and gets no constants. This applies to both commands, but only changes files that were
+broken before.
+
 ## From 3.6 to 3.7
 
 ### Generated types: select fields keep their values
@@ -250,4 +288,4 @@ $routes['_empty']; // bool: true when no route could be resolved
 $routes['detail']; // string: "/foo-bar"
 ```
 
-If you type-hinted against `\Flyo\Model\Routes`, replace it with `array`.
+If you type-hinted against `\Flyo\Model\Routes`, replace it with `array`.
\ No newline at end of file
diff --git a/test/Generator/DegenerateSchemaTest.php b/test/Generator/DegenerateSchemaTest.php
index 10755af..3c45598 100644
--- a/test/Generator/DegenerateSchemaTest.php
+++ b/test/Generator/DegenerateSchemaTest.php
@@ -197,6 +197,51 @@ public function testANumericPropertyKeyIsHandled(): void
         $this->assertStringContainsString("'2024': string|null", $source['Blocks/BlockNumeric.php']);
     }
 
+    /**
+     * Options are author-supplied free text, and each one lands in a string literal of its own.
+     */
+    public function testHostileOptionsBecomeValidConstants(): void
+    {
+        $source = self::render([
+            'BlockHostile' => [
+                'type' => 'object',
+                'x-schema-type' => 'block',
+                'properties' => [
+                    'component' => ['enum' => ['Hostile'], 'type' => 'string'],
+                    'content' => [
+                        'type' => 'object',
+                        'properties' => [
+                            '2024' => [
+                                'type' => 'string',
+                                'enum' => ["it's", 'back\\slash', 'a ?> b', '$d', "e\tf", 'ü'],
+                            ],
+                            // The type is a docblock, so this enum is typed `string` instead.
+                            'closing' => ['type' => 'string', 'enum' => ['*/ echo 1; /*', 'plain']],
+                        ],
+                    ],
+                ],
+            ],
+        ]);
+
+        $rendered = $source['Blocks/BlockHostile.php'];
+
+        self::assertValidPhp($rendered);
+
+        foreach ([
+            "CONTENT_2024_IT_S = 'it\\'s';",
+            "CONTENT_2024_BACK_SLASH = 'back\\\\slash';",
+            "CONTENT_2024_A_B = 'a ?> b';",
+            "CONTENT_2024_D = '\$d';",
+            "CONTENT_2024_E_F = 'e\tf';",
+            "CONTENT_2024_Ü = 'ü';",
+        ] as $constant) {
+            $this->assertStringContainsString('    public const ' . $constant . "\n", $rendered);
+        }
+
+        $this->assertStringContainsString('closing: string|null', $rendered);
+        $this->assertStringNotContainsString('CONTENT_CLOSING_', $rendered);
+    }
+
     // -- entities ----------------------------------------------------------------------------
 
     public function testAnEntityWithNoPropertiesIsAnOpaqueObject(): void
diff --git a/test/Generator/TypeMapperTest.php b/test/Generator/TypeMapperTest.php
index 2a331f9..6ada2cb 100644
--- a/test/Generator/TypeMapperTest.php
+++ b/test/Generator/TypeMapperTest.php
@@ -49,6 +49,11 @@ public static function types(): array
                 ['type' => 'string', 'enum' => ["a\nb"]],
                 'string',
             ],
+            // `*/` would close the docblock the type is written into.
+            'enum with a comment terminator falls back to string' => [
+                ['type' => 'string', 'enum' => ['a */ b', 'c']],
+                'string',
+            ],
             // OpenAPI 3.0 needs `null` listed for a nullable enum to accept it.
             'nullable enum keeps its literals' => [
                 ['type' => 'string', 'nullable' => true, 'enum' => ['red', 'green', null]],
@@ -236,6 +241,22 @@ public function testANullableEnumIsNotSuffixedWithNullTwice(): void
         );
     }
 
+    /**
+     * The strings the literal union is made of, which the enum constants are named after too.
+     */
+    public function testEnumMembersAreTheStringsOfTheLiteralUnion(): void
+    {
+        $this->assertSame(
+            ['1', 'a', null, ''],
+            TypeMapper::enumMembers(['enum' => [1, 'a', null, '1', false, 'a']])
+        );
+        $this->assertSame([null], TypeMapper::enumMembers(['enum' => [null]]));
+        $this->assertNull(TypeMapper::enumMembers(['type' => 'string']));
+        $this->assertNull(TypeMapper::enumMembers(['enum' => []]));
+        $this->assertNull(TypeMapper::enumMembers(['enum' => ['a', ['nested' => true]]]));
+        $this->assertNull(TypeMapper::enumMembers(['enum' => ["a\nb"]]));
+    }
+
     public function testRequiredIsHonouredInsideAShape(): void
     {
         $type = self::mapper()->type([

From 3fa2aac90633d2b3c885e5f37daaa4d5394e891f Mon Sep 17 00:00:00 2001
From: nadar <git@nadar.io>
Date: Mon, 12 Oct 2026 14:59:08 +0300
Subject: [PATCH 4/4] docs: restore the final newline of UPGRADE.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SjJHX6UBVjHdxaoMgHLZYC
---
 UPGRADE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/UPGRADE.md b/UPGRADE.md
index d2fbf2f..cab8a9f 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -288,4 +288,4 @@ $routes['_empty']; // bool: true when no route could be resolved
 $routes['detail']; // string: "/foo-bar"
 ```
 
-If you type-hinted against `\Flyo\Model\Routes`, replace it with `array`.
\ No newline at end of file
+If you type-hinted against `\Flyo\Model\Routes`, replace it with `array`.