Form Extra Bundle Laravel Package

Getting Started

• Install the package via Composer and confirm Laravel auto-discovery picks up the service provider. If the package ships a config file, publish it first and review the default datetime format/timezone expectations.
• Start with the transformer class or facade that handles datetime conversion. The 1.0.1 release makes invalid datetime input fail loudly by throwing a transformation failure, so check the exception class shipped with the package before writing your first transformation.
• First use case: transform a datetime string from a request payload into a Carbon instance or a normalized string. Pass a known-good value first, then pass an invalid value such as "not-a-date" and observe the transformation failure. Wire that failure into your normal exception handling early so invalid input does not silently corrupt downstream data.

Implementation Patterns

• Use the datetime transformer at the boundary where untrusted input enters your application: form requests, DTO hydration, or API resource mapping. Let validation catch obvious format errors, and let the package’s transformation failure catch anything that slips through.
• Wrap transformations in a try/catch for the package’s transformation failure exception. Convert it into a ValidationException, a domain-specific exception, or a 422 response depending on context. This keeps invalid datetime handling consistent across HTTP, queue, and console entry points.
• Centralize accepted datetime formats and timezone handling in config or a small application-level factory. Avoid scattering Carbon::parse() calls alongside the package transformer; the transformer should be the single conversion path.
• For batch imports or queue jobs, catch the transformation failure per row/item and collect failures rather than aborting the whole batch. This is especially useful now that invalid values throw instead of passing through.
• Extend the package’s transformer or use its extension points when you need custom parsing rules, fallback values, or logging. Keep custom transformers small and test them against both valid and invalid datetime strings.
• Add tests for null, empty string, malformed strings, ambiguous formats, and timezone-offset inputs. The 1.0.1 behavior change is easiest to lock down with a dedicated invalid-datetime test case.

Gotchas and Tips

• The main 1.0.1 change is behavioral: invalid datetime values now throw a transformation failure. If you previously relied on invalid values being ignored, coerced, or passed through, audit those paths before upgrading.
• Catch the package’s specific transformation failure exception rather than a broad \Exception. That keeps real bugs visible while handling expected invalid-input cases.
• Watch for null and empty-string semantics. Decide explicitly whether they should be treated as missing values, transformed to null, or rejected. Do not assume the transformer treats them the same as malformed strings.
• Timezone assumptions are a common source of subtle bugs. Verify how the package handles values without an offset, values with an offset, and values that include a timezone name. Normalize to your application timezone after transformation if needed.
• If you see a transformation failure in logs, isolate the exact input and format. Reproduce it with the transformer directly before debugging the surrounding request or model layer.
• Use the package’s config and extension points for format lists and custom failure handling rather than forking the transformer. Keep the failure exception mapping in one place so future package updates are easier to absorb.