Px User Laravel Laravel Package

Getting Started

• Require the package with composer require mindtwo/px-user-laravel and run php artisan vendor:publish --tag=px-user-config (tag name may vary — check src/PxUserServiceProvider.php for the actual publish groups).
• Look first at config/px-user.php (endpoints, credentials, driver/guard wiring) and src/ for the guard, user provider, and any client/resource classes. That is the whole surface area of this package — there is no UI.
• Register the driver in config/auth.php (guards.web.provider → the package's provider, plus providers.px with the package's provider class) and set the related env vars (PX_USER_*, base URL, credentials).
• First use case: log a user in against the external PX service and get a local authenticated user — Auth::attempt($credentials) should hit the package provider transparently, then your app reads/writes the local users record as usual.
• After upgrading to 4.1.10, check the new "extended products on login" option in the config file. It is off by default unless the PR changed the default — read the config diff between 4.1.9 and 4.1.10 and set it explicitly so behaviour is deterministic across environments.

Implementation Patterns

• Guard/provider as the seam. Treat the package as an Illuminate\Contracts\Auth\UserProvider implementation. Everything your app does should go through Auth:: — do not call the package's client classes directly from controllers, or you lose the retry/token handling the provider gives you for free.
• User mapping. Expect a mapper/repository that turns the remote user payload into a local Eloquent model (usually App\Models\User) keyed by an external ID column. Keep that column indexed and unique; use firstOrCreate-style upserts on every login rather than assuming the remote IDs are stable.
• Session login. The typical flow is: validate credentials → package provider calls the remote API → local user is created/synced → Auth::login($user, $remember). Do the sync inside a DB::transaction() if you also write profile fields, so a partially-synced user is never persisted.
• Extended products on login (4.1.10). This is the notable new behaviour: an option to also fetch "extended" product data as part of the login call. Use it when you need the product/entitlement payload available immediately in the session/user object after login. Because it is opt-in, enable it only for the guards/flows that actually need the extra payload — e.g. enable it for the web guard but not for API/token issuance.
• Token handling. Store the remote access token alongside the local user (a px_access_token / px_token_expires_at column or a cached entry) and refresh lazily on 401 rather than on a schedule. Wrap any outbound call in a small try/catch that maps remote 401s to a refresh and remote 5xx to a retryable exception.
• Testing. Use Http::fake() with fixtures captured from the real API and assert on the guard, not on the HTTP layer. Write one test per flow: successful login, invalid credentials (assert no local user created), remote outage (assert the login fails gracefully and does not half-create a user), and — new here — login with extended products enabled/disabled.
• Multi-guard apps. If you have separate admin/customer guards against different PX tenants, register two providers with distinct config arrays rather than one provider with runtime config mutation; config() mutation breaks under Octane and queued workers.
• Queues/Octane. Anything that touches the package outside a request (jobs, commands) must re-resolve config explicitly; cache the config and credentials once per worker, not per call.

Gotchas and Tips

• Config cache. After changing any of the new 4.1.10 options, run php artisan config:clear (and config:cache in deploy). This is the single most common "the new option does nothing" report.
• Extra round-trips on login. Fetching extended products on login makes the login request heavier — potentially a second remote call in the same request. If PX is slow, login latency rises directly. Consider enabling it only where the payload is needed, or move the product sync to an event listener (Login event → queued job) and keep the login path to a single call.
• Partial failure. Decide what happens when authentication succeeds but the extended-products fetch fails: the user is authenticated but the payload is missing. Make sure the package (or your wrapper) does not roll back the login, and handle the empty payload in your views instead of assuming it is populated.
• Default flip. Verify whether the new option defaults to true or false in config/px-user.php — a release that changes login behaviour silently is worse than an opt-in. Pin it explicitly in your published config and in .env.
• Credential hygiene. Keep PX credentials in .env only; never log the raw remote response, since user payloads typically include the access token. Add a redaction list to your logging config (config/logging.php tap or a Monolog processor) around the package's channels.
• Debugging. When a login fails, the package usually swallows the remote error behind a generic ValidationException. Temporarily add Http::globalRequestMiddleware/Http::fake logging or tail the package's log channel to see the actual remote status; do not enable verbose logging in production because of the token leak above.
• Extension points. Prefer listening to the package's events or binding your own implementation of its client/mapper contracts in a service provider over editing the vendor config, so future 4.x releases (like this one) do not conflict with your customisations. Re-run your login test suite after every minor bump — the provider behaviour is the contract you actually depend on.