Ide Helper Laravel Package

Product Decisions This Supports

• Whether "Swoole-first" is a real platform bet or an incidental one. Installing this package is a cheap, reversible declaration that the team intends to write Swoole code deliberately. If nobody installs it, that's a useful signal that Swoole is an implementation detail buried under a framework abstraction and shouldn't appear on the roadmap as a platform competency.
• Build vs. buy (buy, obviously). Upstream mirrors Swoole releases within days — 6.1.8, 6.1.9, 6.2.0, 6.2.1, 6.2.2 are all published — with accurate native type declarations and PHPDoc. Generating and maintaining stubs against a C/C++ extension surface in-house is not a defensible use of engineering time. Treat this as the barryvdh/laravel-ide-helper of the Swoole world: tooling, not application dependency, and govern it accordingly.
• Scoping the support surface you're committing to. The package contents are effectively an inventory of what the platform team must support once Swoole is standardized: all Swoole\ classes (one file per class), global swoole_*() functions, SWOOLE_* constants, short aliases like Co\Channel, plus src/swoole_library/ — the userland companion library loaded when swoole.enable_library is on. That last one is easy to miss in planning: developers will index and then call library classes, so they belong in your compatibility story.
• A concrete developer-onboarding metric. The value is measurable and worth attaching to an enablement OKR: time-to-first-working-coroutine, count of "undefined class" diagnostics on a clean clone, days-to-first-merged-PR for engineers new to coroutines. Without a metric, this looks like noise on a dependency list.
• Version-alignment policy as a standing decision, not a one-off install. Stub release 6.0.2 documents Swoole v6.0.2; a mismatch produces exactly the wrong kind of confidence — autocomplete suggesting methods that don't exist at runtime. Decide the policy once (pin to the extension line, bump both together) and name an owner. Note the cadence is upstream-driven, so don't commit to "always current"; commit to "within one minor of the runtime we ship."
• Workstation standardization. PhpStorm ships its own less complete Swoole stubs that conflict, requiring an explicit Settings → PHP → Stubs → deselect swoole step per machine. That's a documentation/onboarding deliverable, not a code one — but someone has to own it.

When to Consider This Package

Adopt when:

• The runtime genuinely executes under Swoole — a Swoole HTTP/WebSocket server, coroutine workers, Laravel Octane on the Swoole driver, or Hyperf.
• Application or library code references Swoole\* classes or swoole_*() functions directly, rather than only through a framework facade.
• The team edits in PhpStorm or VS Code with Intelephense, which index vendor/ automatically.
• swoole.use_shortname is consistent across local, CI, and container php.ini files. If it isn't, fix the ini first — the stubs will happily autocomplete Co\Channel in an environment where it doesn't exist, papering over a real deployment inconsistency.

Look elsewhere or skip when:

• The stack is conventional PHP-FPM, plain queue workers, or Octane on RoadRunner/FrankenPHP. There is nothing to document; the correct decision is not to adopt.
• The team uses only framework-level abstractions and never touches the extension surface directly — a framework's own helper files may already cover the indexed API.
• Nobody is on PhpStorm/Intelephense and static analysis uses a different stub source; verify PHPStan/Psalm coverage before assuming this fills the gap.
• You need a guarantee of support or a vendor SLA. With 519 stars and zero recorded Composer dependents, this is a small-maintainer project. For a zero-logic dev-only package that's an acceptable profile, but it's the reason to keep it strictly in require-dev and never bootstrap it.

How to Pitch It (Stakeholders)

For executives: One Composer command as a dev dependency, Apache-2.0, zero runtime footprint — every method body is empty and nothing is autoloaded, so it cannot affect a build, a deployment, or production behavior. The problem it removes is mundane but daily: Swoole is a C/C++ extension, so its classes, functions, and constants exist nowhere in our source, and engineers work against a red wall of "undefined class" warnings with no parameter hints. Cost is minutes per developer; benefit is faster onboarding to Swoole-based services and fewer debugging detours caused by guessed signatures. The only risks are developer-experience risks — stub/runtime version drift, and a one-time PhpStorm settings change — not operational ones. Ask: approve as a dev dependency with a named owner for version pinning. No architecture review, no ADR, no security sign-off beyond the standard dependency check.

For engineering: composer require --dev swoole/ide-helper, then pin to the installed extension line after confirming php --ri swoole | grep Version. Bump the helper whenever you bump Swoole. PhpStorm users must disable the bundled swoole stubs to avoid "multiple definitions exist" warnings. Do not require or include the stub files — with the extension loaded, redefinition fails; without it, empty bodies do nothing. Keep it out of production via composer install --no-dev.