Ddm Bundle Laravel Package

Getting Started

This is a Symfony bundle (jbsnewmedia/ddm-bundle), so "getting started" depends on your stack: in Symfony, register the bundle and start consuming services; in a Laravel codebase you'd typically only borrow the field/value/validator concepts, since the bundle itself is not a Laravel package.

Minimal steps:

1. Install with Composer alongside your framework's DI container and Twig (or your templating equivalent).
2. Register the bundle in config/bundles.php and confirm the service definitions are loaded.
3. Look first at the new contracts: DDMFieldInterface and DDMValueInterface. These are the intended extension points as of 1.1.0; anything else in Field/Value should be treated as internal.
4. Review the validator set (Email, Required, String, Unique) under the validators namespace to see how validation is wired and how messages are translated.
5. Inspect the shipped Twig templates to understand the field/form rendering contract before overriding anything.

First real use case: define a datatable/form backed by Doctrine, attach fields (text, email, etc.) to a form definition, run the validator chain on submit, and render with the bundled templates. Then extend the search with the new extended-search handler to add filtering beyond a single basic query string.

Implementation Patterns

Custom fields via the interface. Implement DDMFieldInterface on your own field classes and register them as services (autowire + tag, or explicit service definition). This is now the sanctioned path; it keeps you insulated from future internal refactors.

Custom values via the interface. DDMValueInterface formalises what a value handler must expose. Use it when a field needs bespoke value normalisation (e.g. money, date ranges, arrays of IDs) rather than stretching a scalar field to do non-scalar work.

Extended search. The datatable search handler now has an extended-search path. Pattern: keep the basic search for free-text, and add explicit filter criteria through the extended handler, translating request parameters into query-builder predicates. This is the right place for date ranges, multi-select filters, and relation-based filtering — not inside field classes.

Validation composition. Treat validators as a chain configured per field: Required → String/Email → domain-specific (Unique). Keep custom rules as their own validator classes so they compose and so translation keys stay per-rule rather than per-field.

Translation wiring. With symfony/translation-contracts now a first-class dependency, pass a translator into validators/datatable messages rather than hard-coding strings. Ship your own translations/validators.*.xlf (or YAML) under the expected domain so overrides work without patching vendor code.

Template overrides. Override only the specific template you need, under the bundle's documented override path. Since vorname.html.twig was removed in 1.1.0, any form configuration or include still pointing at it needs to be repointed at the current template set.

DI in tests. The expanded PHPUnit coverage around DI and Doctrine is a useful reference: mirror those patterns (container boot, service retrieval, Doctrine entity setup) when writing your own integration tests for custom fields.

Gotchas and Tips

• Contract alignment is the main upgrade risk. The release is described as backward compatible for typical consumers, but custom implementations touching field/value/validator internals may break. Before upgrading, grep your code for classes implementing or extending field/value/validator internals and check method signatures against DDMFieldInterface and DDMValueInterface.
• Removed template. vorname.html.twig is gone. Any form_theme, include, or template configuration referencing it will fail at render time — this surfaces late, so search templates and form type config proactively.
• Unique validator needs context. It typically requires Doctrine/entity metadata to build its lookup query. If it silently passes or throws in tests, check that the entity manager and mapping are available in that container/test scope; the new test coverage is a good template for reproducing the correct setup.
• Non-scalar input handling. The release explicitly hardens object/array inputs. If you previously relied on loose coercion, validate that array and object values still reach your value handlers in the shape you expect; prefer explicit value classes over implicit casting.
• Translation domain drift. Validator messages now come through the translation contracts. If messages render as raw keys, you're missing the domain registration or the locale file — check the configured translation domain rather than assuming the bundle's defaults.
• Extended search ordering. Decide explicitly whether basic and extended search combine with AND or OR; that choice belongs in the search handler, not scattered across field definitions, or filters will behave inconsistently per datatable.
• Debugging aids. Use the container debug command to confirm your custom field/value services are registered and tagged, and dump the built query from the search handler when filters appear to be ignored.
• Housekeeping. The .idea/modules.xml removal is irrelevant to consumers, but it's a reminder to keep IDE-local files out of your own package/bundle repos so downstream diffs stay clean.
• Extension strategy. Prefer implementing the interfaces over extending concrete classes; the 1.1.0 refactorings show internals are still moving, while the contracts are the stabilised surface.