Filament Persian Date Field Laravel Package

Getting Started

This release (v2.0.1) is a compatibility patch — the only stated change is support for Laravel 11 and 12. There are no new features or API changes advertised, so treat the upgrade as a constraint-widening exercise rather than a code migration. That said, since no prior assessment exists, the workflow below doubles as the baseline onboarding path.

1. Verify your runtime first. Laravel 11 and 12 both require PHP 8.2+, and L12 raises the floor further in some components. Check php -v and your composer.json "php" constraint before touching the package.
2. Inspect the constraint diff, not the code. Run composer require vendor/package:^2.0.1 --dry-run (or composer update vendor/package --with-dependencies -W --dry-run) and read which illuminate/* versions Composer resolves. This tells you more about the release than the changelog does.
3. Look here first, in order: the package's composer.json (require / require-dev), the README's upgrade or requirements section, CHANGELOG.md for the 2.0.0 → 2.0.1 delta, and config/*.php for anything that changed shape.
4. Confirm discovery and publishing. Most Laravel packages register via extra.laravel.providers; check php artisan about or php artisan package:discover output rather than assuming. Then php artisan vendor:publish --tag=<package>-config if a config file ships.
5. First use case: wire the package into a single, low-risk entry point — one artisan command or one read-only controller action — and assert the output in a feature test. This proves container bindings, config resolution, and facade aliases work under L11/L12 before you spread usage across the app.

Implementation Patterns

Resolve from the container, not the facade, in application code. Bind the package's client/manager behind your own interface in a service provider and inject it. This keeps you insulated if a future major changes constructor signatures, and it makes the dependency trivially fakeable in tests.

Gate rollout behind config. If the package talks to an external service, route its enablement through a config value that reads from env(), defaulting to off in config/package.php and on per-environment. This lets you merge the upgrade and flip it per environment rather than in one deploy.

Test against both framework versions. Since the entire value of this release is L11 + L12 support, encode that assumption in CI: a matrix running the package's integration tests on orchestra/testbench for both majors (roughly ^9.0 for L11 and ^10.0 for L12 — confirm exact versions against the package's own require-dev). A single-version matrix silently defeats the point of the release.

Use fakes over network calls. Most packages in this space ship a ::fake() or an equivalent contract-level test double. Prefer that in feature tests and reserve real calls for a small number of tagged integration tests, so the suite stays fast and offline-safe.

Wire long-running work into the queue. If the package exposes synchronous calls that hit I/O, wrap them in a job with $tries/$backoff set explicitly, and dispatch after commit (->afterCommit() or after_commit = true) so a rolled-back transaction doesn't emit work.

Schedule through the scheduler, not cron. Register recurring package operations in routes/console.php or Kernel::schedule() with withoutOverlapping() and onOneServer() where the underlying operation isn't idempotent.

Upgrade sequence for existing installs: pin ^2.0.1, run composer update vendor/package -W, run the full suite, then scan storage/logs/laravel.log for deprecation notices emitted during boot — L11 removed a number of deprecated internals, and packages that touch them often warn rather than fail.

Gotchas and Tips

• v2.0.1 is a patch. Absent a changelog entry saying otherwise, assume no behavioural change and no deprecations. Do not rewrite call sites on the strength of a version-support bump.
• -W matters. Without --with-dependencies, Composer may keep an older illuminate/support pinned by a sibling package, and you'll get a resolution failure that looks like the package is broken when it's actually a transitive conflict.
• Testbench version mismatch is the most common CI failure after an L11/L12 bump. Align orchestra/testbench with the framework major; a stale testbench produces confusing "class not found" errors in setUp().
• Clear caches after publishing config. php artisan config:clear && php artisan cache:clear. A cached config from the previous major is a classic source of "my new config key is ignored."
• Check for manual provider registration. If bootstrap/providers.php (L11+) lists the provider explicitly, package auto-discovery may be bypassed, and you'll be running a stale provider after the upgrade.
• Deprecation noise is asymmetric. L11 emits runtime deprecations for removed contracts; L12 tightens types further. Run the suite with error_reporting(E_ALL) locally so you see them before production does.
• Debugging resolution: app()->make(Vendor\Package\Client::class) in tinker confirms the container binding; dump(config('package')) confirms config load order. These two checks resolve the majority of "package doesn't work after upgrade" reports.
• Extension points worth knowing: container binding overrides in AppServiceProvider::register(), config-driven driver/manager selection (extend() on the manager if one is exposed), and macros if the package returns an Illuminate\Support\Collection or a Macroable trait.
• Lockfile hygiene: commit composer.lock and pin the package to ^2.0.1 rather than ^2.0 if you want the L11/L12 support guaranteed on fresh installs; ^2.0 permits resolution below the patched floor.