feat: framework refactor + decouple from Hyperf

[binaryfire]

Hi @albertcht. This isn't ready yet but I'm opening it as a draft so we can begin discussions and code reviews. The goal of this PR is to refactor Hypervel to be a fully standalone framework that is as close to 1:1 parity with Laravel as possible.

Why one large PR

Sorry about the size of this PR. I tried spreading things across multiple branches but it made my work a lot more difficult. This is effectively a framework refactor - the database package is tightly coupled to many other packages (collections, pagination, pool) as well as several support classes, so all these things need to be updated together. Splitting it across branches would mean each branch needs multiple temporary workarounds + would have failing tests until merged together, making review and CI impractical.

A single large, reviewable PR is less risky than a stack of dependent branches that can't pass CI independently.

---

Reasons for the refactor

1. Outdated Hyperf packages

It's been difficult to migrate existing Laravel projects to Hypervel because Hyperf's database packages are quite outdated. There are almost 100 missing methods, missing traits, it doesn't support nested transactions, there are old Laravel bugs which haven't been fixed (eg. JSON indices aren't handled correctly), coroutine safety issues (eg. model unguard(), withoutTouching()). Other packages like pagination, collections and support are outdated too. Stringable was missing a bunch of methods and traits, for example. There are just too many to PR to Hyperf at this point.

2. Faster framework development

We need to be able to move quickly and waiting for Hyperf maintainers to merge things adds a lot of friction to framework development. Decoupling means we don't need to work around things like PHP 8.4 compatibility while waiting for it to be added upstream. Hyperf's testing package uses PHPUnit 10 so we can't update to PHPUnit 13 (and Pest 4 in the skeleton) when it releases in a couple of weeks. v13 has the fix that allows RunTestsInCoroutine to work with newer PHPUnit versions. There are lots of examples like this.

3. Parity with Laravel

We need to avoid the same drift from Laravel that's happened with Hyperf since 2019. If we're not proactive with regularly merging Laravel updates every week we'll end up in the same situation. Having a 1:1 directory and code structure to Laravel whenever possible will make this much easier. Especially when using AI tools.

Most importantly, we need to make it easier for Laravel developers to use and contribute to the framework. That means following the same APIs and directory structures and only modifying code when there's a good reason to (coroutine safety, performance, type modernisation etc).

Right now the Hypervel codebase is confusing for both Laravel developers and AI tools:

• Some classes use Hyperf classes directly, some extend them, some replace them. You need to check multiple places to see what methods are available
• Some Hyperf methods have old (2019) Laravel signatures while some overridden ones have new ones
• The classes are in different locations to Laravel (eg. there's no hypervel/contracts package, the Hyperf database code is split across 3 packages, the Hyperf pagination package is hyperf/paginator and not hyperf/pagination)
• The tests dir structure and class names are different, making it hard to know what tests are missing when comparing them to Laravel's tests dir
• There are big differences in the API (eg. static::registerCallback('creating') vs static::creating())
• The mix of Hyperf ConfigProvider and Laravel ServiceProvider patterns across different packages is confusing for anyone who doesn't know Hyperf
• There are big functional differences eg. no nested database transactions

This makes it difficult for Laravel developers to port over apps and to contribute to the framework.

4. AI

The above issues mean that AI needs a lot of guidance to understand the Hypervel codebase and generate Hypervel boilerplate. A few examples:

• Models have trained extensively on Laravel code and expect things to have the same API. Generated boilerplate almost always contains incompatible Laravel-style code which means you have to constantly interrupt and guide them to the Hypervel-specific solutions.
• Models get confused when they have to check both Hypervel and Hyperf dependencies. They start by searching for files in the same locations as Laravel (eg. hypervel/contracts for contracts) and then have to spend a lot of time grepping for things to find them.
• The inheritance chain causes major problems. Models often search Hypervel classes for methods and won't remember to search the parent Hyperf classes as well.

And so on... This greatly limits the effectiveness of building Hypervel apps with AI. Unfortunately MCP docs servers and CLAUDE.md rules don't solve all these problems - LLMs aren't great at following instructions well and the sheer volume of Laravel data they've trained on means they always default to Laravel-style code. The only solution is 1:1 parity. Small improvements such as adding native type hints are fine - models can solve that kind of thing quickly from exception messages.

---

What changed so far

New packages

Package	Purpose
hypervel/database	Full illuminate/database port
hypervel/collections	Full illuminate/collections port
hypervel/pagination	Full illuminate/pagination port
hypervel/contracts	Centralised cross-cutting contracts (same as illuminate/contracts)
hypervel/pool	Connection pooling (internalised from hyperf/pool)
hypervel/macroable	Moved Macroable to a separate package for Laravel parity

Removed Hyperf dependencies so far

• hyperf/database
• hyperf/database-pgsql
• hyperf/database-sqlite
• hyperf/db-connection
• hyperf/collection
• hyperf/stringable
• hyperf/tappable
• hyperf/macroable
• hyperf/codec

Database package

The big task was porting the database package, making it coroutine safe, implementing performance improvements like static caching and modernising the types.

• Ported from Laravel 12
• Added 50+ missing methods: whereLike, whereNot, groupLimit, rawValue, soleValue, JSON operations, etc.
• Full Schema builder parity including schema states
• Complete migration system (commands are still using Hyperf generators for now)
• Both Hyperf and Hypervel previously used global PHPStan ignores on database classes. I removed these and fixed the underlying issues - only legitimate "magic" things are ignored now.

Collections package

• Full Laravel parity across all methods
• Modernised with PHP 8.2+ native types
• Full LazyCollection support
• Proper generics for static analysis

Contracts package

• Centralised cross-cutting interfaces (like illuminate/contracts)
• Clean dependency boundaries - packages depend on contracts, not implementations
• Enables proper dependency inversion across the framework

Support package

• Removed hyperf/tappable, hyperf/stringable, hyperf/macroable, hyperf/codec dependencies
• Freshly ported Str, Env and helper classes from Laravel
• Consistent use of Hypervel\Context wrappers (will be porting hyperf/context soon)
• Fixed some existing bugs (eg. Number::useCurrency() wasn't actually setting the currency)

Coroutine safety

• withoutEvents(), withoutBroadcasting(), withoutTouching() now use Context instead of static properties
• Added UnsetContextInTaskWorkerListener to clear database context in task workers
• Added Connection::resetForPool() to prevent state leaks between coroutines
• Made DatabaseTransactionsManager coroutine-safe
• Comprehensive tests verify isolation

---

Benefits

1. Laravel 1:1 API parity - code from Laravel docs works directly
2. AI compatibility - AI assistants generate working Hypervel code
3. Easier contributions - Laravel devs can contribute without learning Hyperf
4. Reduced maintenance - fewer external dependencies to track and update
5. Modern PHP - native types throughout, PHP 8.2+ patterns
6. Better static analysis - proper generics and type hints
7. Coroutine safety - verified isolation with comprehensive tests

---

Testing status so far

• PHPStan passes at level 5
• All existing tests pass
• Coroutine isolation tests verify safety

---

What's left (WIP)

• Port the remaining Hyperf dependencies
• Port the full Laravel and Hyperf test suites
• Documentation updates
• Your feedback on architectural decisions

---

The refactor process

Hyperf's Swoole packages like pool, coroutine, context and http-server haven't changed in many years so porting these is straightforward. A lot of the code can be simplified since we don't need SWOW support. And we can still support the ecosystem by contributing any improvements we make back to Hyperf in separate PRs.

Eventually I'll refactor the bigger pieces like the container (contextual binding would be nice!) and the config system (completely drop ConfigProvider and move entirely to service providers). But those will be future PRs. For now the main refactors are the database layer, collections and support classes + the simple Hyperf packages. I'll just port the container and config packages as-is for now.

---

Let me know if you have any feedback, questions or suggestions. I'm happy to make any changes you want. I suggest we just work through this gradually, as an ongoing task over the next month or so. I'll continue working in this branch and ping you each time I add something new.

[binaryfire]

@albertcht To illustrate how much easier it will be to keep Hypervel in sync with Laravel after this refactor, I asked Claude how long it would take to merge laravel/framework#58461 (as an example) into this branch. This is what it said:

Once the Laravel database tests are ported to Hypervel, incorporating Laravel PRs becomes straightforward:

  1. Fetch the PR diff with `gh pr diff <number> --repo laravel/framework`
  2. Apply the same changes to the equivalent Hypervel files (usually just namespace changes from `Illuminate` → `Hypervel`)
  3. Run the ported tests to verify the behavior matches

  The main work is already done - the logic is identical, just namespaced differently.

  The PR I just looked at would have taken ~5 minutes to apply:
  
  - Add `selectExpression()` method
  - Add two `elseif` checks in `select()` and `addSelect()`
  - Add a type assertion in the types file
  - Run existing tests

So just 5-10 minutes of work with the help of AI tooling! Merging individual PRs is inefficient - merging releases would be better. I can set up a Discord channel where new releases are automatically posted via webhooks. Maybe someone in your team can be responsible for monitoring that channel's notifications and merging updates ever week or 2? I'll only be 1-2 hours of work once the codebases are 1:1.

We should be diligent about staying on top of merging updates. Otherwise we'll end up in in the same as Hyperf - i.e. the codebase being completely out of date with the current Laravel API.

[albertcht]

Hi @binaryfire ,

Thank you for submitting this PR and for the detailed explanation of the refactor. After reading through it, I strongly agree that this is the best long-term direction for Hypervel.

Refactoring Hypervel into a standalone framework and striving for 1:1 parity with Laravel will indeed solve the current issues regarding deep coupling with Hyperf, maintenance difficulties, outdated versions, and inefficient AI assistance. While this is a difficult step, it is absolutely necessary for the future of the project.

Regarding this refactor and the planning for the v0.4 branch, I have a few thoughts to verify with you:

• Scope of the v0.4 Refactor: We should clearly define the expected boundaries for the v0.4 branch. Is the plan to remove all Hyperf package dependencies within v0.4? I personally lean towards this approach—if we are refactoring, converting all Hyperf packages to native Hypervel packages would be the cleaner and more sustainable choice in the long run.

• Database Stability Testing: The database packages are critical and logically complex components of the framework. Before the official v0.4 release, we need to ensure we allocate sufficient time for extensive testing on this part—including the transactions you mentioned and various edge cases—to guarantee data correctness and safety.

• Documentation of Breaking Changes: Obviously, v0.4 will contain a significant number of breaking changes. Throughout the development process, we need to fully document these changes as we go so we can provide a detailed Upgrade Guide upon release to lower the migration barrier for users.

• ConfigProvider Support: Just to confirm—based on your description, we will not be removing support for ConfigProvider in v0.4 yet, correct? (Keeping it during this transition phase seems reasonable until the Container and Config systems are fully refactored).

• Core Component Performance: Regarding future refactors for components like Container, Events, Routes, and HTTP-Server—beyond the primary goal of coroutine safety, I also want to emphasize the importance of benchmark testing. These are the core components of Hypervel and are critical for performance. I hope that while modernizing the architecture, the new refactors will not lead to any performance regression.

Thank you again for dedicating so much effort to driving this forward; this is a massive undertaking. Let's move forward gradually on this branch with ongoing Code Reviews.

[binaryfire]

Hi @albertcht

Thanks for the detailed response! I'm glad we're aligned on the direction. Let me address each point:

• Scope of v0.4: I agree - let's do a complete removal of all Hyperf dependencies in v0.4. If we're refactoring, doing it all at once is cleaner than maintaining two architectures in parallel. I'm working on this full-time so I can move quickly - I estimate 3-4 months for the complete port including Container, Config, Console, Router, HTTP Server, everything.

• ConfigProvider: Actually, I now plan to remove ConfigProvider entirely in v0.4 as part of the complete port. Since we're going all-in on Laravel parity, moving fully to Service Providers makes sense now rather than later.

• Database Stability: Completely agree - stability and code quality are my top priorities. This is one of the reasons I made that PR to increase PHPStan to level 5. For testing, I'm porting the full Laravel test suite for each package to tests/{PackageName}/Laravel. This gives us all of Laravel's test coverage, and by keeping them in a separate directory instead of mixing them with our own tests, it's easy to see what's missing when comparing against Laravel's test directory. I'm working through the database tests now.

• Performance: Don't worry - I'm a bit obsessed with performance and optimisation 😄 Whenever I port a Laravel package, I always review Hyperf's implementation first to incorporate any performance optimisations they've made, as well as looking for new opportunities in the ported code (like the static caching I added to the database package). And yes, we should definitely run benchmarks before release to catch anything that may have been missed.

• Breaking Changes: Since the end state is 1:1 Laravel API parity, I think the upgrade guide becomes simpler than documenting every individual change. It's essentially: "Hypervel now matches Laravel's API exactly, with these Swoole-specific exceptions." Documenting changes as I go would slow things down significantly given how massive the scope of this refactor is. I suggest we figure out the best way to communicate the breaking changes after the refactor is complete, once we have a clear picture of exactly what the exceptions are.

• Review Process: Rather than leaving the review until the end, I'll ping you when each package is fully complete (src + tests) so you can review it. That way our work is progressive and spread out rather than one massive review at the end.

Let me know your thoughts!

[binaryfire]

Hi @albertcht. The hypervel/database package is ready for review. Could you take a look when you have time?

All the Laravel tests have been ported over and are passing (the unit tests, as well as the integration tests for MySQL, MariaDB, Postgres and SQLite). I've implemented Context-based coroutine safety, static caching for performance and modernised all the types. The code passes PHPStan level 5. Let me know if there's anything I've missed, if you have any ideas or you have any questions.

The other packages aren't ready for review yet - many of them are mid-migration and contain temporary code. So please don't review the others yet :) I'll let you know when each one is ready.

A few points:

• The ConfigProvider, Hyperf-style listeners and Hyperf-based commands are still there for now. I'll remove those once the necessary dependencies are ported.
• Given that our goal is 1:1 parity with Laravel, several things have changed. For example, model events are no longer class-based. They are the same string-based events that Laravel uses. I'll be updating the events package to be 1:1 with Laravel too.

[albertcht]

add Prohibitable trait here?

[binaryfire]

@albertcht Done. I'll be re-working these commands once I've ported illuminate/console, but no harm in adding it now too.

[albertcht]

add Prohibitable trait here?

[binaryfire]

@albertcht Done

[albertcht]

add Prohibitable trait here?

[binaryfire]

@albertcht Done

[albertcht]

add Prohibitable trait here?

[binaryfire]

@albertcht Done

[albertcht]

change to Hypervel's Prohibitable here?

[binaryfire]

@albertcht Done