Polyfill Form Dti Laravel Package

Getting Started

This is a Symfony Form polyfill, not a Laravel package, so the first decision is whether you need Symfony's Form component at all. In a normal Laravel app you don't — you'll be using FormRequest, $casts, and Carbon. Only reach for this if you're running Symfony Form standalone (legacy code, shared form definitions, or a Symfony package you're consuming from Laravel) on a Symfony version older than 4.3.

1. Install:

   composer require ruwork/polyfill-form-dti
   

2. Look first at:
   • composer.json — as of 0.2.1 the Symfony constraint is relaxed to >=4.1 with no upper-conflict pin, so it will now resolve against modern symfony/form. That does not mean it's needed there; it just means Composer won't stop you.
   • src/ — the actual form type extension(s). There is very little code here; read all of it before debugging. Check whether it implements getExtendedType() or getExtendedTypes().
   • The README for how the extension is meant to be registered.
3. First use case: take an existing DateTimeType field and ask it to return an immutable object:

   $builder->add('publishedAt', DateTimeType::class, [
       'input' => 'datetime_immutable',
   ]);
   

   Without the extension registered, Symfony throws an "invalid input" style error or silently returns a mutable \DateTime. After registration, $form->get('publishedAt')->getData() is a \DateTimeImmutable.

If you're on Symfony >= 4.3, stop here — DateTimeImmutableType and input => 'datetime_immutable' are native. This package adds nothing.

Implementation Patterns

Register the extension. In a Symfony app this happens via form.type_extension DI tags. In a Laravel app (or any standalone Form usage), you must wire it manually — there's no autoconfiguration:

// e.g. inside a service provider's register()
$formFactory = $this->app->make(FormFactoryInterface::class);

// Class name comes from src/ — inspect it first.
$formFactory->addTypeExtension(new DateTimeImmutableTypeExtension());

Then any DateTimeType/DateType/TimeType in your form definitions can opt in via 'input' => 'datetime_immutable'.

Pair with the persistence layer consistently. The point of returning an immutable object is usually to store it with Doctrine's datetime_immutable DBAL type or, in Laravel, to bind it to a model cast:

protected $casts = [
    'published_at' => 'immutable_datetime',
];

If your field returns DateTimeImmutable but your cast/DBAL type expects mutable, you'll get type errors on save.

Model your domain properties as immutable. The natural workflow is: form type option → \DateTimeImmutable property → immutable DBAL type / cast. Don't mix — a DTO with a \DateTimeImmutable typed property will fatal if the extension isn't active and returns a mutable object.

When bridging into Laravel, register the extension once at boot and keep form-building code isolated in a small adapter layer. Don't scatter new DateTimeTypeExtension() calls around controllers.

Version-gate your registration, not your install. Since 0.2.1 will install on any Symfony >= 4.1, guard registration so the polyfill only runs where it's actually needed:

if (Kernel::VERSION_ID < 40300) {
    $formFactory->addTypeExtension(new DateTimeImmutableTypeExtension());
}

Gotchas and Tips

• This package is effectively obsolete. One maintenance release since 2018 — 0.2.1 only widens the Composer constraint; no code change. 1 star, 0 dependents. Symfony 4.3+ ships DateTimeImmutableType natively; do not add this to a new project.
• The old "constraints will bite" problem is gone — which is arguably worse. Before 0.2.1 the package could not be installed alongside modern symfony/form, which protected you from yourself. Now it installs cleanly on Symfony 4.1 through 6/7, so a composer require succeeding tells you nothing about whether the extension is compatible with that Symfony's Form internals.
• Extension API drift is now the live risk. 0.2.1 did not touch code. If src/ still implements getExtendedType() rather than getExtendedTypes(), it will emit deprecations or fail outright on Symfony 4.2+ — exactly the range the widened constraint now lets you install into. Verify src/ before trusting the install.
• Double-conversion on 4.3+. With the relaxed constraint you can end up with both the native immutable input support and this extension reacting to the same DateTimeType. Symptoms are hard to read (double transforms, timezone applied twice, or "already immutable" type surprises). If you're on 4.3+, remove the package rather than reason about the interaction.
• Registration is the #1 failure mode. Because the extension isn't autoconfigured in Laravel, "it returns a string" or "it returns mutable DateTime" almost always means the extension was never added to the FormFactory. Verify by dumping the resolved form config.
• Debugging the data flow. Date types use a transformer chain (DateTimeToArrayTransformer etc.). If you get unexpected types, dump $form->get('field')->getData() and getNormData() to see which transformer stage misbehaved. In Symfony apps, bin/console debug:form DateTimeType shows whether datetime_immutable is an accepted input value.
• Timezone options still apply. model_timezone / view_timezone are respected, but immutable conversions mean you can't mutate in place — call ->setTimezone() and use the returned object, or you'll silently work on a discarded clone.
• empty_data assumptions. Older form extension code often assumes a mutable object exists to mutate. Empty or invalid submissions can surface as "Call to a member function ... on bool/null" — check empty_data and required behavior when no value is submitted.
• Prefer the native path. On Symfony >= 4.3, replace the option with the built-in DateTimeImmutableType; on Laravel, use immutable_datetime casts and FormRequests. 0.2.1 removes an install-time obstacle but not the reason to avoid the package — it remains a last resort for legacy Symfony 3.x/4.0–4.2 applications only.