Laravel Pt Br Localization Laravel Package

Getting Started

This release (v3.0.3) is a compatibility patch: it adds Laravel 12 support. There are no new public APIs, no deprecations, and no breaking changes signalled in the notes, so the "getting started" story is the same as before — you just get to stay on a supported framework version.

Minimal steps:

1. Confirm your constraints allow it. Laravel 12 requires PHP 8.2+, so run php -v and check composer.json before pulling this in. If you're still on Laravel 10/11, this release is a no-op for you — but it is the release that unblocks your next framework upgrade.
2. Install/upgrade the package:

   composer require <vendor>/<package>:^3.0
   # or, if already installed
   composer update <vendor>/<package> --with-dependencies
   

3. Publish and review config if you haven't already. Most Laravel packages of this shape expose a config file and optionally migrations:

   php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider"
   

   Read the config file top to bottom before changing anything — several defaults are environment-sensitive and are the usual source of "works locally, not in CI" reports.
4. Where to look first: the package's README upgrade section, then CHANGELOG.md for the v3 major-line notes (v3.0.0 is where the real behaviour changes live; v3.0.x patch releases are fixes and framework support). If the package ships a facade or a container binding, that binding is your entry point — resolve it once in php artisan tinker to confirm registration.
5. First use case: take your single most representative call site (one read path, one write path), exercise it against Laravel 12, and confirm output parity with your current version. That one test tells you more than a full test-suite run, because it validates bootstrapping, config resolution, and container wiring together.

Implementation Patterns

Pin to the minor line, not the patch. Use ^3.0 rather than 3.0.3. Framework-support patches like this one ship frequently; pinning the patch forces needless lockfile churn and blocks security fixes.

Upgrade in an isolated branch with a dependency-graph check. Before the framework bump, run:

composer why-not laravel/framework 12.*

That lists exactly which packages (this one included, pre-3.0.3) are holding you back. Treat this release as one gate cleared, then re-run until the list is empty — it's a far faster loop than iterating through composer update failures.

Centralise access behind a small wrapper. Whether the package resolves via facade, injected interface, or helper, wrap it in one application-level service (e.g. App\Support\<Domain>Service) that your controllers and jobs depend on. Two payoffs: when the v4 line changes an API, you edit one file; and you can swap in a fake in tests without touching the package internals.

Bind in tests, don't hit the network. Register a fake or a stub implementation in your base TestCase and override per-test. If the package does not ship a first-party fake, write a thin one against the interface and keep it in tests/Support/ — this is the highest-leverage thing you can build on day one.

Use it from queued jobs, not request handlers, for anything slow. This is where framework-compatibility releases most often surface latent issues (serialisation, container re-resolution after queue:restart, service provider boot order). Exercising the package inside a job on Laravel 12 is a genuinely different code path than exercising it in a request.

Keep the config in config/ and reference it only through config(). Do not read env() from application code that touches the package — config caching will silently hand you null in production while local dev works fine.

Verify the service provider is discovered. Laravel 12 still auto-discovers via composer.json extra.laravel.providers. If you use package discovery optimisation, run php artisan package:discover after the upgrade and check the provider appears in bootstrap/cache/packages.php.

Gotchas and Tips

The release note is one line — treat it as incomplete. A terse "Laravel 12 support" entry usually understates the diff. Before merging, read the actual commit range for v3.0.0 → v3.0.3:

composer diff <vendor>/<package> 3.0.0 3.0.3

Look specifically at composer.json constraint widening and any illuminate/* version bumps. If it widens laravel/framework to ^12.0 but leaves a transitive dependency unbumped, you'll hit a resolution conflict you can't fix from your side.

PHP version is the real gate. Laravel 12 requires PHP 8.2+. A package "supporting Laravel 12" implies it now declares php: ^8.2. If your CI matrix still tests 8.1, your build breaks on a package you upgraded only for framework compatibility. Update the matrix in the same PR.

Minor-version bumps inside a patch release are a smell. If v3.0.3 pulls in a new major of any illuminate/* sub-package, that is technically a breaking change wearing a patch number. Diff the lockfile — git diff composer.lock after the update — and read every changed line rather than trusting semver.

Deprecation noise precedes breakage. Run your suite with deprecations surfaced:

php artisan test --stop-on-deprecation

Anything the package triggers on Laravel 12 is your early warning for v4. Fix or annotate now while the surface is small.

Config cache must be rebuilt after upgrade. php artisan config:clear && php artisan config:cache in every environment. Stale cached config after a provider change is the single most common false-positive "the upgrade broke it" report.

Debugging boot-order problems: if the package works in isolation but fails inside your app, dump the resolved provider list with php artisan about (Laravel 11+) and compare ordering against a fresh Laravel 12 skeleton. Provider ordering issues are silent until something touches the container during boot().

Extension points to prefer: config-driven overrides first, then container bindings ($this->app->bind(...) in your own provider), then published views/migrations, then subclassing the package's classes. Subclassing is the most brittle — it couples you to internals that patch releases freely change. If you find yourself extending a class from src/, file an upstream issue instead and use a wrapper.

Don't skip the changelog for v3.0.0. If you're coming from v2.x, the Laravel 12 note is not your migration guide — v3.0.0 is. Read it before you assume this patch is drop-in.