Laravel Vermicelli Starter Kit Laravel Package

Getting Started

• Install with composer require and immediately publish the package assets: php artisan vendor:publish --tag=config (and the views tag if you intend to override the input markup). The refactored DateInput/DateTimeInput components in v1.0.2 make re-publishing views important — stale published views are the most likely source of "it looks wrong after upgrade".
• Look first at the package config file, specifically the new locale/timezone keys, and cross-check against the README's date/time section. v1.0.2 introduces .env variables that drive display formatting, so the config file is now a thin wrapper over env — read both together.
• Confirm your config/app.php timezone is UTC (v1.0.2 aligns the package with a UTC app timezone). If your app is still on a local timezone, decide deliberately whether to migrate now or pin the package.
• First use case: a single form field. Drop <x-date-input> / <x-date-time-input> (or the equivalent facade/Blade directive) into a form, bind it, and verify the round trip — user types a local-looking date, it persists as UTC, and it re-renders in the user's timezone. Get that one field correct before rolling the components across the app.

Implementation Patterns

• Store UTC, display local. Treat the package's display timezone env var as presentation-only. Persist with Eloquent's datetime cast (which serialises to the app timezone) and convert at the boundary — never store a formatted local string.
• Centralise the conversion. Add a small helper or cast (e.g. a LocalDateTime cast, or an accessor using ->setTimezone(config('...display_timezone'))) rather than sprinkling ->tz() calls through Blade. When the package's env-driven display settings change, one place should need to change.
• Per-request locale/timezone override. For multi-tenant or per-user timezones, set the display timezone in middleware (config(['...display_timezone' => $user->timezone]) or App::setLocale(...)) before the request renders. This keeps the package's global defaults intact while respecting the current user.
• Validation stays in app timezone-agnostic form. Validate the raw input with date / date_format rules, then convert explicitly in a FormRequest prepareForValidation or a DTO. Don't rely on the component to hand you a normalised value — the v1.0.2 refactor may have changed what the request payload looks like.
• Livewire/Inertia integration. If the inputs are Livewire-bound, keep the bound property as a string in the display timezone and convert on save; binding a Carbon instance directly invites double conversion when the component re-renders.
• Testing. Use travelTo() / freezeTime() with an explicit timezone and assert both the stored UTC value and the rendered local value. Add at least one DST-boundary test (spring-forward and fall-back) per input type — this is where refactored date components typically break.

Gotchas and Tips

• The UTC default is the real breaking change. Any code that assumed now() matched the server's wall clock — scheduled tasks, "today" comparisons, report boundaries, existing rows written under a local-timezone app — will shift. Audit whereDate, whereBetween, and raw NOW() usages before deploying. Consider a one-off backfill if historical rows were written in local time.
• Clear cached config. New .env variables do nothing until php artisan config:clear (or a redeploy that rebuilds the cache). "The env var isn't working" is almost always this, followed by a typo'd key name.
• Avoid double conversion. The classic failure is storing a UTC-converted value and then converting again on read, producing a silent offset that only shows up for non-UTC users. Pick one conversion boundary and assert it in a test.
• Re-publish and diff views after the refactor. DateInput/DateTimeInput were refactored; check for renamed props/slots, changed wrapper markup, and altered default formats. If you have published overrides, diff them against the package's new originals rather than assuming they still apply.
• DST ambiguity. Fall-back hours contain the same local time twice; decide a policy (prefer the earlier offset, or require a timezone-qualified input) and document it. The package cannot resolve this for you.
• Laravel 13 readiness cuts both ways. Verify your laravel/framework constraint and any other date-related packages (e.g. datepicker JS, admin panel form builders) are also Laravel 13-compatible — the package being ready doesn't mean your stack is.
• Release notes are thin. "Minor bug fixes" and "internal cleanup" give you nothing to test against. Pin to 1.0.2 exactly, read the diff on the DateInput/DateTimeInput classes before upgrading a production app, and open an issue if the changelog stays this opaque for the next release.