Hyperf: a coroutine PHP framework for microservices and middleware

What Hyperf is for, and who ends up using it

Hyperf is a PHP CLI framework rather than an FPM application framework. The README describes it as a coroutine framework for building microservices or middleware, and the README lists coroutine-compatible gRPC, JSON RPC, WebSocket, AMQP and OpenTracing components alongside the framework itself. That combination points at a specific audience: teams running PHP as a long-lived process behind an RPC boundary, a gateway or a message consumer, where the process is expected to stay up and serve many concurrent requests.

The README is explicit that Hyperf is still a PHP framework, and lists the packages a PHP developer expects: middleware, an event manager, an Eloquent ORM with coroutine optimization and model cache, translation, validation and view engines including Blade, Smarty, Twig, Plates and ThinkTemplate. So the pitch is not that you leave PHP conventions behind. It is that the conventions run inside a coroutine server instead of a fresh process per request.

The design goal is stated as an equation: hyperspeed plus flexibility. Hyperspeed comes from Swoole and Swow coroutines. Flexibility comes from the dependency injection component, which the README claims makes components and classes pluggable and meta-programmable. Those are the two claims worth testing against your own workload.

How the coroutine server, DI container and AOP fit together

The architecture is described in the README as a combination of coroutines, dependency injection, events, annotations and AOP. The dependency injector is the part that carries the AOP support, and the README frames that as the mechanism that keeps components pluggable. In practice this means a class can be replaced or wrapped at the container level without editing its callers, which is the same idea as aspect-oriented middleware in other ecosystems.

Around that core, Hyperf ships coroutine-compatible clients rather than leaving them to the user. The README lists MySQL, Redis, a WebSocket server and client, JSON RPC server and client, gRPC server and client, a Zipkin/Jaeger OpenTracing client, a Guzzle HTTP client, Elasticsearch, Consul, ETCD, AMQP, Apollo and Aliyun ACM configuration centers, an ETCD configuration center, a token bucket limiter, a universal connection pool, a circuit breaker, Swagger, Snowflake, a simple Redis MQ, RabbitMQ, NSQ, Nats, a seconds-level crontab and custom processes.

The stated reason for shipping all of that is that developers can avoid writing coroutine-compatible versions of these libraries themselves. That is the real architectural bet: the framework absorbs the compatibility work so application code does not have to. The cost is that the framework's version of a client is the one you use, and the README does not describe an escape hatch for a library it does not cover.

Installing Hyperf and serving a first route

The README states the operating environment as Linux, OS X, Cygwin, WSL or Windows, with PHP 8.1+ and Swoole 5.0+ or Swow 1.4+. Those are the two runtime extensions to install before anything else, since the framework is a CLI server rather than an FPM application.

The README does not include a composer create-project line for the framework, so the concrete starting point it does give is the ecosystem: the Nano distribution, described as a zero-config, no-skeleton minimal Hyperf distribution that lets you build an application from a single PHP file. It is listed at github.com/hyperf/nano, and the README does not spell out its install command.

What the README does show is how the framework is exercised once running. Its performance section uses wrk against the local server on port 9501.

wrk -c 1024 -t 8 http://127.0.0.1:9501/

That command is the README's own benchmark invocation, and it is the clearest statement in the repository of the address a running Hyperf server answers on. If you point a client at the same address and get a response, the coroutine server is up. If you do not, check the PHP version and the Swoole or Swow extension first, because both are hard requirements in the README rather than optional accelerators.

Where Hyperf is the wrong tool

The clearest limitation is the runtime. Hyperf requires PHP 8.1 or newer and Swoole 5.0+ or Swow 1.4+. A host that only offers PHP-FPM, or an environment where you cannot install a PHP extension, rules the framework out entirely. This is not a tuning detail you can work around in configuration.

The second limitation is the coroutine model itself. Code that relies on per-request global state behaves differently when many requests share one process. The README does not document a migration path for such code, and it does not document rollback or a compatibility mode. The framework's answer is the set of coroutine-compatible clients it ships, which implies the expectation that you use those clients rather than arbitrary libraries.

The third is scope. Hyperf is positioned for microservices and middleware. If you are building a small content site with a handful of pages, the coroutine server, the connection pool, the circuit breaker and the tracing client are all overhead you carry without using. The README's own framing, that the framework was privately used by medium and large internet companies for multiple services before its 2019-06-20 public release, describes the intended scale.

Hyperf compared with Laravel and other PHP frameworks

The comparison people actually search for is Hyperf against Laravel, and the difference is not the feature list. Laravel's default execution model is a fresh process per request through FPM. Hyperf's execution model is a coroutine server that keeps the process alive and handles concurrent requests inside it. Everything else follows from that: the connection pool exists because connections outlive a request, the token bucket limiter exists because limits are shared across coroutines, and the circuit breaker exists because a failing downstream is hit by many coroutines at once.

The two frameworks do overlap in surface area. Hyperf provides an Eloquent ORM, middleware, validation, translation and Blade among its view engines, so a Laravel developer will recognize much of the application layer. The README also states that all core components strictly follow PSR standards and can be used in other frameworks, which means the relationship is not strictly either-or: a Hyperf component can be pulled into a PSR-compatible application.

The practical difference to weigh is operational. Laravel gives you a deployment story that works on almost any PHP host. Hyperf gives you a long-running process that needs supervision, extension support and a host that permits it. Choose on the deployment target first, then on the feature set.

Maintenance cadence, licence and upgrade cost

The repository is not archived, and the last push was on 2026-10-23. The most recent releases listed are v3.1.73 on 2026-10-14, v3.2.4 on 2026-08-10 and v3.2.3 on 2026-07-30. The cadence of those releases, across two release lines, suggests patch releases arrive often enough that pinning an exact version and reading the changelog before moving is the sensible habit.

The repository carries CHANGELOG.md plus per-major changelogs up to CHANGELOG-3.2.md, so upgrade notes exist per release line. The README does not document a rollback procedure or a downgrade path, and it does not state a support window for older major versions. That is a gap worth knowing about before you plan an upgrade: the changelog tells you what changed, not what to do if the change breaks you.

Licensing is MIT, per the repository. MIT permits commercial use and modification with the licence and copyright notice retained. This is a description of the licence text, not legal advice; if your organisation has policies about bundled dependencies, the repository also carries a licenses.md file at the top level.

Editorial conclusion

Adopt Hyperf when you are building long-running PHP services such as RPC backends, gateways or queue consumers and you can run Swoole 5.0+ or Swow 1.4+ on your hosts. Do not adopt it for a conventional shared-hosting site or a codebase whose libraries hold per-request global state, because the coroutine model will surface that state as cross-request bugs. Before committing, verify that every dependency you need has a coroutine-compatible client in the framework, and check the CHANGELOG-3.2.md file for the changes between v3.2.4 and the version you pin.

Frequently asked questions

Official sources

1. hyperf/hyperf on GitHub
2. License: MIT
3. Project website
4. README
5. Releases