Easy Admin Enum Field Bundle Laravel Package

Getting Started

• Install with composer require tourze/easy-admin-enum-field-bundle:^1.0.0. The -bundle suffix and easy-admin namespace mean this is built around EasyAdmin (a Symfony bundle), not a native Laravel package — plan for that mismatch before writing code (see Gotchas).
• Read the source first, in this order: src/*Field.php (the field type you’ll actually wire up), src/DependencyInjection/ (how the bundle registers services), then src/Resources/ (form themes / templates, if any). The repository has no README-level documentation for 1.0.0, so source is your spec.
• Your first end-to-end use case: take a PHP backed enum such as:

  enum Status: string {
      case Draft = 'draft';
      case Published = 'published';
  }
  

  and wire it into an admin form field so the enum cases become the selectable options, and rendered values in list/detail views resolve to a human label instead of the raw draft string.
• If you are hosting this from Laravel: confirm whether your app is actually using Tourze/EasyAdmin at all. If it isn’t, stop here — this bundle won’t help a stock Laravel Nova/Filament/resource setup, and you’re cheaper building an enum cast + a Rule::enum() validator yourself.

Implementation Patterns

• Declare the field once per enum, reuse everywhere. Point the field at the enum FQCN (e.g. Status::class) and let the bundle derive choices from cases(). This keeps choice lists in sync as you add enum cases — the main reason to use the bundle over hand-written ['draft' => 'Draft', ...] arrays.
• Backed enums for persistence, pure enums for ephemeral UI. Use string/int backed enums as the field’s value type so form submits map cleanly to ::from(). Pure enums are fine for radio/filter widgets but require explicit mapping back to storage.
• Use it in three surfaces consistently: the entity/form field, the index/list column formatter, and any filter. An enum field that renders nicely in the form but shows raw draft in the list is the most common complaint in bundles of this shape — verify each surface after wiring.
• Customise labels at the enum, not the admin config. Prefer a label method/interface on the enum (e.g. label(): string) so translation and labels travel with the enum and remain reusable outside EasyAdmin. Fall back to title-casing the case name only for quick prototypes.
• Translate via the existing translator. If the field pulls from Symfony’s translator, put keys like enum.status.draft in your translation catalogue; do not hardcode English in admin YAML.
• Compose with standard admin field options (required, help, empty_data) rather than fighting the enum field — treat it as a normal ChoiceType-like field for everything except the choice source.

Gotchas and Tips

• Framework mismatch is the big one. This is a Symfony bundle; there is no Laravel auto-discovery ServiceProvider in a -bundle package. A Laravel developer can only “leverage it day-to-day” if the host application runs Tourze/EasyAdmin. Budget time for an adapter layer or choose a native Laravel equivalent.
• Sparse 1.0.0 release notes. The only artefact is a changelog link (/commits/1.0.0) — no migration notes, no BC statement. Treat 1.0.0 as “initial public shape” and pin the exact version in composer.json (1.0.0, not ^1.0) until you’ve diffed 1.0.1 yourself. Read the source at the pinned tag; don’t trust docs that may not exist.
• Nullable vs required enums. A null/empty choice is not a case. Confirm how the field handles empty_data and null on submit — otherwise you’ll get ValueError: "" is not a valid backing value from Enum::from() instead of a validation message.
• Value casting on hydrate. If list/detail shows the raw case name, the field is probably calling (string) on an enum instance or skipping the formatter. Check whether it expects a backed value or the case object and adjust your entity getter/type cast accordingly.
• Enum case naming edge cases. Hyphenated or all-caps cases (e.g. case IN_PROGRESS) produce ugly auto-labels and translation keys — override labels explicitly rather than relying on the default transformer.
• Debugging checklist: dump the resolved cases() array; confirm the enum FQCN string passed matches the imported class (namespace typos silently yield an empty field in some implementations); check the form theme is loaded if options render unstyled.
• Extension points to look for: a bundle extension/config node for default label strategy and a template override hook for rendering. If neither exists in 1.0.0, subclass the field class in your app rather than editing vendor code.