Hypervel: an async PHP application skeleton on Swoole workers

The skeleton is not the framework

The repository description is one line: the application skeleton for the Hypervel framework. The section titled About This Repository then spells out the division, and this is the first thing to understand.

This repository contains the application skeleton. It provides the default application structure and configuration used when creating a new Hypervel project. The framework source and the first-party packages are maintained in a separate Hypervel components repository.

The issue tracker policy follows the same split, and it is a good sign that it is written down. Use this repository's issues only for problems with the application skeleton's default files, configuration or starter code. Report framework bugs through the components repository's issues, and use its discussions for support questions, feature requests and ideas.

The directory listing is what a Laravel developer would recognise. There is an app/ directory, an artisan file, bootstrap/, config/, database/, public/, resources/, routes/, storage/ and tests/. Alongside them are the files that make it a modern application skeleton: a .env.example, a vite.config.js, a package.json, phpstan.neon for static analysis, phpunit.xml for the test runner, and a .php-cs-fixer.php for code style. There is also a CLAUDE.md.

So this is the part of the framework you copy and then own. Everything that is actually the framework, the container, the ORM integration, the HTTP client, the queue system, lives in the other repository, which is where you should look before deciding anything.

Swoole workers and the coroutine model underneath

The About section explains the execution model, and it is the reason to care about Hypervel at all.

Hypervel runs applications in long-lived Swoole workers, using coroutines to handle requests, background jobs and network operations concurrently. The explanation is concrete: while one coroutine waits for a database query, an HTTP response or other I/O, the worker can continue other work. The README says this concurrency model runs throughout the framework, letting you write familiar sequential PHP while taking advantage of concurrent execution.

That last clause is the design claim, and it is the whole appeal for a PHP shop. The traditional PHP model is one request per process, and the usual answer to an I/O-bound service is more processes or more machines. Long-lived workers with coroutines change the shape of the problem: a worker is not blocked by a slow dependency, so the number of workers you need is driven by CPU work rather than by how long your database takes.

The stated audience is broad and specific at once. Hypervel is built for traditional web applications, APIs, microservices, real-time services, background workers, and applications that spend much of the time waiting on external systems. That last category is the sharpest one, because it is the case where the coroutine model changes the numbers rather than the syntax.

The topics tag the project with hyperf, laravel, php, swoole and coroutine, which places it in a family of ideas rather than alone: an asynchronous runtime with a Laravel-shaped API, following the path that other frameworks have taken.

Creating a project with Composer

The Getting Started section is short because the skeleton is a Composer package, which means the standard create-project command is the whole installation story.

composer create-project hypervel/hypervel example-app

cd example-app
php artisan serve

Once the development server has started, the application is available at http://localhost:8000.

If you want a React front end built with Inertia, the README points to an official React application starter kit, which is another Composer package:

composer create-project hypervel/react-starter-kit example-app

The complete setup instructions live in the installation documentation and the starter kit documentation, both in the components repository under the 0.4 branch.

What the .env.example file tells you about the defaults is worth reading, because it is the shape of a fresh application. The application name is Hypervel, the environment is local, debugging is on, and the URL is http://localhost:8000. The database connection defaults to sqlite, and the commented lines show the MySQL settings. Sessions, the queue, the cache and the rate limiter store all default to the database driver, while the broadcast connection and the mailer default to log, so a fresh install writes notifications to a log file rather than sending anything. Redis is configured at 127.0.0.1 on port 6379 for the parts that use it.

On the front end, the package.json is a private ES module package with Vite as the bundler, Tailwind CSS 4, the laravel-vite-plugin and a @laravel/multiplex package, with build and dev scripts that call vite.

A Laravel-shaped checklist, implemented for coroutines

The feature list is long and deliberately familiar. Read it as the list of things a Laravel developer expects to find and then check the linked documentation for what has been adapted.

There is fast, expressive routing and middleware. There is a dependency injection container and a service provider system. Multiple session and cache stores are supported. Eloquent ORM comes with schema building and database migrations. Background jobs have job batching and task scheduling. Event broadcasting and WebSocket support are there for real-time work. The application layer covers authentication, authorization, validation, notifications, mail and filesystem storage, with Blade templates and Vite integration for the view layer.

Then the four items that are specific to this runtime. There is built-in support for coroutines and for concurrent HTTP requests, which is the point of the whole project. There are persistent database and Redis connection pools, so a long-lived worker reuses connections instead of opening one per request. And there is coroutine-aware testing with a familiar assertion API, which is the piece that decides whether the framework is usable, because a test suite that hangs or interleaves badly under concurrency is worse than no test suite.

Each of those points links to its own documentation page in the components repository, which is where the detail lives. The README here is the index, and the useful thing about an index this complete is that it lets you spot the missing piece early. Nothing in the list is missing, which is unusual for a framework still in a rewrite.

Laravel compatibility is a porting project, not a namespace swap

The Laravel Compatibility section is the part of the README that most deserves a careful reading, because the claim is easy to over-read.

Hypervel aims for Laravel API compatibility wherever it fits. However, Hypervel is not a Laravel clone or drop-in replacement. Many Hypervel components are ports of Laravel packages, adapted for Hypervel's asynchronous runtime, performance requirements and coroutine safety, but the framework itself has its own architecture, features, supported integrations and direction.

The sentence about coroutine safety is the one to sit with. A package written for PHP-FPM assumes one request, one process, and that a function call blocking is fine because it blocks nothing else. In a coroutine, blocking is the thing you are trying to avoid, and a ported package that blocks can stall every other coroutine in that worker. So a port is not a rename, it is a review of every blocking call in the dependency.

The practical consequence is stated next: moving an existing Laravel application or package to Hypervel is a deliberate port, not a namespace replacement, and the porting guide explains what needs to change and why.

So the realistic path for an existing Laravel shop is incremental. A new service written from scratch in Hypervel gets the coroutine model with no porting cost. An existing application is a project, with a document listing the changes, and the README points you to the guide for the details. A team that expects to change a namespace and run is going to be disappointed, and the framework's own documentation is careful not to suggest otherwise.

Read the 0.4 warning before anything else

The first element of the README is a warning block, and it should shape the entire evaluation.

The branch contains the ongoing, unreleased work for the Hypervel 0.4 rewrite. Hypervel 0.4 is not ready for use yet, and APIs, behavior, configuration and package internals may change unexpectedly while the rewrite is still in progress. The README asks that this branch not be used for projects until a beta release is tagged, while inviting bug reports and feedback from anyone experimenting with or testing the rewrite.

The default branch of this repository is 0.4, so the branch you land on by cloning is the unstable one. The stable line lives in the tags: v0.3.24 on 2026-07-02, v0.3.25 on 2026-07-22 and v0.3.26 on 2026-08-14. The repository is not archived and the last push was on 2026-10-20, so the rewrite is active.

If you want to see what the rewrite looks like, the README points to the in-progress 0.4 documentation in the components repository, and to the porting guide for anyone coming from Laravel. Both are on the 0.4 branch, so they describe the moving target rather than a released version.

The licence is MIT, with the LICENSE file in the repository root, so there is no licensing obstacle to experimenting. The obstacle is the churn, and it is self-declared. A framework that tells you not to use it in production until a beta is tagged is being more careful than most, which is a good sign about the maintainers even if it is a bad sign about your schedule.

Editorial conclusion

Hypervel fits a team that wants Laravel-style application code running concurrently on Swoole, that is willing to port rather than swap, and that can wait for a tagged beta. It is the wrong choice for a production project today, because the default 0.4 branch carries an explicit warning that APIs, behavior, configuration and package internals may change unexpectedly and that the branch should not be used for projects until a beta release is tagged. Before adopting, read the porting guide in the components repository, start from the stable 0.3.x tags if you must build now, and confirm that your Swoole and extension environment matches what the installation documentation requires.

Frequently asked questions

Official sources

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