Ext Swoole Laravel Package

Getting Started

This package ships no PHP code. It is a Composer platform shim: its composer.json uses provide/replace to tell Composer that ext-swoole and ext-openswoole are interchangeable. Understanding that one sentence explains everything about how you will use it.

Step 1 — Confirm what your runtime actually has. The shim never installs an extension, so verify first:

php -m | grep -i swoole          # shows swoole or openswoole
php --ri openswoole | head -20   # OpenSwoole version + build options
php --ri swoole | head -20       # Swoole version
composer check-platform-reqs     # what Composer currently thinks you have

Step 2 — Find who is blocking you. Almost every real-world use starts with a failed composer install or composer require complaining about a missing platform extension. Trace it:

composer why ext-swoole
composer why ext-openswoole
composer prohibits ext-swoole 5.1.0   # which package pins which constraint

Step 3 — Read the shim before trusting it. The authoritative version map lives in vendor/upscale/ext-swoole/composer.json:

{
  "name": "upscale/ext-swoole",
  "require": { "php": ">=8.0" },
  "provide": {
    "ext-swoole": "5.1.0",
    "ext-openswoole": "22.1.0"
  }
}

Match the provide version against the constraint that's failing. If a package wants ext-swoole: ^5.1 and this release provides 5.0.x, you need a different tag, not a workaround.

Step 4 — Install it and move on.

composer require upscale/ext-swoole:^5.1

Your first use case is nearly always: a library declares ext-swoole in its requirements, but your Docker image / CI runner / distro ships OpenSwoole. Adding this package satisfies Composer in one line, with a documented, scoped, reviewable change — instead of sprinkling --ignore-platform-req=ext-swoole across every command in your Makefile.

Implementation Patterns

Pattern 1: Unblocking a transitive requirement

You usually don't want to touch a vendor library's composer.json. Add the shim to your root instead, scoped to the major version you actually run:

{
  "require": {
    "upscale/ext-swoole": "^5.1"
  }
}

Then re-resolve just the lock:

composer update upscale/ext-swoole --with-dependencies

This is the pattern to prefer over editing composer.json files in vendor/ (which gets blown away) and over config.platform (which lies to Composer about all extensions, including ext-mbstring, ext-redis, etc.).

Pattern 2: CI matrix — Swoole locally, OpenSwoole in CI

Teams commonly develop against Swoole and deploy on OpenSwoole (or vice versa). The shim makes a single composer.lock installable in both environments:

# .github/workflows/ci.yml
strategy:
  matrix:
    include:
      - php: '8.3'
        ext: swoole-5.1.2
      - php: '8.3'
        ext: openswoole-22.1.0
steps:
  - run: shivammathur/setup-php@v2 ...  # installs the matrix extension
  - run: composer install --no-interaction --prefer-dist

Because the shim provides both names, composer install succeeds identically on both legs. Keep the shim as a require (not require-dev) so it survives --no-dev production installs.

Pattern 3: Docker images that ship OpenSwoole by default

FROM php:8.3-cli

RUN pecl install openswoole-22.1.0 \
 && docker-php-ext-enable openswoole \
 && php -m | grep openswoole

COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --no-scripts --prefer-dist

The image has zero Swoole packages from PECL named swoole, yet composer install succeeds because the shim satisfies the ext-swoole constraint. Verify at build time with composer check-platform-reqs in the Dockerfile — it's cheap insurance that the shim and the installed extension version actually agree.

Pattern 4: Pair the shim with a real runtime adapter

This is the most important pattern. The shim fixes Composer, not PHP. Swoole and OpenSwoole expose different namespaces (Swoole\Coroutine, Swoole\Runtime vs OpenSwoole\Coroutine, OpenSwoole\Runtime), different hook toggles, and different feature sets across majors. Write a bootstrap that detects and aliases:

<?php
// bootstrap.php
$ext = extension_loaded('openswoole') ? 'openswoole' : 'swoole';

if ($ext === 'openswoole' && !class_exists(\Swoole\Coroutine::class)) {
    // Only works if the OpenSwoole build exposes the Swoole namespace aliases.
    // If not, route your code through your own thin abstraction instead.
}

if (!extension_loaded('swoole') && !extension_loaded('openswoole')) {
    fwrite(STDERR, "No Swoole runtime loaded; the composer shim is not the extension.\n");
    exit(1);
}

Prefer a small internal façade (a Runtime class wrapping Coroutine::create, go(), Runtime::enableCoroutine()) over sprinkling class_exists() checks through application code.

Pattern 5: Consuming it from a shared library

If you maintain a package that genuinely works on both runtimes, mirror the technique upstream rather than forcing consumers to add a third dependency:

{
  "require": { "php": ">=8.1" },
  "provide": {
    "ext-swoole": "5.1.0",
    "ext-openswoole": "22.1.0"
  },
  "suggest": {
    "ext-swoole": "Required to run the server (or ext-openswoole)",
    "ext-openswoole": "Required to run the server (or ext-swoole)"
  }
}

Move the requirement to suggest + provide and document the contract. require should stay for things you truly cannot live without.

Pattern 6: Static analysis and IDE stubs

Neither extension's classes are visible to PHPStan/Psalm unless you install stubs. Since the shim contributes no symbols, add one stub set and keep it runtime-agnostic in phpstan.neon:

parameters:
    scanFiles:
        - vendor/swoole/ide-helper/output/swoole/Swoole/functions.php

If your codebase targets OpenSwoole, use that project's IDE helper output instead and make sure the namespace prefix in your source matches what you actually run.

Gotchas and Tips

The shim does not install the extension. composer install with this package on a bare PHP image succeeds, then your app fatals at the first Swoole\... reference. Always pair composer check-platform-reqs with a runtime assertion (php -m) in your health check or entrypoint. This is the single most common failure mode with provide-based packages.

Version pinning is the whole game. The provide version must satisfy the failing constraint — not merely exist. If a library requires ext-swoole: ^5.1 and the shim provides 5.0.3, Composer still fails, and the error message points at ext-swoole, not at the shim. Read vendor/upscale/ext-swoole/composer.json and align with the newest tag.

Release cadence lags upstream. A brand-new Swoole 6.x or OpenSwoole major will not be in the provide map until a new tag ships. Expect a gap between "extension released" and "shim updated." If you need it immediately, vendor a copy of the composer.json with an adjusted provide block (Apache-2.0 permits this) under a path repository — and open an upstream issue while you're at it.

provide is not replace. replace means "this package is that package" and can suppress installation of an actual implementation. Depending on how the shim declares things, verify you aren't accidentally suppressing a real package. Inspect the vendor/upscale/ext-swoole/composer.json keys before assuming semantics.

Do not reach for these instead:

The shim is the narrow, documented version of the same trick — prefer it, and leave the escape hatches for emergencies.

composer.lock staleness. After adding the shim, use composer update upscale/ext-swoole --with-dependencies (or composer update --lock) rather than hand-editing. A lock file that still records ext-swoole as unsatisfied will keep failing in --no-dev production installs even though local dev works.

Debugging toolkit, in order:

composer why-not ext-swoole 5.1.0     # why resolution is blocked
composer prohibits ext-swoole          # inverse dependency tree
composer show upscale/ext-swoole       # what this tag actually provides
composer diagnose                      # catches platform/network oddities
php -r 'var_dump(get_loaded_extensions());'
php --ri openswoole | grep -i version

Runtime divergence is your real risk, not Composer. Coroutine hooks (Runtime::enableCoroutine flags differ), swoole_loader/encoding differences, removed functions between majors, and OpenSwoole's feature subset all survive the shim untouched. Keep an integration smoke test that exercises the coroutine path and runs on both extensions in CI — that test, not the shim, is what actually proves interchangeability.

Dependents: 0, stars: 1. Treat this as an unreviewed, low-traffic package. Read its composer.json in full (it's under 50 lines), pin it to an exact version in composer.json, and commit the lock file. Do not let it float on a * or dev-main constraint.