Laravel Persian Validation Laravel Package

Getting Started

• Check what changed first. v2.1.0 is a compatibility release: the only documented change is Laravel 13 support. Treat it as a constraints/plumbing update, not a feature release — the public API you were using in 2.0.x should be unchanged. Confirm by diffing the tag rather than assuming: composer diff isn't a thing, so browse the compare view (v2.0.x...v2.1.0) on the repo and scan composer.json + src/ for anything beyond version bumps.
• Verify your own framework version before requiring it. v2.1.0 is the first line declaring illuminate/* ^13.0. If your app is still on Laravel 12, keep the constraint at ^2.0 so Composer doesn't try to pull 2.1.0 and fail resolution against your framework pin.
• Install: composer require <vendor>/<package>:^2.1 (use ~2.1.0 if you need reproducible builds across a fleet of apps).
• Publish only what you need:
  • php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" to list available tags.
  • php artisan vendor:publish --tag=package-config for config.
  • php artisan vendor:publish --tag=package-migrations if it ships tables, then php artisan migrate.
• Confirm discovery actually happened. php artisan about and php artisan package:discover -v are the two fastest sanity checks that the service provider registered. If it's missing, check the extra.laravel.dont-discover block in your composer.json.
• First use case: take the shortest end-to-end path, not the full feature set. Set the minimum required .env keys (usually driver/connection/queue), open config/package.php to see which keys have env fallbacks, then exercise one call from php artisan tinker before wiring it into a controller. If the package is queue-backed, dispatch a single job and watch php artisan queue:work --once — that surfaces config problems that a synchronous call hides.

Implementation Patterns

• Wrap it in one app-level seam. Even for a thin package, put a small manager/service class (or your own facade) in front of it. Package upgrades then touch one file, and swapping implementations later is a bind() change rather than a grep across controllers.
• Config, not code. Drive everything through config/package.php with env() fallbacks, and use per-environment .env values. Reserve config()->set() for tests and per-tenant rebinding — never for production wiring.
• Push expensive work to jobs. Any package operation that hits an external service (HTTP, mail, storage, third-party API) belongs in a queued job with retries and a timeout, not in the request cycle. This is the single most common way these packages get adopted badly.
• Prefer events over inheritance. If the package fires events, listen and react. Extending package classes couples you to internals that a patch release can change; event/listener wiring usually survives.
• Rebind for multi-tenancy. If the package resolves a singleton holding config, a tenant-switching middleware needs both config([...]) and app()->forgetInstance(ThePackage::class) — updating config alone leaves the stale instance alive.
• Test at the boundary. Use Http::fake() / Queue::fake() plus the package's own fakes if it ships them; otherwise integration-test with an in-memory SQLite connection. Add one test that asserts the config resolves as expected so a future major bump fails loudly.
• Upgrade runbook: composer update <vendor>/<package> --with-dependencies → run the app's test suite → only then vendor:publish --tag=package-config --force after diffing the published config against the new stub. Never blanket-force-publish; you'll silently clobber customized migrations.

Gotchas and Tips

• "Adds Laravel 13 support" is a claim about composer.json, not proof of behaviour. Laravel majors remove deprecated APIs; the package may still call something that only survives on 13 if you're coming from 11. Run your suite on the target framework version before shipping, not just composer update.
• Constraint resolution is the usual failure mode. A ^2.1 constraint on a Laravel 12 app produces a confusing "your requirements could not be resolved" message. Test with composer why-not <vendor>/<package> 2.1.0 — it names the exact blocking package, which saves far more time than reading the solver output.
• config:cache freezes env values. Any .env change after php artisan config:cache is invisible. Re-run config:cache (or config:clear locally) in every deploy step, and remember it inside queue workers too.
• Publish tags, not everything. A bare vendor:publish can overwrite migrations you've already modified. Always pass --tag= and --force deliberately.
• Provider ordering matters for extension points. If you need to swap the package's implementation, bind your class in a provider that registers after the package's. Use register() for bindings and boot() for anything that depends on other providers being ready.
• Singletons hold stale config. Runtime config() changes plus a resolved singleton equals a bug that looks like "the package ignores my settings." forgetInstance() after rebinding, or bind as a non-shared instance.
• Debugging order that works: composer show <vendor>/<package> (confirm the installed version is really 2.1.0) → php artisan package:discover -v (provider registered?) → php artisan about → php artisan tinker calling the smallest method → Log::debug(config('package')) to confirm config reached the container.
• Don't over-pin, don't under-pin. For an app, ~2.1.0 gives you reproducibility; for a library that depends on this, ^2.1 lets consumers resolve. Mixing the two across a monorepo is a common source of duplicate-install headaches.