Laravel Scavenger Laravel Package

Getting Started

Treat v4.0.0 as a platform upgrade, not a routine composer update. The package now requires PHP 8.3+ and supports Laravel 12 and 13 only, so the first step is confirming your app (and any CI images, Dockerfile base images, and composer.json platform block) are on 8.3 before you touch the dependency.

1. Check your toolchain. php -v, composer why-not php 8.3, and confirm the Laravel version constraint in composer.json resolves to 12.x/13.x. Older Laravel majors are not supported by v4.
2. Install/upgrade. composer require <vendor>/<package>:^4.0 (or composer update <vendor>/<package>). The Goutte removal will surface as a composer conflict if anything else in your dependency tree pulls Goutte in — resolve that first, it's the fastest signal that you have code to port.
3. Look at config first. The two values that drive most behaviour are the daemon model setting (defaults to App\Models\User in v4) and guzzle_settings.timeout. Read both before running anything, because both changed semantics rather than just moving.
4. First use case: start a single daemon process under your process manager (Supervisor/systemd), pointed at one real user, and confirm from the logs that it authenticates as that user. That one smoke test exercises the model resolution, the password-cast path, and the HTTP client swap in a single run.

Implementation Patterns

Be explicit about the daemon model. v4 changes the default to App\Models\User. That's convenient for greenfield apps and silently wrong for anyone with a tenant-scoped user model, a soft-deleted auth model, or a dedicated bot/service account table. Set the model explicitly in config even when the default matches — it documents intent and survives the next default change.

Let the hashed cast do the hashing. If your daemon model uses Laravel's hashed password cast, the package no longer hashes a second time. The pattern is: assign plaintext to the attribute, let the cast store the hash, and remove any Hash::make() you added as a workaround on 3.x. If you ever write the password via DB::table() or mass raw updates (bypassing Eloquent), you still hash manually — the cast only applies on model assignment.

Set guzzle_settings.timeout for the whole request, not the gap between bytes. This is the biggest behavioural change: the single value is now both the idle timeout and the maximum request duration. Tune it to your slowest realistic full response, not to your longest expected wait. If a daemon call legitimately takes 90 seconds end-to-end, a 30-second timeout that used to survive on trickling bytes will now hard-fail at 30. Workflows that need a long idle window plus a bounded total duration have to be redesigned (split the call, or wrap the client with your own handler stack).

Write against HttpBrowser, not Goutte. New work should use Symfony's HttpBrowser API directly — $browser->request(), $browser->submit(), and DomCrawler selectors on the response. Anything type-hinted against Goutte\Client or reaching into Client::setClient() for a custom Guzzle client needs porting; the equivalent is constructing HttpBrowser with your Guzzle client/options.

Test at the HTTP boundary. Because the package is driven by an HTTP browser plus a configurable model, the high-value tests are (a) a unit test asserting your daemon resolves the right model instance, and (b) an integration test that binds a mock Guzzle handler / HttpBrowser so the run never leaves the machine. Assert on the parsed result, not on raw HTML strings, so the Goutte→HttpBrowser migration doesn't invalidate your suite.

One daemon per identity. Where you previously ran a process per tenant or per account, keep that shape: parameterise the daemon model per process and run N supervised workers rather than trying to multiplex inside one long-lived process. Password-cast behaviour and config caching both behave more predictably that way.

Gotchas and Tips

• No deprecation runway. This is a major with a hard floor (PHP 8.3, Laravel 12+). Do it on a branch, and expect downstream packages that still require Laravel ≤11 to block the upgrade — resolve those first.
• The default model change is silent. Nothing errors; the daemon just starts authenticating as App\Models\User. If you have any environment where that class exists but isn't the right identity, you get a confusing auth failure or, worse, a successful run against the wrong account. Grep your config for the daemon model setting during the upgrade.
• Double-hash regressions cut both ways. The v4 fix means pre-hashed values passed in by your own code are now hashed again if the hashed cast is present. Search seeders, importers, and any password => Hash::make(...) in factories when moving to v4.
• Diagnosing timeouts is harder now. A single timeout value means the log line "timed out after 30s" no longer tells you whether the peer went quiet or the request was just slow. Log the elapsed time and the last successful step; consider a per-call override rather than one global value if you talk to more than one endpoint.
• Stale config after upgrade. New keys won't appear in a cached config file. Run php artisan config:clear (and republish the config) before debugging anything — a missing key looks identical to a broken feature.
• Check Goutte is really gone. Run composer show | grep -i goutte after upgrading. A transitive dependency keeping Goutte installed will mask porting mistakes until Goutte is finally dropped upstream.
• Extension points to lean on: bind a configured HttpBrowser/Guzzle client in the container for per-environment proxies, auth middleware, and retry logic rather than editing the package config; and keep custom daemon models implementing the auth contract the package expects (password attribute plus whatever it calls to identify the account) so future minors don't break you.
• Supervisor hygiene. Restart workers as part of deploy — long-lived daemons hold the old config and the old browser instance in memory, so config:cache alone won't pick up v4 settings.