Skip to content

feat: framework refactor + decouple from Hyperf#349

Draft
binaryfire wants to merge 1737 commits intohypervel:0.4from
binaryfire:feature/hyperf-decouple
Draft

feat: framework refactor + decouple from Hyperf#349
binaryfire wants to merge 1737 commits intohypervel:0.4from
binaryfire:feature/hyperf-decouple

Conversation

@binaryfire
Copy link
Contributor

@binaryfire binaryfire commented Jan 26, 2026

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.

EDIT: New comments are getting lost in the commit history so linking them here:

New hypervel/container package ready for review

See: #349 (comment)

New hypervel/context, hypervel/coordinator, hypervel/coroutine, hypervel/engine, hypervel/pool& hypervel/redis packages ready for review

See: #349 (comment)

New hypervel/database package ready for review

See: #349 (comment)

@binaryfire binaryfire marked this pull request as draft January 26, 2026 03:51
@binaryfire
Copy link
Contributor Author

binaryfire commented Jan 26, 2026

@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 albertcht added the breaking-change Breaking changes label Jan 27, 2026
@albertcht
Copy link
Member

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
Copy link
Contributor Author

binaryfire commented Jan 28, 2026

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 binaryfire force-pushed the feature/hyperf-decouple branch from 8cec3bf to bfffa6f Compare January 30, 2026 06:48
@binaryfire
Copy link
Contributor Author

binaryfire commented Feb 2, 2026

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.

@@ -6,9 +6,9 @@

use Hyperf\Command\Concerns\Prohibitable;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

change to Hypervel's Prohibitable here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@albertcht Done

@binaryfire binaryfire force-pushed the feature/hyperf-decouple branch from 80f3ef2 to 94c115e Compare February 6, 2026 07:25
@binaryfire
Copy link
Contributor Author

binaryfire commented Feb 8, 2026

@albertcht The following packages are ready for review. I've modernised typing, optimised the code, added more tests (including integration tests) and fixed several bugs.

  • hypervel/context
  • hypervel/coordinator
  • hypervel/coroutine
  • hypervel/engine
  • hypervel/pool
  • hypervel/redis

I've also ported https://github.com/friendsofhyperf/redis-subscriber into the Redis package. The subscription methods were all blocking - now they're coroutine friendly. With the previous implementation, if you wrapped subscribe() in go() it wouldn't block the calling coroutine. But yhe problem is what happens inside that coroutine. phpredis's subscribe() blocks the coroutine it's called in for the entire subscription lifetime, which means:

  1. Pool connection exhaustion: Each subscriber holds a pool connection that's never released until the subscription ends. With the default pool size, a few long-lived subscribers can starve other Redis operations.

  2. Shutdown deadlock: As mentioned in [FEATURE] Use https://openswoole.com/article/redis-swoole-pubsub for redis connection hyperf/hyperf#4775, when the worker exits, the subscribe coroutine is stuck on recv() with no way to interrupt it from PHP, so the worker hangs. The socket-based subscriber makes this solvable — because we control the socket, we can close it from another coroutine to break the recv loop. I added a shutdown watcher (CoordinatorManager::until(WORKER_EXIT)) to do exactly that, giving us clean worker exit.

  3. No dynamic channel management: phpredis's callback API doesn't support subscribing/unsubscribing after the initial call. The new Subscriber class supports subscribe(), unsubscribe(), psubscribe(), punsubscribe() as separate operations on the same connection.

The approach follows the same pattern suggested in hyperf/hyperf#4775 (https://github.com/mix-php/redis-subscriber, which Deeka ported to https://github.com/friendsofhyperf/components). I.e. a dedicated raw socket connection with RESP protocol, coroutine-based recv loop, and Channel for message delivery. It's the same way go-redis handles this.

This is a good article re: this issue for reference: https://openswoole.com/article/redis-swoole-pubsub

@binaryfire binaryfire mentioned this pull request Feb 9, 2026
@binaryfire
Copy link
Contributor Author

binaryfire commented Feb 12, 2026

Hi @albertcht! The new hypervel/container package is ready for review.

This is Swoole-optimised version of Laravel's IoC Container, replacing Hyperf's container. The goal: give Hypervel the complete Laravel container API while maintaining performance parity with Hyperf's container and full coroutine safety for Swoole's long-running process model.

Why replace Hyperf's container?

Hyperf's container is minimal. It exposes get(), has(), make(), set(), unbind(), and define(). That's the entire public API. It has no support for:

  • Contextual bindings (when()->needs()->give())
  • Resolving callbacks (resolving(), afterResolving(), beforeResolving())
  • Service extenders (extend())
  • Tagging (tag(), tagged())
  • Scoped bindings (scoped()) for request-lifecycle singletons
  • Method bindings (bindMethod(), call() with dependency injection)
  • Rebound callbacks (rebinding())
  • Binding-time singleton/transient control (bind() vs singleton())
  • Attribute-based contextual injection (#[Config], #[Tag], #[CurrentUser], etc.)

Also, the API is very different to Laravel's. make() always returns fresh instances, get() doesn't respect the binding type etc.

This makes it difficult to port Laravel code or use Laravel's service provider patterns without shimming everything. The new container closes that gap completely and makes interacting with the container much more familiar to Laravel devs. It also means that our package and test code will be closer to 1:1 with Laravel now.

API

The new container implements the full Laravel container contract:

Method Description
bind($abstract, $concrete, $shared) Register a binding (fresh instance each resolution)
bindIf(...) Register only if not already bound
singleton($abstract, $concrete) Register a shared binding (cached for worker lifetime)
singletonIf(...) Register only if not already bound
scoped($abstract, $concrete) Register a request-scoped singleton (cached in coroutine-local Context)
scopedIf(...) Register only if not already bound
instance($abstract, $instance) Register a pre-resolved instance
make($abstract, $parameters) Resolve from the container (respects binding type)
get($id) PSR-11 compliant resolution
build($concrete) Always build a fresh instance, bypassing bindings
call($callback, $parameters) Call a method/closure with dependency injection
when($concrete)->needs($abstract)->give($impl) Contextual bindings
extend($abstract, $closure) Decorate or modify resolved instances
tag($abstracts, $tags) / tagged($tag) Group bindings by tag
resolving() / afterResolving() / beforeResolving() Resolution lifecycle hooks
afterResolvingAttribute($attribute, $callback) Attribute-based lifecycle hooks
whenHasAttribute($attribute, $handler) Attribute-based contextual injection
alias($abstract, $alias) Type aliasing
rebinding($abstract, $callback) Rebound event hooks
factory($abstract) Get a closure that resolves the type
wrap($callback, $parameters) Wrap a closure for deferred dependency injection
flush() Clear all bindings, instances, and caches
forgetInstance($abstract) Remove a single cached instance
forgetInstances() Remove all cached instances
forgetScopedInstances() Remove all scoped instances (request cleanup)

It also supports closure return-type bindings (register a binding by returning a typed value from a closure, including union types), SelfBuilding interface for classes that control their own instantiation, and ArrayAccess for $container['key'] syntax.

Key API difference from Hyperf

Like Hyperf's get(), unbound concrete classes are automatically cached as singletons on first resolution (critical for Swoole performance). However, unlike Hyperf (where the caching decision is at resolution time i.e. get() = cached, make() = fresh), our caching decision is at binding time: singleton() = cached, bind() = fresh, unbound concretes = auto-cached. This matches Laravel's API while preserving Hyperf's performance characteristics.

Auto-singletoned instances are stored in a separate $autoSingletons array (not $instances) so that bound() doesn't report auto-cached classes as explicitly registered. This preserves correct behavior for optional typed constructor parameters with default values.

Attribute-based injection

16 contextual attributes are included, providing declarative dependency injection:

Attribute Resolves
#[Auth] Auth guard instance
#[Authenticated] Currently authenticated user (or throws)
#[Cache] Cache store instance
#[Config('key')] Configuration value
#[Context('key')] Coroutine context value
#[CurrentUser] Current user (nullable)
#[Database] Database connection
#[DB] Database connection (alias)
#[Give(value)] Inline contextual value
#[Log] Logger channel
#[RouteParameter('name')] Route parameter value
#[Scoped] Mark class as request-scoped singleton
#[Singleton] Mark class as process-global singleton
#[Storage] Filesystem disk instance
#[Tag('name')] Resolve all tagged bindings
#[Bind(Concrete::class)] Attribute-based interface binding (with environment support)

Example:

class OrderService
{
    public function __construct(
        #[Config('orders.tax_rate')] private float $taxRate,
        #[Tag('payment-processors')] private array $processors,
        #[Authenticated] private User $user,
    ) {}
}

Performance

Build recipe caching

Constructor parameters are analyzed via reflection once per class and cached as BuildRecipe / ParameterRecipe value objects for the worker lifetime. Subsequent resolutions read from cached metadata with zero reflection overhead.

First resolution:  ReflectionClass → ReflectionMethod → ReflectionParameter[] → BuildRecipe (cached)
Subsequent:        BuildRecipe → resolve parameters → instantiate (no reflection)

Method parameter caching

Container::call() caches method parameter metadata the same way - BoundMethod maintains a static $methodRecipes cache keyed by ClassName::methodName. Closures and global function strings fall back to per-call reflection since they lack a deterministic cache key.

Reflection caching

ReflectionManager caches ReflectionClass, ReflectionMethod, and ReflectionProperty objects statically for the worker lifetime, shared across the container and the rest of the framework.

Hot-path optimizations

  • Singleton cache hit path: alias resolution → empty-check early exits for callbacks → isset() on $instances → return. No Context reads on the singleton path when no contextual bindings are registered.
  • $scopedInstances is a keyed array for O(1) isScoped() lookups (not in_array()).
  • $extenders and resolving callback arrays are guarded by empty() checks before iteration.
  • $this->contextual is guarded by !empty() before contextual binding lookup.

Performance vs Hyperf

The singleton cache-hit path does marginally more work than Hyperf's single isset() (we additionally check aliases, callbacks, and scoping), but the difference is nanoseconds per resolution. This would be undetectable in any real workload. For transient bindings (bind() classes resolved multiple times), warm resolutions are cheaper than Hyperf because BuildRecipe caching eliminates repeated reflection - Hyperf's ParameterResolver re-processes ReflectionParameter objects on every make() call. Overall, real-workload performance is on par with Hyperf's container.

Coroutine safety

All per-request state is stored in coroutine-local Context, never in shared properties:

State Storage Lifetime
Build stack Context Transient (during resolution, cleaned in finally)
Resolving stack Context Transient (during resolution, cleaned in finally)
Parameter overrides Context Transient (during resolution, cleaned in finally)
Resolution depth Context Transient (during resolution, cleaned in finally)
Scoped instances Context Request lifetime (cleaned on coroutine exit)
Singletons $instances Worker lifetime (process-global, by design)
Auto-singletons $autoSingletons Worker lifetime (process-global, by design)
Bindings, aliases, tags, etc. Properties Worker lifetime (process-global, by design)

Circular dependency detection uses two complementary mechanisms:

  1. Resolving stack - direct cycle detection with full dependency chain reporting (e.g., A → B → C → A), stored in a dedicated Context key separate from the build stack to avoid false positives from call()
  2. Depth guard - safety net for indirect cycles through aliases/interfaces where abstract names differ, capped at 500 levels

All transient Context state is cleaned up in finally blocks, so exceptions during resolution never leak state to subsequent resolutions in the same coroutine.

Scoped instance cleanup is handled consistently across all invalidation paths. forgetInstance(), forgetInstances(), forgetScopedInstances(), dropStaleInstances() (triggered by rebinding), offsetUnset(), and flush() all destroy the corresponding Context entries. There's no path that clears a scoped binding's registration without also cleaning up its coroutine-local instance.

Tests

~220 tests:

  • ContainerTest - core API (binding, resolution, singleton, scoped, aliases, flush, attributes)
  • ContainerCallTest - call() method, dependency injection, method recipe caching
  • ContextualBindingTest - when()->needs()->give(), variadic bindings, contextual primitives
  • ContainerExtendTest - service extenders, scoped extend behavior
  • ContainerTaggingTest - tagging and tagged resolution
  • ResolvingCallbackTest - before/resolving/after callbacks, global and typed
  • AfterResolvingAttributeCallbackTest - attribute-based lifecycle callbacks
  • ContainerResolveNonInstantiableTest - error messages for interfaces, abstract classes
  • CoroutineSafetyTest - coroutine isolation for scoped instances, build stack, parameter overrides, exception cleanup
  • ReflectionManagerTest - reflection caching
  • RewindableGeneratorTest - lazy tagged resolution
  • UtilTest - utility helpers

Everything passes at PHPStan level 5.

Let me know what you think

*/
protected function prepareDatabase(): void
{
if (! $this->migrator->repositoryExists()) {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @binaryfire , do we consider porting handleMissingDatabase function from Laravel as well?
https://github.com/laravel/framework/blob/12.x/src/Illuminate/Database/Console/Migrations/MigrateCommand.php#L179

Copy link
Contributor Author

@binaryfire binaryfire Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @albertcht. I haven’t ported the Laravel commands because I want to port illuminate/console first.

So all these commands will be fully refactored later (and the Laravel features will be ported at that time).

use Hypervel\Console\Prohibitable;
use Hypervel\Database\ConnectionResolverInterface;

class WipeCommand extends Command
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@binaryfire will we also port DbCommand, DumpCommand, MonitorCommand, PruneCommand, ShowCommand and TableCommand from Laravel?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@albertcht Please see my comment here: #349 (comment). The current commands are just refactored versions of the old commands. I'll be doing fresh ports of the Laravel commands after I port illuminate/console. Otherwise I'd have to do the work twice. So could you skip reviewing the commands for now? It will be better to review the new ones after I've replaced them. That won't be for a while though - there are several other things I need to refactor before I do illuminate/console.

Keeps Hyperf\Codec\Json import as-is (unported package).
Replaces Hyperf\Support\make() helper with direct instantiation
since JsonParser and XmlParser have no dependencies to inject.
Keeps Hyperf\Codec\Xml import as-is (unported package).
- Container update: ApplicationContext → Container::getInstance()
- Import Base\Request instead of using FQCN
- Add type hints to withParsedBody and withoutAttribute
- Add return type to loadFromSwooleRequest
- Fix loose comparisons to strict
- Replace Hyperf\Support\make() with direct instantiation
- Add docblocks, clean up redundant @param annotations
Update namespace, imports (Writable, Cookie, SwooleStream, Chunkable,
HasChunk), import Base\Response instead of inline FQCN, add static
return type to setConnection, fix docblocks and grammar.
Update namespace, replace Hyperf\Coroutine\Exception\InvalidArgumentException
with standard InvalidArgumentException, add mixed return type to __call,
type withStatus params, add return type to getCookies, add docblocks.
Update namespace, Cookie import, add type hints to PSR-7 proxy methods,
add void return to setResponse, add mixed return to getTrailer,
add docblocks, fix grammar.
Update namespace, add native property types, add type hints to seek/write/
read/getMetadata params, add mixed return to detach/getMetadata, add
docblocks, fix grammar.
Update namespace, FileException import (Hyperf\HttpServer\Exception\Http
to Hypervel\HttpServer\Exceptions\Http), add union type to constructor,
add type hints to seek/write/read/getMetadata, add mixed return to
detach/getMetadata, add docblocks, preserve behavioral descriptions and
@see links.
Update namespace, add type hints to seek/write/read/getMetadata,
add mixed return to detach/getMetadata, modernize docblock titles,
preserve all behavioral descriptions, @see links, @throws and
@param/@return annotations with useful context.
Update namespace, StandardStream import, add native type to $mimeType,
add type hints to moveTo/isStringNotEmpty/validateActive, fix loose
comparisons, add strict flag to in_array, replace empty() with strict
comparison, add docblocks, preserve all behavioral descriptions.
…es and composer.json files

- Port Uri/Uri.php: namespace update, fix loose comparisons, add type hints, docblocks
- Create ConfigProvider.php registering RequestParserInterface -> Parser
- Update root composer.json: PSR-4 autoload, replace, config discovery
- Update all 59 consumer files (41 src/ + 18 tests/) from Hyperf\HttpMessage to Hypervel\HttpMessage
- Update exception namespace: Exception\ -> Exceptions\ (plural)
- Consolidate HyperfHttpException alias in foundation Handler
- Update cookie contracts/extension: HyperfCookie -> BaseCookie
- Update sub-package composer.json: core (remove), cookie, http-server (add), websocket-server, engine (suggest -> require)
- Drop psr/http-message ^1.0 support, require ^2.0 only across all packages
- Update testbench ConfigProviderRegister
Replaces Swow\Psr7\Message\MessagePlusInterface with
Hypervel\Contracts\Http\MessagePlusInterface. Types modernized to
match PSR-7 v2: all with* params typed, set*/addHeader $value typed
as string|array.
Replaces Swow\Psr7\Message\RequestPlusInterface with
Hypervel\Contracts\Http\RequestPlusInterface. All with* params typed
to match PSR-7 v2 (withMethod(string), withUri(bool $preserveHost),
withRequestTarget(string)).
Replaces Swow\Psr7\Message\ResponsePlusInterface with
Hypervel\Contracts\Http\ResponsePlusInterface. withStatus() now
properly typed with int $code, string $reasonPhrase matching PSR-7 v2.
…acts

Replaces Swow\Psr7\Message\ServerRequestPlusInterface with
Hypervel\Contracts\Http\ServerRequestPlusInterface. getAttribute,
withAttribute, withoutAttribute typed with string $name matching
PSR-7 v2. withParsedBody kept untyped (matching PSR-7 v2).
Replaces Swow\Psr7\Message\UriPlusInterface with
Hypervel\Contracts\Http\UriPlusInterface. All with* params typed to
match PSR-7 v2 (withPort(?int), withUserInfo(string, ?string), etc).
Replace all Swow\Psr7\Message\*PlusInterface imports with
Hypervel\Contracts\Http\*PlusInterface across http-message implementors.

Modernize param types to match PSR-7 v2: mixed → string for header
names, method, request target, URI components; mixed → ?int for port;
null|array|object → untyped for withParsedBody (matching PSR-7 v2);
withHeader/withAddedHeader $value stays untyped (PSR-7 v2 constraint).

Also fixes: HasChunk redundant instanceof check, loadFromSwooleRequest
new Request() → new static() for correct static return type.
Update all src/ and tests/ files that referenced Swow\Psr7\Message\*
interfaces to use Hypervel\Contracts\Http\* instead. These are pure
namespace swaps with no signature changes — consumers only use the
interfaces as type hints, return types, and instanceof checks.
The package now uses Hypervel\Contracts\Http\*PlusInterface instead of
Swow\Psr7\Message\*PlusInterface. The swow/psr7-plus package is still
pulled in transitively by upstream Hyperf packages but is no longer
used by any Hypervel code.
Absorb all methods from Hyperf\Testing\Http\TestResponse into
Hypervel\Testing\TestResponse so it no longer extends the Hyperf
parent. This removes the swow/psr7-plus type constraint on
fromBaseResponse() that caused 7 test failures after the interface
migration, and gives us full control over the testing response class.

- Create AssertsStatusCodes trait in Concerns/
- Add ArrayAccess implementation, Macroable, Tappable traits
- Port all content, JSON, status, and streaming assertion methods
- Modernize types throughout (native params, static returns)
- fromBaseResponse() now accepts Hypervel ResponsePlusInterface
…esponse mixin

- Remove always-true instanceof check in Handler::renderHttpException()
- Switch WritableConnection import from Hyperf\Engine to Hypervel\Engine
- Add @mixin annotation to TestResponse for PSR-7 method proxying
All exceptions now live in src/http-message/src/Exceptions/.
The core HttpException was the last remaining file and all its
additions ($headers, getHeaders()) were already merged into the
ported package version.
Port 7 test files and 3 stubs:
- MessageTraitTest, RequestParserTest, ResponseTest,
  ResponseProxyTest, ServerRequestTest, SwooleStreamTest,
  Upload/UploadedFileTest
- Stub/ParserStub, Stub/Server/RequestStub, Stub/Server/ResponseStub

CookieTest skipped (tests SetCookie which was intentionally not ported).
Standard porting changes: namespaces, base class, container mocking,
Mockery alias, PHPUnit attribute removal, type modernization.
- Create Hypervel\Testing\HttpMessage\Upload\UploadedFile (overrides
  isValid() for test contexts where files aren't HTTP-uploaded)
- Update TestClient to use Hypervel version instead of Hyperf
- Remove stale "hyperf/http-message component" comment from ResponseEmitter
Eliminates circular dependency: http-message was importing
FileException from http-server, while http-server depends on
http-message. The class now lives in the package that uses it
at the lowest level.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking-change Breaking changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants