Download the PHP package survos/field-bundle without Composer

survos/field-bundle

Universal field/property metadata for Symfony — declare once, consume everywhere.

The problem

Property metadata is scattered across attributes with overlapping concerns:

None of them answer: how should this property be displayed and filtered in a grid, search panel, or UX-search widget?

The solution

#[Field] declares display and search behavior once, orthogonally to the other attributes:

Attribute lanes — no overlap

Installation

Attributes

The bundle provides five PHP attributes covering properties, entities, and controllers.

#[Field] — property / method level

Widget inference — when widget is null, FieldDescriptor::resolvedWidget() infers from PHP type:

Widget is only inferred when filterable: true. Non-filterable fields return null.

Browsability — Widget::Select and Widget::Boolean are "browsable" (render as selectable lists in ColumnControl / SearchBuilder / facet panels). Widget::Range, Widget::Date, and Widget::Text are filterable but not browsable — they render as input controls.

#[EntityMeta] — class level

Class-level metadata for admin UI, dashboard cards, and menu auto-registration.

Parameters:

Discovered at compile time by EntityMetaPass, which scans all Doctrine entity directories.

Twig globals — every #[EntityMeta] entity is exposed as a Twig global keyed by APP_ENTITY_{SHORTNAME} (upper-snake of short class name). Use this to avoid class strings in templates:

#[RouteIdentity] — class level

Declares how an entity identifies itself in URLs. This is fundamental to Survos navigation: entities generate their own route parameters with getRp(), controllers resolve typed entity arguments from those same parameters, and templates link with path('route_name', entity.rp).

This replaces the legacy UNIQUE_PARAMETERS const pattern from survos/core-bundle and avoids repeating #[MapEntity] mappings on every controller method.

Parameters:

RouteIdentityTrait implements getRp(), getUniqueIdentifiers(), and erp() for the entity. Pair with implements RouteParametersInterface from survos/core-bundle.

Navigation Contract

For every navigable Doctrine entity, use this pattern:

Then name the route parameter after the generated key. The default key is {lcfirst(shortClassName)}Id, so Image becomes imageId, Item becomes itemId, and GalleryImage becomes galleryImageId.

Templates should not rebuild route parameters manually:

For a custom route key, declare it on the entity and use that key in the route:

The entity is the single source of truth for route identity:

• entity.rp generates URL parameters.
• RouteIdentityValueResolver resolves controller arguments.
• Menus, labels, redirects, and templates all use the same contract.
• If the route parameter name does not match the identity key, typed entity resolution will not run.

Migration from old pattern:

#[RouteMeta] — method level

Metadata for individual controller actions. Powers sitemap generation, AI introspection, breadcrumbs, nav, and OpenAPI projection.

Key parameters:

#[ControllerMeta] — class level

Class-level defaults for #[RouteMeta]. Avoids repeating entity:, audience:, and tags: on every action.

RouteMetaPass merges class-level ControllerMeta defaults under each method's #[RouteMeta]. The method always wins for any field it sets explicitly; ControllerMeta fills the gaps.

FieldReader — reading descriptors at runtime

FieldReader is the main service for consuming #[Field] metadata programmatically. Inject it anywhere:

FieldDescriptor properties

Key methods:

Progressive enhancement sources

FieldReader enriches descriptors when optional packages are present:

Fallback synthesis — properties with no #[Field] but referenced in #[ApiFilter] or #[MeiliIndex] get a synthesized descriptor so the grid still shows them correctly. Add #[Field] to take explicit control.

Widget mapping across consumers

Zero required dependencies

#[Field] and Widget have no external dependencies — just PHP 8.4. FieldReader enhances output progressively based on what packages are installed.

Consumers

Further reading

• docs/CONTROLLERS.md — Survos controller naming convention: XxxController (entity) vs XxxListController (collection). Covers #[RouteMeta], #[ControllerMeta], #[RouteIdentity], entity injection, and testing patterns.