Calendar Bundle Laravel Package

Getting Started

This is a 0.1-beta release of a driver-based date/calendar package for Laravel. The only documented surface area is two drivers — Persian and Gregorian — and the explicit statement that no views or assets ship yet. Treat everything below as the expected shape of the package; confirm exact namespaces and method signatures against the repo before committing.

1. Install and pin. Because this is 0.1-beta, require it explicitly rather than floating:

   composer require <vendor>/<package>:"0.1.*@beta"
   

   Commit the lockfile. A beta at 0.1 signals the public API is not stable.

2. Look at the driver layer first. Open src/ and find the driver contract/interface and the two concrete drivers. That contract — not the README — is the real API. Check whether both drivers implement the same interface; if they don't, "driver" is a label, not a swappable abstraction.

3. Check for publishable config. Run php artisan vendor:publish and see whether anything is registered. A beta this early may hard-code the default driver instead of exposing config.

4. First use case: convert and format at the presentation boundary. Store timestamps in UTC/Gregorian in your database as usual, then use the Persian driver only when rendering (API resource, Blade echo, PDF, notification). The canonical first test is a round-trip: Carbon → Persian → Gregorian → assert equality with the original instant.

Implementation Patterns

• Wrap it, don't sprinkle it. Create a single CalendarService (or a Blade directive / API Resource macro) that owns the package calls. When 0.1-beta breaks in 0.2, you patch one file instead of grepping your codebase.
• Global default + per-call override. Most driver packages read a default from config and allow an explicit driver argument per invocation. Use the default for user-facing display based on app()->getLocale(), and pass the Gregorian driver explicitly anywhere you serialise for storage or third-party APIs.
• Convert at the edges only. Never let Persian-formatted strings reach the database, queues, or logs. Keep one rule: Persian in the view layer, Gregorian everywhere else. This makes the package trivially replaceable if the beta stalls.
• Pair with Laravel validation manually. Since there are no views/assets, there is likely no form component or validation rule included. Write your own Rule that parses with the Persian driver and rejects invalid dates (see Gotchas on month lengths).
• Locale-driven driver selection. A small config map (fa → persian, en → gregorian) plus a middleware or view composer keeps call sites clean and makes adding a third calendar later a config change.
• Test with frozen time. Use Carbon::setTestNow() and assert both drivers agree on the same instant. Add explicit cases for month boundaries and the Persian year-end.
• Don't use it for scheduling. This is a conversion/formatting layer. Queue delays, cron, and now() comparisons should stay on Carbon/UTC.

Gotchas and Tips

• Beta API churn is the headline risk. 0.1-beta with no prior assessment means there is no migration path and no deprecation policy yet. Pin the version, wrap the calls, and read the diff before every bump.
• "No view and asset yet" is a scope statement, not a bug. Do not plan on Blade components, a JS datepicker, published CSS, or a @persianDate directive. Build your own UI and feed it strings from the driver. If your feature depends on a picker, this package is not ready for that feature.
• Timezone handling is the most likely silent bug. Confirm whether the Persian driver converts timezones itself or assumes a fixed offset (Iran has had DST historically). Always pass an explicit timezone and assert the resulting instant, not just the formatted string.
• Persian month lengths and leap years. Months 1–6 are 31 days, 7–11 are 30, and month 12 (Esfand) is 29 or 30 in leap years. Test 1402/12/29, 1403/12/30, and the Nowruz rollover explicitly — off-by-one-day errors here are the classic failure mode.
• Naming collisions. "Persian", "Jalali", "Solar Hijri", and "Farsi" are used interchangeably across packages. Verify which calendar the driver actually implements before assuming interoperability with verta/morilog/jalali output.
• Driver-swap is not guaranteed to be drop-in. If one driver returns a Carbon and the other a custom value object, your wrapper must normalise the return type.
• Debugging tip: when an output looks wrong, dump the same instant through both drivers side by side. Divergence isolates calendar math from timezone bugs instantly.
• Extension point: the driver contract is almost certainly where you'd add a Hijri or custom calendar. Read it before you need it — if it's a concrete class rather than an interface, extending is a fork, not an implementation.