Swoole Laravel Package

Getting Started

This package is best understood as an API reference/stub layer for Swoole inside a Laravel/Lawoole application, not a runtime framework. It will not make Swoole work on its own — the swoole PHP extension must already be installed, enabled, and version-matched. Treat installation as two separate steps:

# 1. Runtime prerequisite (CLI SAPI only)
pecl install swoole
php -m | grep swoole

# 2. The reference package
composer require lawoole/swoole

Then look at, in this order:

1. composer.json — check the autoload block. If it maps a Lawoole\Swoole\ namespace to src/, import from there. If it only ships stubs/aliases, your IDE and static analyser are the primary consumers.
2. src/ — most likely contains class aliases, IDE helper docblocks, or constants mirroring Swoole\*. Skim for Swoole\Coroutine, Swoole\Http\Server, and Swoole\WebSocket\Server references; those are the surfaces you will touch daily.
3. The package's README/service provider (if any) — check whether it registers a provider. A reference-only package frequently has no provider at all, which is fine.

First real use case: wiring a Swoole HTTP/WebSocket server entry point alongside your normal Laravel bootstrap so you get autocompletion and type hints on $request, $response, and $server inside coroutine callbacks:

use Swoole\Http\Request;
use Swoole\Http\Response;

$server->on('request', function (Request $req, Response $res) {
    $res->header('Content-Type', 'application/json');
    $res->end(json_encode(['ok' => true]));
});

If your IDE resolves those types after composer require, the package is doing its job.

Implementation Patterns

Use it as a type-hint and autocompletion source, not as application logic. The day-to-day value is in making Swoole's native classes legible inside Laravel-shaped code.

Pattern: bridge Swoole callbacks into container-resolved services. Swoole callbacks run outside the normal request lifecycle, so resolve dependencies explicitly rather than relying on facades that assume app() state:

$server->on('request', function (Request $req, Response $res) use ($app) {
    $handler = $app->make(MyRequestHandler::class);
    $res->end($handler->handle($req));
});

Pattern: coroutine-scoped work. Where the package documents or aliases coroutine helpers, prefer explicit Co::run() / go() scopes over sprinkling raw swoole_* functions, so you can swap the implementation in tests:

use Swoole\Coroutine as Co;

Co::run(function () {
    $channel = new Co\Channel(1);
    go(fn () => $channel->push(doWork()));
    $result = $channel->pop();
});

Pattern: static analysis. Add the package's stubs to PHPStan/Psalm bootstrap paths so CI stops complaining about undefined Swoole\* symbols:

# phpstan.neon
parameters:
    scanFiles:
        - vendor/lawoole/swoole/stubs/Swoole.php

(Confirm the actual stub path in vendor/lawoole/swoole/ — this is the one path you should verify rather than guess.)

Pattern: keep framework code coroutine-agnostic. Don't let Lawoole\Swoole types leak into domain classes. Isolate Swoole in an adapter layer (a Server wrapper, a Request mapper) so the bulk of your app stays testable outside a coroutine context.

Integration tip: when mixing with Laravel's queue/event system, remember Swoole workers persist across requests. Any singleton registered in the container survives — which is usually desired, but only if it holds no per-request mutable state.

Gotchas and Tips

• It is a reference package. With 14 stars and a description of "Swoole Api references," expect documentation and stubs, not helpers with behavior. If you need a full coroutine-aware Laravel kernel, that is a different package (e.g. Lawoole's own framework or Swoole Laravel integrations), not this one.
• Extension version drift is the #1 failure mode. Stubs written for Swoole 4.x will silently mislead you on 5.x (removed functions, changed signatures). Pin the extension version in your Docker image and bump the package together with it.
• CLI SAPI only. Swoole does not run under PHP-FPM. If php -m shows swoole in FPM but your artisan command fails, you are testing the wrong binary. Verify with php -r 'var_dump(extension_loaded("swoole"));' from the same CLI you run the server with.
• Coroutine context leakage. Static properties, app() singletons, and globals shared across coroutines cause the classic "user A sees user B's data" bug. Audit any singleton that mutates state per request.
• Silent callback failures. Exceptions thrown inside on('request', ...) often die without a stack trace reaching your Laravel log. Wrap the body in try/catch and log explicitly to a Swoole-safe logger.
• Debugging: Swoole\Coroutine::getCid() (returns -1 outside a coroutine) is your fastest sanity check that code is running where you think it is. Pair with Swoole\Coroutine::getBackTrace() when a coroutine hangs.
• Testing: Swoole code is awkward to unit test. Push logic out of callbacks into plain classes, and only integration-test the thin Swoole shell. swoole.use_shortname = Off in php.ini forces you to use namespaced classes, which makes the stubs more useful and the intent clearer.
• Extension point to look for: if the package publishes config or stub files, publish them (php artisan vendor:publish) and commit the result — you will want to patch signatures locally when the upstream stubs lag the extension.
• Maintenance risk: low star count means no guaranteed updates for new Swoole releases. Budget time to maintain your own stubs or pin aggressively; do not build core infrastructure that depends on this package releasing a fix.