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.

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

Updated hypervel/context package ready for review

See: #349 (comment)

New hypervel/http-server, hypervel/http & hypervel/routing packages ready for review

See: #349 (comment)

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]

@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.

[binaryfire]

@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]

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

[albertcht]

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

[binaryfire]

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).

[albertcht]

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

[binaryfire]

@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.

[binaryfire]

Hi @albertcht. The Context package is now ready for review.

1. Propagated Context

Why this feature matters

Laravel 11 introduced Illuminate\Log\Context\Repository - an API for storing per-request metadata that automatically flows into log entries and queued job payloads.

This is genuinely useful beyond just Laravel parity. Two concrete problems it solves:

• Automatic propagation to queued jobs. Any metadata you add to propagated context during a request - tenant ID, user preferences, feature flags, trace IDs, locale, whatever - automatically serializes into every job payload dispatched during that request and deserializes when the job runs. No manual passing of context through job constructors.
• Automatic context in log entries. Any metadata in propagated context automatically appears in the extra field of every log entry for that request. No need to pass context arrays to every Log::info() call or maintain custom log processors per app.

Both of these work transparently once configured - add context once at the start of a request, and it flows everywhere it needs to go.

Why extend Context instead of porting Laravel's Context classes

Hypervel's Context and Laravel's Context are fundamentally different things:

	Hypervel Context	Laravel Context
Purpose	Coroutine-local storage for any per-request state	Metadata that propagates to logs and jobs
Storage	Swoole coroutine context (C-level)	Instance properties on a Repository object
Scope	Framework internals + developer use	Developer-facing only
Propagation	No - stays in current coroutine	Yes - serialized into job payloads, added to log records

Porting Laravel's Illuminate\Log\Context classes directly would create confusing overlap - two "context" classes doing different things. Instead, I extended Context with a propagated() method that returns a PropagatedContext instance:

• One canonical entry point (Context) for all per-request state
• Clear separation - set()/get() for raw coroutine storage, propagated()->add()/get() for metadata that flows to logs/jobs
• Laravel-compatible API - PropagatedContext methods map directly to Laravel's Repository methods
• No second competing store - the PropagatedContext instance is stored inside coroutine context under a reserved key

Why propagated() instead of flat static methods

I considered adding static methods like Context::getPropagated(), Context::forgetPropagated(), Context::getPropagatedHidden() etc. directly on Context. Rejected because:

• The full API surface would add 30+ static methods to Context, most with verbose names (forgetPropagatedHidden, pullPropagatedHidden)
• Context::propagated() returning the PropagatedContext instance is cleaner - one entry point, then use Laravel-equivalent method names (add, get, forget, addHidden, etc.)
• The returned instance can be stored in a variable for repeated use: $propagated = Context::propagated();
• Maps directly to Laravel's Context:: facade methods, making migration documentation straightforward

Architecture

Context::set('key', 'value')              ->  Swoole coroutine context (raw storage)
Context::get('key')                       ->  Swoole coroutine context (raw storage)
Context::propagated()                     ->  PropagatedContext instance (stored in coroutine context)
Context::propagated()->add('key', 'val')  ->  PropagatedContext::$data array
Context::propagated()->addHidden(...)     ->  PropagatedContext::$hidden array
Context::propagated()->dehydrate()        ->  Serializes $data + $hidden for job payload
Context::propagated()->hydrate($payload)  ->  Deserializes into $data + $hidden from job payload

The PropagatedContext instance lives under the coroutine context key __context.propagated, created lazily on first access:

public static function propagated(): PropagatedContext
{
    return self::getOrSet(
        self::PROPAGATED_CONTEXT_KEY,
        fn () => new PropagatedContext(app(Dispatcher::class))
    );
}

Context::hasPropagated() checks if a PropagatedContext instance exists without creating one. Used in the log processor and queue payload hook to avoid allocating an empty instance on every request when propagated context is never used.

How it works: log integration

ContextLogProcessor is pushed onto every resolved log channel. It adds propagated context data to the log record's extra field:

class ContextLogProcessor implements ProcessorInterface
{
    public function __invoke(LogRecord $record): LogRecord
    {
        if (! Context::hasPropagated()) {
            return $record;
        }

        $propagated = Context::propagated()->all();

        if ($propagated === []) {
            return $record;
        }

        return $record->with(extra: [
            ...$record->extra,
            ...$propagated,
        ]);
    }
}

Key details:

• Only visible data ($data) flows to logs. Hidden data ($hidden) is intentionally excluded from log records - it only propagates to jobs.
• The hasPropagated() guard means zero overhead on requests that never use propagated context.
• The processor is pushed in LogManager::get() for named channels and LogManager::stack() for on-demand stacks.
• createStackDriver() filters out ContextLogProcessor from constituent channel processors to prevent duplication when channels are combined into stacks.

How it works: queue integration

Wired in QueueServiceProvider::boot():

// When creating job payloads, dehydrate propagated context into the payload.
Queue::createPayloadUsing(function (string $connection, ?string $queue, array $payload): array {
    if (! Context::hasPropagated()) {
        return [];
    }

    $context = Context::propagated()->dehydrate();

    return $context === null ? [] : ['hypervel:context' => $context];
});

// When processing jobs, hydrate propagated context from the payload.
$this->app['events']->listen(JobProcessing::class, function (JobProcessing $event): void {
    $context = $event->job->payload()['hypervel:context'] ?? null;

    if ($context === null) {
        return;
    }

    Context::propagated()->hydrate($context);
});

Key details:

• dehydrate() works on a clone so dehydrating callbacks can modify values without affecting the live propagated context.
• dehydrate() returns null when propagated context is empty - no payload bloat for jobs that don't use context.
• hydrate() flushes existing propagated context before restoring, dispatches ContextHydrated so service providers can react.
• No explicit cleanup on JobProcessed/JobExceptionOccurred is needed. Async jobs run in their own coroutine - Swoole destroys the coroutine context when it ends. Sync jobs run in the request's coroutine, which is expected (same as Laravel).
• ContextDehydrating and ContextHydrated events allow service providers to hook into the serialization lifecycle.

How it works: coroutine isolation

When coroutines are forked via Context::copy(), the PropagatedContext instance is replicated so the child gets its own independent copy rather than sharing an object reference with the parent. This ensures mutations in a child coroutine don't affect the parent's propagated context:

// In Context::copy()
if (isset($map[self::PROPAGATED_CONTEXT_KEY])
    && $map[self::PROPAGATED_CONTEXT_KEY] instanceof PropagatedContext
) {
    $map[self::PROPAGATED_CONTEXT_KEY] = $map[self::PROPAGATED_CONTEXT_KEY]->replicate();
}

The same replication is applied in Context::copyFromNonCoroutine().

Usage examples

// Add context at the start of a request (e.g. in middleware)
Context::propagated()->add('trace_id', $request->header('X-Trace-Id'));
Context::propagated()->add('user_id', auth()->id());

// Hidden context flows to jobs but NOT to logs (sensitive data)
Context::propagated()->addHidden('api_key', $apiKey);

// Every log entry now automatically includes trace_id and user_id
Log::info('Processing order', ['order_id' => $order->id]);
// Log extra: {"trace_id": "abc-123", "user_id": 42}

// Every dispatched job automatically carries the context
ProcessOrder::dispatch($order);
// Job payload includes: {"hypervel:context": {"data": {...}, "hidden": {...}}}

// Inside the job, context is automatically restored
class ProcessOrder implements ShouldQueue
{
    public function handle(): void
    {
        $traceId = Context::propagated()->get('trace_id'); // "abc-123"
        $apiKey = Context::propagated()->getHidden('api_key'); // restored
    }
}

// Temporary context for a specific scope
Context::propagated()->scope(function () {
    // Additional context only exists inside this callback
}, data: ['scope' => 'payment'], hidden: ['token' => $paymentToken]);

// Hooks for serialization lifecycle
Context::propagated()->dehydrating(function (PropagatedContext $context) {
    $context->add('dehydrated_at', now()->toISOString());
});

Context::propagated()->hydrated(function (PropagatedContext $context) {
    // React to restored context in the job worker
});

Laravel equivalence mapping

Full API parity with Laravel's Illuminate\Log\Context\Repository:

Laravel Context::	Hypervel
add($key, $value)	Context::propagated()->add($key, $value)
addIf($key, $value)	Context::propagated()->addIf($key, $value)
get($key)	Context::propagated()->get($key)
has($key)	Context::propagated()->has($key)
missing($key)	Context::propagated()->missing($key)
all()	Context::propagated()->all()
only($keys)	Context::propagated()->only($keys)
except($keys)	Context::propagated()->except($keys)
forget($key)	Context::propagated()->forget($key)
pull($key)	Context::propagated()->pull($key)
remember($key, $value)	Context::propagated()->remember($key, $value)
push($key, ...$values)	Context::propagated()->push($key, ...$values)
pop($key)	Context::propagated()->pop($key)
stackContains($key, $value)	Context::propagated()->stackContains($key, $value)
increment($key, $amount)	Context::propagated()->increment($key, $amount)
decrement($key, $amount)	Context::propagated()->decrement($key, $amount)
addHidden($key, $value)	Context::propagated()->addHidden($key, $value)
addHiddenIf($key, $value)	Context::propagated()->addHiddenIf($key, $value)
getHidden($key)	Context::propagated()->getHidden($key)
hasHidden($key)	Context::propagated()->hasHidden($key)
missingHidden($key)	Context::propagated()->missingHidden($key)
allHidden()	Context::propagated()->allHidden()
onlyHidden($keys)	Context::propagated()->onlyHidden($keys)
exceptHidden($keys)	Context::propagated()->exceptHidden($keys)
forgetHidden($key)	Context::propagated()->forgetHidden($key)
pullHidden($key)	Context::propagated()->pullHidden($key)
rememberHidden($key, $value)	Context::propagated()->rememberHidden($key, $value)
pushHidden($key, ...$values)	Context::propagated()->pushHidden($key, ...$values)
popHidden($key)	Context::propagated()->popHidden($key)
hiddenStackContains($key, $value)	Context::propagated()->hiddenStackContains($key, $value)
scope($callback, $data, $hidden)	Context::propagated()->scope($callback, $data, $hidden)
isEmpty()	Context::propagated()->isEmpty()
flush()	Context::propagated()->flush()
dehydrating($callback)	Context::propagated()->dehydrating($callback)
hydrated($callback)	Context::propagated()->hydrated($callback)
dehydrate()	Context::propagated()->dehydrate()
hydrate($context)	Context::propagated()->hydrate($context)
handleUnserializeExceptionsUsing($cb)	Context::propagated()->handleUnserializeExceptionsUsing($cb)

New files

File	Description
src/context/src/PropagatedContext.php	Core class - data + hidden storage, serialization, hooks, scoping
src/context/src/Events/ContextDehydrating.php	Event dispatched before context is serialized for a job payload
src/context/src/Events/ContextHydrated.php	Event dispatched after context is restored from a job payload
src/log/src/ContextLogProcessor.php	Monolog processor that adds propagated context to log record extras

Modified files

File	Change
src/context/src/Context.php	Added propagated(), hasPropagated(), PROPAGATED_CONTEXT_KEY constant, replicate() calls in copy() and copyFromNonCoroutine()
src/context/src/helpers.php	Updated context() docblock to reference Context::propagated()
src/context/composer.json	Added dependencies: hypervel/events, hypervel/queue, hypervel/conditionable, hypervel/macroable, hypervel/support
src/contracts/src/Queue/Job.php	Added payload() method to the Job contract
src/log/src/LogManager.php	Pushes ContextLogProcessor onto resolved channels and on-demand stacks, filters duplicates in stack driver
src/queue/src/QueueServiceProvider.php	Wires Queue::createPayloadUsing for dehydration and JobProcessing listener for hydration

Test coverage

Test file	Tests	What it covers
tests/Context/PropagatedContextTest.php	57 tests	Unit tests for all PropagatedContext methods - data ops, hidden ops, stacks, counters, scope, flush, dehydrate/hydrate, event hooks, error handling
tests/Context/ContextPropagatedTest.php	11 tests	Integration of Context::propagated() - lazy creation, same-instance identity, isolation from raw context, hasPropagated() guard, flush() clearing
tests/Context/PropagatedContextCoroutineTest.php	4 tests	Coroutine isolation - separate instances per coroutine, non-inheritance by children, fork copy isolation (regression test for shallow copy bug), cross-coroutine dehydrate/hydrate
tests/Context/PropagatedContextLogTest.php	6 tests	Log integration - context appears in log extras, hidden data excluded, no override of message context, processor skip when no context exists, custom processor binding
tests/Context/PropagatedContextQueueTest.php	12 tests	Queue integration - payload inclusion, empty context skip, hidden data in payload, hydration on job processing, dehydrating/hydrated hooks, round-trip type preservation, end-to-end sync job
tests/Integration/Context/PropagatedContextIntegrationTest.php	7 tests	End-to-end integration through the real LogManager - propagated data in channel logs, stack logs, hidden exclusion, empty context skip, processor skip

2. Method name alignment: destroy -> forget, destroyAll -> flush

Renamed Context::destroy() to Context::forget() and Context::destroyAll() to Context::flush(). Aligns with Laravel's naming conventions (forget used throughout Collections, Session, Cache, etc.) and with PropagatedContext which also uses forget() and flush().

Hard break, no deprecation - pre-1.0 and all call sites are ours. ~50 files across src/ and tests/.

The same rename was applied to the context subclasses: ParentContext::forget(), RequestContext::forget(), ResponseContext::forget(), and WebSocketServer\Context::forget().