feat: framework refactor + decouple from Hyperf#349
feat: framework refactor + decouple from Hyperf#349binaryfire wants to merge 878 commits intohypervel:0.4from
Conversation
|
@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: 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. |
|
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:
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. |
|
Hi @albertcht Thanks for the detailed response! I'm glad we're aligned on the direction. Let me address each point:
Let me know your thoughts! |
binaryfire
force-pushed
the
feature/hyperf-decouple
branch
from
8cec3bf to
bfffa6f
Compare
Container aliases (Application.php): - Add 'migrator' as alias for Migrator::class - Add 'db.transactions' as alias for DatabaseTransactionsManager::class - This ensures both string and class access return the same singleton ConfigProvider: - Remove incorrect dependency bindings (they created separate singletons) Ported tests: - MigrateWithRealpathTest - MigrationServiceProviderTest (uses get() for Hypervel singleton semantics) - Updated stub migrations to use Hypervel imports
Migrator now fetches the event dispatcher from the container each time instead of caching it at construction. This ensures Event::fake() and other runtime swaps are respected, since the Migrator may be constructed during bootstrap before fakes are set up. Also ported MigratorEventsTest from Laravel.
Test ported with namespace/import conversions and typed properties. Two failures remain that require source code fixes: - model:show command doesn't exist (ShowModelCommand not ported) - Observer detection returns 'Closure' (getRawListeners returns ListenerData objects)
Remove Hyperf-style priority system and switch to Laravel-style raw listener storage. This brings the event dispatcher API in line with Laravel's conventions while maintaining compatibility with Hyperf packages that use ListenerInterface. Key changes: - Remove priority parameter from listen() across all dispatcher classes - Store raw listeners (strings/closures/arrays) instead of ListenerData - Delete ListenerData class (no longer needed) - Update ListenerProvider to return arrays instead of SplPriorityQueue - Listeners now execute in registration order (Laravel behavior) - Simplify ListenerProviderFactory to ignore priority from annotations - Rewrite EventListCommand to format raw listeners Hyperf compatibility preserved: - ListenerProviderFactory still supports ListenerInterface - Config-based and annotation-based listener registration still works - Server events (OnWorkerStart, etc.) continue to function Files changed: - src/contracts/src/Event/Dispatcher.php - src/event/src/EventDispatcher.php - src/event/src/ListenerProvider.php - src/event/src/ListenerProviderFactory.php - src/event/src/NullDispatcher.php - src/event/src/Contracts/ListenerProvider.php - src/support/src/Testing/Fakes/EventFake.php - src/devtool/src/Commands/EventListCommand.php - Deleted: src/event/src/ListenerData.php
Add model:show command ported from Laravel, which displays information about an Eloquent model including its attributes, relations, events, and observers. Supports --json flag for JSON output. Fix ModelInspectorTest by calling withoutMockingConsoleOutput() in setUp() before parent::setUp(). This prevents DatabaseMigrations from binding a mock OutputInterface during migrate:fresh, which would otherwise intercept the real command output. Add docblock to withoutMockingConsoleOutput() explaining that it must be called before parent::setUp() when used with DatabaseMigrations.
- Add $fetchUsing property and fetchUsing() method to Query\Builder - Add fetchUsing parameter to Connection::select() and cursor() - Update ConnectionInterface to match - Fix where() type hint to accept queryable types (self|EloquentBuilder|Relation) - Add Testbench Assert class with assertArraySubset for test compatibility - Port QueryBuilderTest from Laravel - Update test mocks to use 4-parameter select() signature (WIP) - Update porting guide with clearer instructions on handling failures
…ters - Fix HasInDatabase::toString() to use Expression::getValue() instead of (string) cast - Update test mocks for Connection::select() 4th fetchUsing parameter - Port QueryBuilderUpdateTest to Hypervel namespaces
- Port QueryBuilderUpdateTest, QueryBuilderWhereLikeTest, QueryingWithEnumsTest, RefreshCommandTest, SchemaBuilderSchemaNameTest, SchemaBuilderTest - Fix BlueprintState::$primaryKey type to accept Fluent (blueprint commands) - Fix SQLiteBuilder::getTables() to cast $withSize to bool - Fix SQLiteBuilder::getColumns() to handle null SQL for views
- Process RequiresDatabase in setUpDatabaseRequirements() BEFORE migrations run, allowing tests to skip early when wrong driver - Port TimestampTypeTest to Hypervel namespaces - Port MariaDb test directory: MariaDbTestCase, EloquentCastTest, EscapeTest, FulltextTest, and connection/schema tests
- Port MySqlTestCase, DatabaseEloquentMySqlIntegrationTest, DatabaseMySqlConnectionTest, DatabaseEmulatePreparesMySqlConnectionTest, DatabaseMySqlSchemaBuilderAlterTableWithEnumTest, DatabaseMySqlSchemaBuilderTest, EloquentCastTest, EscapeTest - Port MariaDb/JsonLikeTest - Fix MySqlGrammar::compileTables() - remove unused sprintf argument - Fix EloquentCastTest mutator to use $this->attributes[] (avoid recursion) - Update EscapeTest to expect TypeError for array input (strict typing)
- Move DB insert from setUp() to afterRefreshingDatabase() (coroutine context)
- Fix RequiresOperatingSystemFamily vs RequiresOperatingSystem attribute usage - Convert PostgresTestCase, DatabaseEloquentPostgresIntegrationTest, DatabasePostgresConnectionTest, EscapeTest to Hypervel namespaces - Add proper return types and model property types
The purge() method clears context and flushes the pool, but didn't clear the $this->connections cache used by SimpleConnectionResolver (non-pooled mode). This meant tests using runtime config changes wouldn't get fresh connections with updated config.
- Add search_path and prefix_indexes to pgsql config - Convert EscapeTest to expect TypeError for array input (strict typing) - Convert FulltextTest namespace and move DB ops to afterRefreshingDatabase - Convert JoinLateralTest namespace and fix RequiresOperatingSystem attribute
The DatabaseConnectionResolver caches connections statically, which wasn't cleared when DB::purge() was called. This caused stale connections with old config to be returned after config changes. Fix: - Add FlushableConnectionResolver interface for resolvers with caches - DatabaseConnectionResolver implements it with flush() to clear static cache - DatabaseManager::purge() calls flush() on resolver if it implements interface Also: - Port PostgresSchemaBuilderTest to Hypervel namespace - Move dont_drop config tests to separate files (Swoole requires config in defineEnvironment(), not runtime Config::set())
- Port Queue fixtures and tests to Hypervel namespaces - Add database queue connection to workbench config - Tests require remote() function (not yet implemented)
Implements remote() to spawn subprocesses for testing scenarios requiring process isolation (e.g., queue workers with job timeouts). - Add testbench CLI binary that boots Hypervel and runs console commands - Add Foundation/Process classes (RemoteCommand, ProcessDecorator, ProcessResult) - Add helper functions: remote(), package_path(), defined_environment_variables() - Register testbench binary in composer.json
Move testing utilities to dedicated hypervel/testing package to match Laravel's structure where Illuminate\Testing is separate from Illuminate\Foundation\Testing. Moved classes: - Constraints (CountInDatabase, HasInDatabase, NotSoftDeletedInDatabase, SeeInOrder, SoftDeletedInDatabase) - PendingCommand - TestResponse - TestResponseAssert
…kage These classes belong in the Testing package per Laravel's structure where Illuminate\Testing contains Assert, Constraints\ArraySubset, and Exceptions\InvalidArgumentException.
- Process DefineEnvironment attributes in defineEnvironment() method
instead of setUpTheTestEnvironmentUsingTestCase(), allowing database
config to be set before connections are pooled in Swoole
- Move testbench migrations from workbench/migrations/ to migrations/
(parallel to workbench/, matching Laravel's laravel/migrations/ structure)
- Add workbench/database/{factories,migrations,seeders} structure for
database_path() to work correctly
- Update default_migration_path() to use testbench package path
- Recombine PostgresSchemaBuilderDontDrop*Test files into main test
using DefineEnvironment attribute with separate connection names
- Port ConnectorTest using DefineEnvironment for custom SQLite configs
- DatabaseSchemaBlueprintTest: Update namespaces, remove SqlServer tests (unsupported), add RefreshDatabase trait with foreign_key_constraints=false - DatabaseSchemaBuilderTest: Update namespaces, add setUp cleanup for connections that call dropAllTables() (can't use transaction-based cleanup) - DatabaseSqliteConnectionTest: Update namespaces, add return types
- DatabaseSqliteSchemaBuilderTest: Update namespaces, add return types - EloquentModelConnectionsTest: Update namespaces, add test-specific namespace for model classes, add proper type hints, add table cleanup - EscapeTest: Update namespaces, change testEscapeArray to expect TypeError (Hypervel has stricter type hints)
- SchemaBuilderSchemaNameTest: Update namespaces (tests skip on :memory:) - SchemaStateTest: Update namespaces (tests skip on :memory:) - Add InteractsWithPublishedFiles trait to testbench for file assertion helpers
Purge and reconnect in setUp to apply foreign_key_constraints config before tests run. Remove RefreshDatabase trait since manual cleanup via dropAllTables() is sufficient for these SQL generation tests.
|
|
||
| class RollbackCommand extends BaseCommand | ||
| { | ||
| use ConfirmableTrait; |
| @@ -6,9 +6,9 @@ | |||
|
|
|||
| use Hyperf\Command\Concerns\Prohibitable; | |||
There was a problem hiding this comment.
change to Hypervel's Prohibitable here?
- SeedCommand: switch from Hyperf's Prohibitable to Hypervel's - RollbackCommand: add missing Prohibitable trait (matches Laravel)
binaryfire
force-pushed
the
feature/hyperf-decouple
branch
from
80f3ef2 to
94c115e
Compare
Copy coordinator package (Constants, Coordinator, CoordinatorManager, Timer, Functions) from hyperf, update namespaces to Hypervel, modernise types, add method docblocks. Skip deprecated ResumeExitCoordinatorListener (empty body, depends on unported packages). Update consumers in foundation, object-pool to use Hypervel\Coordinator. Rename and update porting guide docs.
Update Hyperf\Coordinator references to Hypervel\Coordinator in pool, queue, testbench, object-pool (src + tests), and horizon test worker. Fix phpstan: use self:: instead of static:: for private static property in CoordinatorManager. Update porting guide to include consumer update step covering both src/ and tests/.
- Port all 14 Hyperf coordinator tests (CoordinatorTest, FunctionTest, TimerTest) - Add WORKER_EXIT coordinator cleanup in FunctionTest setUp to prevent stale state from RunTestsInCoroutine's post-test cleanup - Update porting guide: absolute directory paths, drop :void on test methods - cs-fixer: import ordering after coordinator namespace changes
- Delete unnecessary per-package base test cases (EngineTestCase, CoroutineTestCase, GuzzleTestCase) that only added RunTestsInCoroutine and redundant Mockery::close() - Update all 23 test classes to extend Hypervel\Tests\TestCase directly with RunTestsInCoroutine trait - Fix integration base test cases to extend Hypervel\Tests\TestCase and remove redundant Mockery::close() - Remove : void from all test methods for consistency with existing tests - Remove PHPUnit #[CoversNothing] attributes from Guzzle tests
The trait supports all test server types (HTTP, TCP, WebSocket, HTTP/2), not just HTTP. Rename trait, properties, and methods to reflect this.
Typed class constants (const string) require PHP 8.3+, which breaks php-cs-fixer linting on the PHP 8.2 CI runner.
- Fix ContextEnumTest base class to Hypervel\Tests\TestCase, remove :void - Merge 5 Hyperf non-coroutine tests into ContextTest (override, getOrSet, destroy, request/response context) - Create ContextCoroutineTest with 8 coroutine tests using RunTestsInCoroutine - Create ApplicationContextTest adapted from Hyperf (mock Hypervel container contract) - Create Traits/CoroutineProxyTest with updated namespace in exception message
Update porting doc to require 'use Mockery as m' convention and change all Mockery:: calls to m:: in 32 test files. Remaining files will be updated in a follow-up.
Complete the migration from `use Mockery;` / `Mockery::` to `use Mockery as m;` / `m::` across the remaining test files in ObjectPool, Queue, Redis, Router, Sanctum, Scout, and Sentry.
AfterEachTestExtension handles Mockery cleanup globally after every test, making explicit m::close() calls in tearDown unnecessary. Removed the calls and deleted tearDown methods that existed solely for this purpose.
Copy and adapt all 4 test files and 6 stubs from hyperf/pool to tests/Pool/. Key adaptations: Hyperf→Hypervel namespaces, Mockery alias standardization, ClassInvoker replaced with ReflectionProperty, container make() mocks removed (Hypervel instantiates Channel and PoolOption directly), and WORKER_EXIT coordinator cleared in setUp to prevent stale coordinator state from causing timer closures to resolve immediately.
Add Hypervel\Support\ClassInvoker for accessing protected/private members via reflection. Modernized with strict parameter and return types. Refactor HeartbeatConnectionTest to use it instead of raw ReflectionProperty calls.
2 participants
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.Stringablewas 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
RunTestsInCoroutineto 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:
hypervel/contractspackage, the Hyperf database code is split across 3 packages, the Hyperf pagination package ishyperf/paginatorand nothyperf/pagination)static::registerCallback('creating')vsstatic::creating())ConfigProviderand LaravelServiceProviderpatterns across different packages is confusing for anyone who doesn't know HyperfThis 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:
hypervel/contractsfor contracts) and then have to spend a lot of time grepping for things to find them.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
illuminate/databaseportilluminate/collectionsportilluminate/paginationportilluminate/contracts)hyperf/pool)Macroableto a separate package for Laravel parityRemoved Hyperf dependencies so far
Database package
The big task was porting the database package, making it coroutine safe, implementing performance improvements like static caching and modernising the types.
whereLike,whereNot,groupLimit,rawValue,soleValue, JSON operations, etc.Collections package
Contracts package
Support package
hyperf/tappable,hyperf/stringable,hyperf/macroable,hyperf/codecdependenciesStr,Envand helper classes from LaravelHypervel\Contextwrappers (will be portinghyperf/contextsoon)Number::useCurrency()wasn't actually setting the currency)Coroutine safety
withoutEvents(),withoutBroadcasting(),withoutTouching()now use Context instead of static propertiesUnsetContextInTaskWorkerListenerto clear database context in task workersConnection::resetForPool()to prevent state leaks between coroutinesDatabaseTransactionsManagercoroutine-safeBenefits
Testing status so far
What's left (WIP)
The refactor process
Hyperf's Swoole packages like
pool,coroutine,contextandhttp-serverhaven'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
ConfigProviderand 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.