Puzi Laravel Laravel Package

Getting Started

pUZI-laravel wraps the minvws/puzi library (UZI smartcard / certificate handling for Dutch healthcare SOAP services) in Laravel service-provider, config and middleware sugar. Treat it as infrastructure glue, not an application framework — most of your day-to-day work happens in the config file and in the service classes you inject.

1. Install and discover

   composer require minvws/puzi-laravel
   php artisan vendor:publish --provider="MinVWS\\PuziLaravel\\PuziServiceProvider"
   

   Check the service provider's $this->publishes array for the exact tags (config, migrations, views) before guessing — the package has historically used both tagged and untagged publishing.

2. Verify the runtime prerequisites before writing any code. You need the PHP soap and openssl extensions, and for real card reads a working PC/SC stack (pcscd, the vendor smartcard middleware) on the host running PHP. Nothing in Laravel will tell you this gracefully; a missing reader surfaces as a low-level exception. Confirm php -m | grep -E 'soap|openssl' and that a card is visible to pcsc_scan first.

3. Look at the config file first. It is the map of the whole package: reader selection, certificate paths/CA bundle, SOAP endpoints and the middleware alias. Read it end to end once — it answers most "how do I point this at the acceptation environment" questions.

4. First use case: authenticate a route with a UZI card. Register the middleware alias provided by the package on a route group, hit the route with a card in the reader, and dump the resolved identity. This single flow exercises reader → certificate → session binding, which is where 90% of setup problems live.

5. Then a signed SOAP call. Take the simplest service call (a "get" style operation on the acceptation endpoint) and confirm the request is signed and the response validates. Once that round-trips, every other service is a variation.

Implementation Patterns

Inject, don't app(). The package binds its core services in the container. Type-hint the manager/client interfaces in your controllers, jobs and listeners rather than resolving them statically — it keeps you testable and survives the package reorganising internals (see the v3.2.2 CA-cert refactor for how internals move).

Middleware for identity, not authorisation. Use the package middleware to establish who the card holder is and to guarantee a valid certificate is present in the request lifecycle. Do your own authorization (roles, patient relationships) in a policy or gate on top of that identity. Mixing the two makes it impossible to test authorization without hardware.

Wrap SOAP calls in your own service layer. Create one small class per external service (e.g. VecozoClient, CibgClient) that takes the package's client in its constructor and exposes typed methods returning your own DTOs. The raw SOAP responses are verbose and version-sensitive; centralising the mapping means a schema change touches one file.

Bind the client in a service provider keyed by environment. Use $this->app->bind() / singleton() with a match on app()->environment() to select acceptation vs production endpoints and certificate sets. Keep the endpoints in config/ and the selection logic in the provider — never branch inside the controller.

Long-running processes need care. In queue workers and Octane, a card/certificate handle captured at boot is stale. Resolve the client per job (app()->make() inside handle()) or use Queue::before()-style refreshes, and never cache a card session in a singleton for the request lifetime of a worker.

Testing pattern. Fake at your own service-layer boundary: bind a stub VecozoClient returning fixture DTOs, and stub the identity middleware to inject a known card holder. Keep a tiny set of "contract" tests (marked as a separate group, skipped in CI) that hit the real acceptation endpoint with a real card so certificate/signature regressions are still caught.

Scheduled health checks. Add a scheduled command that validates the loaded certificate's expiry and chain, and alerts well before expiry. Certificates on UZI cards and the CA bundle expire; the failure mode is a hard outage on the day, not a warning.

Gotchas and Tips

Hardware and environment drift is the number one cause of "the package is broken". The reader daemon must be running on the machine executing PHP — not your laptop browser host, not a container without USB/PC-SC passthrough. If card reads work in a CLI script but not in HTTP, you are almost certainly in a different process namespace (FPM pool, container, or Sail/Valet VM).

Never log certificate material or SOAP envelopes at debug level in production. Signed envelopes and card data are personal data under the Dutch healthcare privacy regime. Register a redacting processor on your logging channel, or gate the package's verbose logging behind an env flag that is off by default, and confirm it is off in staging too.

config:cache will bite you. Anything you compute in the config file (paths from storage_path(), environment-dependent certificate locations) must remain pure — closures and env() calls outside the config file break after php artisan config:cache. If the package's own config uses env(), keep it and never override with runtime logic.

CA bundle and chain trust. v3.2.2 extracted the CA-certificate parser into its own class. Behaviour should be unchanged, but if you have ever depended on the old parser's location, subclassed it, or asserted on its exception messages, re-run your certificate tests. If you need to inspect the chain yourself (expiry dashboards, revocation checks), depend on the new dedicated parser class rather than re-implementing ASN.1/X.509 handling — that is precisely the code you do not want to own.

Session binding pitfalls. A card removed mid-request yields confusing downstream errors rather than a clean 401. Wrap boundary calls and translate reader/certificate exceptions into a single domain exception, then render a friendly "please re-insert your card" response at the HTTP layer via Handler::renderable().

Extension points worth knowing. The service provider binds concrete implementations; where the package offers interfaces, bind your own decorator (logging, retry, metrics) around the package service instead of editing package code. Decorators survive minor releases like 3.2.2; forks do not.

Debugging order of operations. (1) Does plain puzi/openssl tooling see the card and parse the cert? (2) Does the package resolve from the container (php artisan tinker → app(YourClient::class))? (3) Does a single signed call succeed against acceptation? Only then look at your application code. Skipping step 1 wastes hours.

Version pinning and changelog discipline. This package moves in small patch releases that occasionally relocate internals (v3.2.2: CA-cert parser moved to a separate class). Pin to a minor (^3.2) rather than a patch, read the diff of every patch you take, and keep the certificate/signature contract tests green on upgrade — those are the parts that break silently.