README

Swoole is a PHP extension written in C/C++, so its classes, functions, and constants don't exist as PHP source code anywhere in your project. Without help, your IDE can't see them: no autocompletion, no parameter hints, no inline documentation, and plenty of "undefined class" warnings.

This package fixes that. It provides fully documented stub files for everything Swoole exposes — every class, method, function, and constant, with accurate signatures, native type declarations, and PHPDoc descriptions. Once it's installed, IDEs like PhpStorm and VS Code (with a PHP language server such as Intelephense) pick up the stubs automatically and give you the same editing experience you'd get with a pure-PHP library.

The stubs under src/swoole/ contain no real logic: method bodies are empty, or hold a few lines of explanatory pseudocode (see Reading the docblocks). Nothing is autoloaded, so the package has zero runtime footprint.

Table of contents

• Installation
  • Choosing a version
• Requirements
• IDE and tool setup
• Best practices
• What's included
  • Features that depend on build options
• Reading the docblocks
• PHP configuration settings
• Contributing
• License

Installation

Install it with Composer as a dev dependency:

composer require --dev swoole/ide-helper

Since the package is only there to assist your IDE, it doesn't belong in production; --dev keeps it out of composer install --no-dev deployments.

Choosing a version

Releases of this package mirror Swoole releases: version 6.2.3 of this package documents Swoole v6.2.3. Note that this package's tags have no v prefix, while Swoole's do. For the most accurate results, use the release that matches the Swoole version you actually run. You can check your installed version with:

php --ri swoole | grep Version

Then require the matching release, e.g.:

composer require --dev swoole/ide-helper:~6.2.3

The ~6.2.3 constraint installs the newest 6.2.x release that is 6.2.3 or later, so you pick up documentation fixes made in later patch releases while staying on the same minor line as your Swoole extension. To pin one exact release instead, drop the ~ (swoole/ide-helper:6.2.3).

The master branch tracks the latest Swoole minor line (currently 6.2.x). Older minor lines are released from their own maintenance branches (e.g. 6.1.x), so a constraint like ~6.1.10 keeps working for them. To use the latest unreleased stubs from the master branch instead:

composer require --dev swoole/ide-helper:dev-master

Requirements

Swoole 6.2 requires PHP 8.2 or later, and so do these stubs: they use PHP 8.2 syntax in their declarations and are checked against PHP 8.2 through 8.5 in CI. Set your IDE's or static analyzer's PHP language level to 8.2 or later so it can parse them.

If you're on PHP 8.1 (and therefore on Swoole 6.1 or older), use the matching older release line of this package instead, e.g. composer require --dev swoole/ide-helper:~6.1.10.

IDE and tool setup

• PhpStorm: PhpStorm ships its own (less complete) Swoole stubs, which conflict with this package and cause "multiple definitions exist" warnings. Go to Settings → PHP, open the PHP Runtime tab, expand PECL, and uncheck swoole, so this package becomes the single source of truth.
• VS Code (Intelephense): Intelephense indexes vendor/ automatically, so no setup is needed. Its own Swoole stubs are off by default; if you added swoole to the intelephense.stubs setting, remove it to avoid duplicate definitions.
• PHPStan / Psalm: when the Swoole extension isn't loaded in the PHP process that runs the analyzer, point the analyzer at vendor/swoole/ide-helper/src/swoole (PHPStan's scanDirectories option, or Psalm's element), so it knows the Swoole symbols exist.

Best practices

• Keep it a dev dependency. The stubs are for your editor only. They declare no autoloading and execute nothing, but there's still no reason to ship them to production.
• Upgrade the helper when you upgrade Swoole. Signatures and available symbols change between Swoole releases; a mismatched helper version means your IDE may suggest methods that don't exist in your runtime (or miss ones that do).
• Don't require/include the stub files, and don't add them to an autoloader or a preload script. If the Swoole extension is loaded, redefining its classes would fail; if it isn't, empty method bodies would do nothing useful anyway. Just let Composer install the package and let your IDE index it.

What's included

• src/swoole/ — stubs for everything implemented in C/C++ by the Swoole extension:
  • all classes under the Swoole\ namespace (one file per class, e.g. Swoole\Coroutine\Http\Client);
  • global swoole_*() functions;
  • SWOOLE_* constants;
  • short class aliases like Co\Channel (active when the swoole.use_shortname ini directive is on).
• src/swoole_library/ — the PHP source of Swoole Library, the userland companion code that ships inside the extension (loaded when swoole.enable_library is on). Unlike the stubs, this is real, runnable code: a verbatim copy of the Swoole Library release bundled with the matching Swoole version, included so your IDE can index these classes too.

Features that depend on build options

Some Swoole features exist only when the extension is built with a particular configuration option. The stubs declare them unconditionally, so your IDE offers them even if your Swoole build doesn't include them; each one's docblock says what it needs. For example:

• Swoole\Thread and the rest of the Swoole\Thread\ namespace: PHP compiled with Zend Thread Safety (ZTS) enabled, and Swoole installed with --enable-swoole-thread.
• The swoole_native_curl_*() functions and the SWOOLE_HOOK_NATIVE_CURL hook flag: --enable-swoole-curl.
• The coroutine-friendly PDO hook flags (SWOOLE_HOOK_PDO_PGSQL, SWOOLE_HOOK_PDO_ODBC, SWOOLE_HOOK_PDO_ORACLE, SWOOLE_HOOK_PDO_SQLITE, SWOOLE_HOOK_PDO_FIREBIRD): --enable-swoole-pgsql, --with-swoole-odbc, --with-swoole-oracle, --enable-swoole-sqlite, and --with-swoole-firebird respectively.
• Running file operations through io_uring (a Linux facility for asynchronous I/O), and the SWOOLE_IOURING_* constants: --enable-iouring (or --with-liburing-dir).
• The experimental "stdext" module (calling methods directly on plain strings, arrays, and streams, plus functions such as swoole_typed_array()): --enable-swoole-stdext.

Reading the docblocks

Besides the standard PHPDoc tags, the stubs use a few conventions you'll see in your IDE's hover popups:

• @since X.Y.Z — the Swoole version that added the symbol.
• @deprecated X.Y.Z — still available, but deprecated since that version; a @see tag points at what to use instead.
• @alias — the symbol is an alias of another one (or has one), e.g. Swoole\Table::del() and Swoole\Table::delete(). Short class names such as Co\Channel are noted on the real class, and only exist when the swoole.use_shortname ini directive is on.
• @readonly — the property can be read but not written.
• @not-serializable — objects of the class can't be serialized.
• @pseudocode-included — the method body contains PHP code that explains what the built-in method does. It's for reading only; the real implementation is in C/C++.
• When a method's or function's signature changed between Swoole versions, its docblock shows the old and new signatures.
• Usage examples are written as fenced ```php code blocks inside the description, so IDEs render them with syntax highlighting.

PHP configuration settings

Swoole's behavior can be tuned with the following ini directives (as of Swoole 6.2.3):

"php.ini only" directives can't be changed with ini_set() at runtime; set them in a php.ini file, or with php -d on the command line.

• swoole.enable_library: Load Swoole Library (the PHP code under src/swoole_library/) or not.
• swoole.enable_fiber_mock: Make each coroutine look like a PHP Fiber to tools that watch Fibers (e.g. debuggers and profilers), so they can follow coroutine switches. Turning on swoole.blocking_detection or swoole.profile turns this on automatically.
• swoole.enable_preemptive_scheduler: Enable the preemptive scheduler or not, which stops a CPU-intensive coroutine from running forever without letting others run. It can also be turned on at runtime through the enable_preemptive_scheduler option of Swoole\Coroutine::set(). To understand how it works, please check examples under section "CPU-intensive job scheduling" of repository deminy/swoole-by-examples.
• swoole.display_errors: Display/hide error information from Swoole.
• swoole.use_shortname: Support short names or not. Short names are all the aliases listed in file src/swoole/shortnames.php.
• swoole.socket_buffer_size: The default buffer size (in bytes) of the sockets Swoole creates, including the ones between the master process and the worker processes of a Swoole server.
• swoole.blocking_detection: Part of Swoole's built-in tracer. When on, Swoole prints a warning with a PHP backtrace whenever a built-in PHP function blocks a coroutine for longer than swoole.blocking_threshold without letting other coroutines run (e.g. a blocking call that isn't hooked by Swoole\Runtime::enableCoroutine()).
• swoole.blocking_threshold: How long (in microseconds) a blocking call may take before swoole.blocking_detection reports it.
• swoole.profile: Part of Swoole's built-in tracer. Enables profiling through functions swoole_tracer_prof_begin() and swoole_tracer_prof_end().
• swoole.leak_detection: Part of Swoole's built-in tracer. Enables memory leak detection through function swoole_tracer_leak_detect().

Contributing

Bug reports and pull requests are welcome. If a stub doesn't match Swoole, please cite the relevant code in swoole-src at the matching release tag (e.g. v6.2.3). A few rules:

• Compare against swoole-src's actual C/C++ source. Don't use the .stub.php files shipped in swoole-src as a source; they aren't reliable for this work.

• Don't hand-edit src/swoole_library/; it's copied from the matching swoole/library release.

• Inline declarations must be valid PHP 8.2 syntax (the minimum PHP version Swoole 6.2 supports).

• Before submitting, run the same checks as CI:

  # Coding style.
  docker run -q --rm -v "$(pwd):/project" -w /project -i jakzal/phpqa:php8.5-alpine php-cs-fixer fix --dry-run
  # Syntax, under the oldest supported PHP version (newer versions accept syntax that PHP 8.2 rejects).
  docker run -q --rm -v "$(pwd):/project" -w /project -i jakzal/phpqa:php8.2-alpine phplint src

The full set of stub-writing conventions is in CLAUDE.md.

License

This package is licensed under the Apache License 2.0.