Dispatcher Laravel Package

Technical Evaluation

Framing and architecture fit

The release in question is Hyperf v3.2.0, not a Laravel package. Hyperf is a PHP-CLI coroutine framework built on Swoole/Swow with PSR-11/PSR-15 conventions, its own DI container, its own hyperf/* component suite, and a Laravel-shaped surface (config/autoload, Eloquent-derived hyperf/database, collections, async-queue). That shape similarity is the main trap for a TPM: it reads like "Laravel with coroutines," but it is a different runtime, different container, and different config loader. Nothing in this release makes Hyperf a drop-in dependency for a Laravel application.

Three viable postures, in order of realism:

Architecture fit for A and C is poor for a Laravel codebase. Fit for B is good — this is the only posture where v3.2.0 is a routine upgrade rather than a platform event.

Integration feasibility and technical risk

The release is heavy on breaking changes for anyone already running Hyperf, and moderate on dependency risk for anyone consuming it next to Laravel.

• Carbon 3 alignment (highest silent-risk item). Carbon::diffInDays() no longer returns an absolute value, and createFromTimestamp() no longer falls back to date_default_timezone_get(). Both are silent semantic changes — no exception, no deprecation, just different numbers. Any reporting, SLA, billing, or retention logic that relied on absolute day deltas or implicit local timezones is now quietly wrong. Note also that the release notes contain a documentation defect: the "break usage" and "correct usage" snippets for createFromTimestamp() are byte-identical, so the guidance is unusable as written and must be resolved by reading the upstream PR.
• Async-queue API rename. JobInterface::getQueueName() → getPoolName(), plus a $queue → $pool property rename on Consumer. Every custom Job class in the estate breaks at load time. This is loud (fatel error), so it is low-severity but high-touch — it is a mechanical codebase-wide edit and a mandatory release blocker.
• Config schema restructures (logger, cache). Both move from a flat map to a default pointer plus channels/stores maps. Published config files that are not republished will fail at container resolution — a startup-time failure, which is preferable to a runtime one, but it means config drift is a deploy-blocking condition and every environment overlay must be audited, not just config/autoload/*.php defaults.
• PHP floor raised to >= 8.2. Clean and welcome; it is also a hard gate that forces the runtime image matrix (base image, CI, local dev) to be rebuilt before anything else lands.
• Dependency ceiling lifts. Symfony ^6||^7, Guzzle ^7, PHPUnit ^11, nikic/php-parser 5.6, Elasticsearch ^8||^9, protobuf ^3.6.1||^4.2. Symfony 6/7 in particular is where coexistence with a Laravel app gets sticky — Laravel 11/12 already pins Symfony 7, and Composer will be the arbiter of whether a shared vendor tree is even possible. Assume it is not, and plan for separate vendor trees.
• Removed APIs. CacheableSupportsMethodInterface, async-queue JobMessage BC shim, collection BC layer, ProxyTrait parameter mapping, SocketIO flag, WebSocket typo alias, laminas/laminas-mime. Static analysis (PHPStan at a meaningful level) is the cheap way to enumerate blast radius before touching production.
• Behavioral changes with runtime-exception risk. Builder::limit() now throws on negative values — code that passed -1 as a "no limit" idiom will now hard-fail. deleted_at defaults to datetime — soft-delete column semantics and timezone handling need a migration review.
• Swow dependency registration. Swow users must now bind ResponseEmitterInterface explicitly; omitting it is a runtime failure in the response path, not a startup one.
• PHP 8.4 CSV warning. fgetcsv/fputcsv require an explicit escape. Low effort, but it is a scattered search-and-replace across import/export code.

Key questions for the maintainers / owning team

1. Which posture (A/B/C) are we actually on? If B, is the Hyperf service in scope for this quarter's upgrade budget at all?
2. Do we have a defensible inventory of diffInDays() and createFromTimestamp() call sites, or is this a search-and-pray exercise?
3. Is Hyperf v3.1 still receiving security patches, and for how long? That sets the true deadline.
4. Which of the two supported engines (Swoole vs Swow) are we on, and is that decided?
5. Who owns the config republish across dev/staging/prod overlays?
6. Can we get a corrected createFromTimestamp() example upstream before we publish internal migration guidance?

Integration Approach

Stack fit

Target Laravel remains on PHP 8.2+ with Symfony 7 — which happens to align with this release's Symfony floor, so the constraint is not the blocker. The blocker is the container and runtime model, not the version numbers. Do not attempt a shared Composer vendor tree between Laravel and Hyperf; isolate the Hyperf service into its own repository or a monorepo package with an independent composer.json, and communicate over HTTP/gRPC/queue rather than shared code.

For the Laravel side, this release is effectively a non-event except for one item: if the same estate independently upgrades nesbot/carbon to 3.x, the diffInDays() and createFromTimestamp() semantics change identically. Treat that as a shared cross-cutting risk and audit it once, estate-wide, rather than twice.

Migration path (Hyperf service, v3.1 → v3.2)

1. Gate on runtime. Rebuild the base image to PHP 8.2+ (ideally 8.3), confirm Swoole or Swow extension versions, update CI matrix and local dev containers. Nothing else starts until this is green.
2. Freeze and branch. Cut upgrade/v3.2 off the current release tag. Do not interleave feature work.
3. Dependency resolution. Bump composer.json constraints, run composer update --with-all-dependencies in isolation, and record the resolved lock as the new baseline. Expect to unpin anything that disagrees with Symfony 7 / PHPUnit 11.
4. Static analysis sweep. Run PHPStan across the codebase at the strictest level the team can tolerate to surface removed interfaces, renamed methods, and the ProxyTrait/collection BC removals in one pass rather than deploy by deploy.
5. Mechanical codemods. getQueueName() → getPoolName(), $queue → $pool, fgetcsv/fputcsv escape arguments, laminas-mime replacement, InfluxDB client swap (influxdb/influxdb-php → influxdata/influxdb-client-php, which is a genuine API rewrite, not a rename — budget it separately).
6. Config republish. Rewrite config/autoload/logger.php and cache.php to the default + channels/stores shape. Do this for every environment overlay, then diff against the framework's published defaults. Add dependencies.php binding for ResponseEmitterInterface if on Swow.
7. Semantic audit (the part that needs humans). Review every diffInDays() call for whether absolute value was load-bearing, and every createFromTimestamp() call for timezone assumptions. Review ->limit(-1) idioms and soft-delete column types (deleted_at now datetime). This is the only step that cannot be automated reliably.
8. Shadow-run. Deploy to staging, replay production-shaped traffic, and diff outputs from reporting/billing paths against the v3.1 baseline.
9. Cut over with a rollback tag ready.

Sequencing note: steps 1, 3, and 4 are hard prerequisites for everything downstream. Steps 5 and 6 are parallelizable across owners. Step 7 is the critical path and should be staffed first, not last.

Compatibility caveats

• Elasticsearch 8/9 support is additive but the client upgrade is not symmetric — verify index mapping and query DSL against the target cluster version before assuming a version bump is sufficient.
• WebSocket HandeShakeException typo alias removal will surface only in code that referenced the misspelling — grep for it explicitly rather than trusting static analysis.
• Jsonable::toJson(), Htmlable, Pipeline::finally(), Context macroability, and the async-queue auto-registration mode are all safe to adopt opportunistically; none are prerequisites.

Operational Impact

Maintenance

The recurring cost is configuration-surface churn. Two schema restructures in one release (logger, cache) is a signal that Hyperf's config contracts are still moving; budget for a config audit on every minor release, not just majors. Pin the framework exactly and upgrade deliberately — this is not a dependency that tolerates floating constraints.

The Carbon 3 semantics are a durable maintenance hazard, not a one-time migration. Once diffInDays() is non-absolute by default, every future "days between" calculation carries an implicit ordering assumption that reviewers must consciously check. Encode that as a lint rule or a code-review checklist item, or it will regress.

Support

Hyperf's community is materially smaller than Laravel's. For a TPM this translates to: fewer StackOverflow answers, longer mean-time-to-answer on upstream issues, and a real chance that the migration guidance you need (e.g. the broken createFromTimestamp() snippet) is only obtainable by reading PR diffs. Staff the upgrade with someone who can read framework internals, not just consume documentation. If the codebase's only Hyperf exposure is a single isolated service, this is manageable; if Hyperf is load-bearing infrastructure, it is a key-person dependency worth naming explicitly as a risk.

Scaling

Unchanged by this release — the coroutine model's scaling characteristics are the same before and after. The change that matters operationally is async-queue: the getPoolName() rename plus the new config-driven consumer registration mode means queue topology is now expressible in configuration. That is a genuine operational win (fewer manual processes.php entries, less drift) but only if the config-driven mode is adopted deliberately and the pool naming is consistent with whatever the queue backend calls the same concept. Rename half the codebase and you get jobs silently landing in the wrong pool — a failure that looks like throughput loss, not an error.

Failure modes to instrument

Ramp-up

Estimate by posture: B (isolated service) is a 1–2 engineer-week upgrade for a team already fluent in Hyperf, gated almost entirely on the semantic audit in step 7. A (component reuse) is days, and probably not worth doing. C (full migration) is a multi-quarter program that this release does not change the calculus on.

For a team new to Hyperf but experienced in Laravel, add meaningful ramp-up specifically on the coroutine mental model — shared state across requests, blocking calls, and connection-pool lifetimes behave differently from FPM, and the config similarities actively mislead. The upgrade itself is not the onboarding exercise; running the service in production is.

Recommendation: upgrade posture B on a deliberate schedule, treat the Carbon semantics as an estate-wide audit that also covers the Laravel side, block release on the async-queue rename and config republish, and request a corrected createFromTimestamp() example upstream before publishing internal guidance.