Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
75 commits
Select commit Hold shift + click to select a range
2bfa852
Require PhpRedis 6.3 for framework development
binaryfire Nov 16, 2026
e2e2ef9
Plan the deferred framework-wide PhpRedis 6.3 minimum
binaryfire Nov 16, 2026
4b2d0d3
Simplify Redis transaction helpers and correct native client types
binaryfire Nov 16, 2026
6ef9a79
Convert gRPC test doubles to Double
binaryfire Nov 16, 2026
84ce191
Use Double and real configuration in hashing and head tests
binaryfire Nov 16, 2026
f2ae8cc
Convert Horizon tests using real Redis forwarding
binaryfire Nov 16, 2026
6f0b124
Convert HTTP and server test doubles to Double
binaryfire Nov 16, 2026
981794b
Convert image and Inertia tests to typed doubles
binaryfire Nov 16, 2026
9b94880
Convert JWT tests to Double without changing guard coverage
binaryfire Nov 16, 2026
6066d8f
Convert logging and context tests to Double
binaryfire Nov 16, 2026
bf2a358
Convert remaining mail tests to Double
binaryfire Nov 16, 2026
d9e16d0
Convert remaining MCP tests to Double
binaryfire Nov 16, 2026
8fe7a3b
Convert nested-set dependency tests to Double
binaryfire Nov 16, 2026
e9b8f37
Convert remaining notification tests to Double
binaryfire Nov 16, 2026
fb335a1
Convert object-pool lifecycle tests to Double
binaryfire Nov 16, 2026
851e343
Convert telemetry lifecycle and instrumentation tests to Double
binaryfire Nov 16, 2026
818117f
Convert analyzer service tests to Double
binaryfire Nov 16, 2026
7071ed9
Convert pagination resolver tests to Double
binaryfire Nov 16, 2026
7a3ccc0
Convert passkey action and controller tests to Double
binaryfire Nov 16, 2026
1e475bc
Convert Passport authentication and key tests to Double
binaryfire Nov 16, 2026
c98204d
Explain the MCP process destructor allowance
binaryfire Nov 17, 2026
2809b66
Convert Pennant stored-value cache tests to Double
binaryfire Nov 17, 2026
f9b5198
Convert permission tests to Double
binaryfire Nov 17, 2026
ff04582
Convert pipeline test doubles to Double
binaryfire Nov 17, 2026
7f92ecb
Convert process tests to Double
binaryfire Nov 17, 2026
715ab9b
Convert prompt animation test doubles to Double
binaryfire Nov 17, 2026
45c2482
Convert queue outbox tests to Double
binaryfire Nov 17, 2026
8c8fd05
Convert queue command tests to Double
binaryfire Nov 17, 2026
6e04939
Convert queue lifecycle and driver tests to Double
binaryfire Nov 17, 2026
8581b24
Convert queue integration test doubles to Double
binaryfire Nov 17, 2026
2f9dcf4
Convert rate limiter store and lifecycle tests to Double
binaryfire Nov 17, 2026
67d6105
Convert Redis limiter tests to Double
binaryfire Nov 17, 2026
56ae645
Convert Redis connection and operation tests to Double
binaryfire Nov 17, 2026
c557096
Convert Redis pool and configuration tests to native fixtures
binaryfire Nov 17, 2026
0fd8e66
Convert remaining Redis proxy and subscriber tests to Double
binaryfire Nov 17, 2026
3bcd61e
Convert Reverb transport and lifecycle tests to Double
binaryfire Nov 17, 2026
570eaf1
Convert routing exception-handler tests to Double
binaryfire Nov 17, 2026
fb7500a
Convert Saloon test dependencies to Double and real configuration
binaryfire Nov 17, 2026
292048b
Convert Sanctum middleware and cache-provider test doubles
binaryfire Nov 17, 2026
881b540
Convert Scout engine tests to concrete searchable doubles
binaryfire Nov 17, 2026
1e2a3d6
Convert Scout command tests to Double and real config repositories
binaryfire Nov 17, 2026
98061e6
Convert remaining Scout model and builder tests to Double
binaryfire Nov 17, 2026
5eedb21
Convert Sentry transport and flush tests to Double
binaryfire Nov 17, 2026
f683161
Convert Sentry integration and lifecycle tests to Double
binaryfire Nov 17, 2026
537b6dc
Convert server lifecycle and command tests to Double
binaryfire Nov 17, 2026
d8fe685
Convert server process tests to Double
binaryfire Nov 17, 2026
ab49154
Convert session and ownership tests to Double
binaryfire Nov 17, 2026
fddb80f
Convert signal lifecycle tests to Double
binaryfire Nov 17, 2026
52fe836
Convert Slack notification transport tests to Double
binaryfire Nov 17, 2026
39aacb2
Convert Socialite tests to Double and verify real Google mapping
binaryfire Nov 17, 2026
ec998ab
Convert remaining Support test doubles to Double
binaryfire Nov 17, 2026
ba72f34
Convert remaining Telescope test doubles to Double
binaryfire Nov 17, 2026
3b70344
Convert Testbench console tests using the shared component fixture
binaryfire Nov 17, 2026
d91e283
Convert Testbench lifecycle and database doubles to Double
binaryfire Nov 17, 2026
023140a
Convert testing assertion dependencies to Double
binaryfire Nov 17, 2026
3800409
Convert remaining Tinker and View doubles to Double
binaryfire Nov 17, 2026
87d9e83
Convert validation planner and presence tests to Double
binaryfire Nov 17, 2026
8fdc0af
Preserve authorization data and bound Gate policy caching
binaryfire Nov 17, 2026
c1844ce
Check authoritative Composer autoloading in production
binaryfire Nov 17, 2026
4317d17
docs: make contract completeness a general design rule
binaryfire Nov 17, 2026
93095f3
Convert watcher and route-binding test doubles
binaryfire Nov 17, 2026
92948ba
Convert WebSocket lifecycle tests to Double
binaryfire Nov 17, 2026
588fe16
Convert AI storage and auth cache integration doubles
binaryfire Nov 17, 2026
73610b0
Convert broadcast integration tests and share the Redis fixture
binaryfire Nov 17, 2026
e4e623b
Complete the cache repository contract and preserve flush events
binaryfire Nov 17, 2026
578c0b9
Convert console scheduling and serialized-closure doubles
binaryfire Nov 17, 2026
83e5e5f
Convert database pooling integration doubles
binaryfire Nov 17, 2026
6286e53
Convert foundation integration dependencies to Double
binaryfire Nov 17, 2026
8d23de0
Finish remaining framework integration double conversions
binaryfire Nov 17, 2026
8cde033
Use Double in pooled-connection benchmark fixtures
binaryfire Nov 17, 2026
82fbe99
Allow the intentional development PhpRedis constraint difference
binaryfire Nov 17, 2026
71c21db
Preserve positional authorization arguments from named Can parameters
binaryfire Nov 17, 2026
a0dda4d
Bound policy discovery to declared class spellings
binaryfire Nov 17, 2026
debc72d
Preserve authoritative autoloading during Doctor repairs
binaryfire Nov 17, 2026
6ddba98
Preserve configured policy names for declared model classes
binaryfire Nov 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
10 changes: 5 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,7 @@ Build complete, long-term solutions, not MVPs or local workarounds. A broad chan
- **New Hypervel-owned code and packages must be Laravel-style** — Design new packages and public surfaces as if they were first-party Laravel packages ported to and enhanced for Hypervel. APIs, naming, class responsibilities, code patterns, and directory structure must be ergonomic, intuitive, and immediately familiar to Laravel developers, while internals remain coroutine-safe and optimized for Hypervel's long-lived Swoole runtime and high-performance requirements. Apply the requirements under [Audit changes during modification and code review](#audit-changes-during-modification-and-code-review) from initial design onward.
- **Reserve `assert*` methods for testing APIs** — Use prefixes such as `ensure*` or `validate*` for runtime guards.
- **Modern PHP 8.4+ with full typing** — use constructor property promotion, readonly properties, enums, match expressions, named arguments, and attributes where they fit. Every file declares `strict_types=1`; parameters, return types, properties, and class constants are natively typed wherever PHP and the inherited API permit (e.g. `resource` cannot be represented as a native PHP type). PHP does not allow return types on `__construct()` or `__destruct()`.
- **Keep contracts complete** — A contract should declare the documented public API that every conforming implementation must provide, so code that type-hints the contract can use it. Add missing methods when found, even when the omission is inherited from Laravel. Put optional driver capabilities on separate capability interfaces, such as LockProvider. Implementation-specific methods and internal helpers do not belong on contracts. Follow the existing approval rules for Laravel API changes.
- **Contract signature dependencies are lazy** — contract signatures may natively reference types from optional split packages without a reverse Composer dependency. Do not remove these types or add cyclic dependencies solely for split-package isolation.
- **Dependency access in new packages** — Inject framework service contracts through constructors or methods rather than using helpers, facades, or direct instantiation. Where injection is impractical, such as static contexts or framework-constructed objects, use `Container::getInstance()->make(...)`. Helpers are fine in route and config files.
- **Dependency access within existing packages** — Follow the established style of surrounding classes with the same role, including when adding new classes to a ported package. Preserve upstream’s helper, facade and instantiation style where it keeps updates straightforward. A class being newly written is not, by itself, a reason to use a different style. Change dependency access only for a concrete correctness, lifetime, testability or maintainability benefit, and keep related code internally consistent without rewriting unrelated classes.
Expand Down Expand Up @@ -772,11 +773,10 @@ Run full PHPStan checks with `composer analyse`. During implementation, use targ
2. **Don't make the code worse or more convoluted just to satisfy PHPStan.** Fix real issues in the code, but don't add awkward wrappers, fake branches, casts, or wider types just to silence PHPStan. A type-only fix must not change runtime behavior, add overhead, or introduce new edge cases. A genuine runtime bug that PHPStan exposes is fixed through the normal bug-fix workflow. If you cannot satisfy PHPStan within those constraints, reach consensus on a compliant solution through a second-opinion loop with your peer agent. If the code is correct and PHPStan cannot understand it, follow the source-first rule below.
3. **Check the supported runtime contract before removing guards.** Preserve necessary validation of caller input, consumer configuration and external data. Remove checks that only repeat guarantees the code already enforces; PHPDoc types and facts inferred from the booted application are not such guarantees.
4. **Don't change contract/concrete boundaries to fix phpstan.** Swapping a contract for a concrete (or vice versa) to satisfy a type check diverges from Laravel's API. Only do this when Laravel's typing is genuinely incorrect.
5. **Methods can be added to contracts only if they represent behavior any conforming implementation must provide.** Implementation-specific methods, internal helpers, or driver-specific features don't belong on contracts — find another fix even if adding them would satisfy phpstan.
6. **Type decisions must be evidence-based.** See Development Conventions — check Laravel/Hyperf signatures and docblocks, then trace real control flow. Don't guess.
7. **Fix types at their source.** Correct signatures, PHPDoc, generics, stubs or extensions. Use `assert()` only for genuine invariants; assertions may be disabled and cannot replace required validation. A truthful inline `@var` is a last resort. For verified analysis limitations, use `@phpstan-ignore identifier (reason)`, always including a meaningful reason; never use identifier-less ignores. For a confirmed PHPStan bug, start the reason with `@TODO: Remove once PHPStan` and describe the needed fix; do not add a `docs/todo.md` entry. NEON ignores require approval under the global-ignore rule.
8. **Don't add patterns to `phpstan.neon.dist` on your own.** The neon file's global ignores cover fundamental framework patterns (Eloquent magic, generics, `new static`). Fix new phpstan errors at the source, not by masking them with new neon rules. Global suppression is a rare exception. First, reach consensus through a second-opinion loop with your peer agent that the error cannot be fixed at the source or narrowed locally, and that the pattern is frequent enough to justify global suppression. Then STOP, explain the reason and recommended suppression to the owner, and wait for approval before adding it.
9. **Environment reads outside config files.** Framework source reads the environment outside config files only for a deliberate infrastructure need, such as reads before configuration loads, process transport like `__HYPERVEL_CONTEXT`, or test infrastructure like worker tokens. Use `Env::get()` with an inline `@phpstan-ignore hypervel.noEnvCallsOutsideOfConfig (reason)` stating that need. `Env::get()` is the convention for these intentional reads; switching from `env()` does not fix a read in the wrong place. Do not add directory, path or class-wide exemptions.
5. **Type decisions must be evidence-based.** See Development Conventions — check Laravel/Hyperf signatures and docblocks, then trace real control flow. Don't guess.
6. **Fix types at their source.** Correct signatures, PHPDoc, generics, stubs or extensions. Use `assert()` only for genuine invariants; assertions may be disabled and cannot replace required validation. A truthful inline `@var` is a last resort. For verified analysis limitations, use `@phpstan-ignore identifier (reason)`, always including a meaningful reason; never use identifier-less ignores. For a confirmed PHPStan bug, start the reason with `@TODO: Remove once PHPStan` and describe the needed fix; do not add a `docs/todo.md` entry. NEON ignores require approval under the global-ignore rule.
7. **Don't add patterns to `phpstan.neon.dist` on your own.** The neon file's global ignores cover fundamental framework patterns (Eloquent magic, generics, `new static`). Fix new phpstan errors at the source, not by masking them with new neon rules. Global suppression is a rare exception. First, reach consensus through a second-opinion loop with your peer agent that the error cannot be fixed at the source or narrowed locally, and that the pattern is frequent enough to justify global suppression. Then STOP, explain the reason and recommended suppression to the owner, and wait for approval before adding it.
8. **Environment reads outside config files.** Framework source reads the environment outside config files only for a deliberate infrastructure need, such as reads before configuration loads, process transport like `__HYPERVEL_CONTEXT`, or test infrastructure like worker tokens. Use `Env::get()` with an inline `@phpstan-ignore hypervel.noEnvCallsOutsideOfConfig (reason)` stating that need. `Env::get()` is the convention for these intentional reads; switching from `env()` does not fix a read in the wrong place. Do not add directory, path or class-wide exemptions.

## Porting Packages

Expand Down
2 changes: 1 addition & 1 deletion composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@
"ext-pcntl": "*",
"ext-pdo": "*",
"ext-posix": "*",
"ext-redis": "^6.1",
"ext-redis": "^6.3",
"ext-session": "*",
"ext-simplexml": "*",
"ext-sockets": "*",
Expand Down
77 changes: 77 additions & 0 deletions docs/plans/todo/phpredis-6.3-minimum.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# Framework-wide PhpRedis 6.3 minimum

## Status and purpose

Deferred; obtain authorization before implementing. Development and tests already require PhpRedis `^6.3` in the components root manifest. Published packages continue supporting their existing client versions, including the separate requirements for hash-field expiration.

Adopt one PhpRedis minimum across installed applications to remove obsolete client-version branches. Hash-field expiration is used by Redis cache tagging and user-session tracking; the native test doubles also need the methods declared by PhpRedis 6.3. Do not replace those native methods with test fixtures or add compatibility shims.

Redis remains optional for applications that do not use it. A Composer conflict rejects an installed extension below 6.3 even when that application does not use Redis; users must upgrade or unload it. Document PIE as an installation option, not a framework dependency. Before implementation, check current package availability and the current code against this plan.

## Metadata and installation

- Keep root `composer.json` at `ext-redis: ^6.3`; update `src/horizon/composer.json` to the same requirement.
- In `src/redis/composer.json`, retain the optional extension suggestion and add `"conflict": {"ext-redis": "<6.3"}`. Framework, Foundation, Cache, Session and Queue already require this package, so do not duplicate the conflict in their manifests or require Redis for every application.
- Update the Redis, Cache and Session extension suggestions to one `^6.3` requirement, removing feature-specific client clauses.
- Use Composer commands for root dependency changes. Split-package manifests have no lockfiles and are edited directly. Never commit the components root lockfile.
- Composer's conflict behavior was verified with a disposable local package: an absent extension and version 6.3 resolve; version 6.2 fails. Repeat this focused check against the final metadata rather than building a permanent Composer test harness.

## Shared requirement and diagnostics

In `src/redis/src/RedisRequirements.php`:

- Set `MINIMUM_PHPREDIS_VERSION` to `6.3.0` and remove its separate-feature qualification.
- Remove `HASH_FIELD_EXPIRATION_PHPREDIS_VERSION` and `hashFieldExpirationClientError()`.
- Add `clientError(string|false $version): ?string`, accepting `phpversion('redis')` directly. Return null for supported clients; report the required and installed versions otherwise. For false, say the extension is not installed rather than presenting a fictitious version zero. Include `pie install phpredis/phpredis` as the installation/upgrade instruction.
- Preserve the Redis and Valkey server constants and `hashFieldExpirationServerError()`.

Use the shared client check in both diagnostics:

- `src/cache/src/Redis/Console/Doctor/Checks/PhpRedisCheck.php`: remove the tag-mode constructor parameter and private version-selection method. Update construction in `DoctorCommand.php`. Retain missing-extension detection and useful install/upgrade instructions. Use the spelling `PhpRedis` consistently in the touched output and matching tests.
- `src/doctor/src/Diagnostics/RedisSupportsConfiguredFeatures.php`: check the client once, then check servers only for configured features requiring hash-field expiration. Remove the second, feature-specific client check and the `?: '0'` conversion. Retain inactive-service skipping, real connection failures and cancellation handling.

Do not add production test seams to diagnostics. Test version decisions through the existing plain-input requirement test and retain existing diagnostic integration coverage.

## Remove obsolete client branches

- In `RedisConnection::setOptions()`, remove the pre-6.2 `OPT_PACK_IGNORE_NUMBERS` availability guard. Keep the option mapping and normal invalid-option validation. Remove the stale PhpRedis 6.0 qualification from `pack()`.
- In `Foundation/Testing/Concerns/RequiresHashFieldExpiration`, remove the client branch and `detectedPhpredisVersion()`. Keep server detection, memoization, skip reasons and `flushHashFieldExpirationState()`.
- Remove corresponding old-client test cases and version-dependent skips. Preserve supported behavior assertions and server-capability tests.

### Boundaries that stay

- Ordinary Redis server 6.2+ and Valkey 7.2+ remain supported. Features using hash-field expiration still require Redis 8+ or Valkey 9+.
- Keep cache doctor's `RedisVersionCheck` and `HashFieldExpirationCheck`, including the actual command probe. A supported PHP client does not establish server or command availability.
- Keep optional serializer/compression build checks and Cluster-specific limitations such as TCP keepalive behavior.
- Keep service opt-in skips in reusable integration-test traits. A configured but unusable Redis connection must still fail.
- The hash-expiry call-site audit covers native calls and Lua in AnyTag `Add`, `Put`, `PutMany`, `Touch`, `Increment`, `Decrement` and `Forever`, plus `RedisSessionHandler` and cache doctor checks. Their remaining branches select topology, TTL, configured tag mode, tracking or metadata behavior; they are not old-client fallbacks and must not be removed for this bump. Facade annotations and telemetry command names need no change.

## Tests to update

- `tests/Composer/PackageManifestConsistencyTest.php`: remove the `ext-redis` subset exception and its unused imports and parser; exact equality applies again once the development and published requirements match.
- `tests/Redis/RedisRequirementsTest.php`: move existing client cases to `clientError()`, use false for the missing extension, and retain older/prerelease/minimum/newer version cases and all server cases.
- `tests/Redis/PackageMetadataTest.php`: preserve the optional-extension assertions; add the conflict assertion to that existing test.
- `tests/Session/PackageMetadataTest.php`: update the exact extension-suggestion assertion. Horizon's metadata test already checks the dependency's presence.
- `tests/Foundation/Testing/Concerns/RequiresHashFieldExpirationTest.php`: remove the old-client skip case, version stub property, assignments and override; retain server failures and memoization coverage.
- `tests/Cache/Redis/Console/DoctorCommandTest.php`: replace the tag-mode client-version dataset with the single-baseline check; remove the old-client skip from the zero-named-store case and update changed diagnostic text.
- `tests/Doctor/Feature/Diagnostics/RedisSupportsConfiguredFeaturesTest.php`: remove obsolete version attributes and the unsupported-client-only integration test; the shared requirement test covers that decision.
- Remove `OPT_PACK_IGNORE_NUMBERS` skips in `tests/Redis/RedisConnectionTest.php`, `tests/Redis/PhpRedisClusterConnectionTest.php`, `tests/Integration/Cache/Redis/RedisStoreTest.php` and `tests/Integration/Cache/Redis/SerializationIntegrationTest.php`. Delete the standalone test expecting the old-client availability exception.
- Remove redundant Redis extension-presence attributes from `tests/Integration/Horizon/Feature/SupervisorTest.php` and `tests/Integration/Queue/Redis/{RedisQueueDriverTest,RedisQueueTest,ThrottlesExceptionsRedisStoreTest,RateLimitedRedisStoreTest}.php`: the development root requires the extension. Remove unused imports; do not remove service configuration checks.

## Documentation and CI

- Update the root README and `src/docs/installation.md` minimum. State 6.3 and show `pie install phpredis/phpredis` in `src/docs/redis.md` installation guidance.
- Amend the existing Redis sentence in `src/docs/porting-from-laravel.md` with the minimum and an installation link; do not add a duplicate section.
- Remove redundant client-version qualifiers from `src/docs/cache.md`, `src/docs/session.md`, the `pack_ignore_numbers` documentation, and `RedisStore::setTagMode()`. Preserve server requirements and explain Redis **or** Valkey, not both together.
- Update foundation `config/cache.php` and `config/session.php`, plus both application skeleton mirrors, to describe only the additional server requirements for the relevant features.
- Update stale client-skip comments in `tests/Integration/Cache/Redis/RedisCacheIntegrationTestCase.php` and `tests/Integration/Auth/Redis/EloquentUserProviderCacheTagsTest.php`.
- Remove the two feature-specific PhpRedis comments in `.github/workflows/redis.yml`. The CI Dockerfile already installs and validates 6.3: retain those build checks and change the validation error's rationale from integration coverage to the framework minimum. No new installation workflow, installer dependency or manually pinned binary is needed.
- Leave historical plans and the factual INCREX note in `docs/todo.md` unchanged. Do not update consumer lockfiles merely to replace suggestion text.

## Verification and completion

Search all source, tests, manifests, configuration, CI and docs for the removed symbols and client-version requirements, including raw hash-expiry commands in Lua. Check private package/application consumers under the normal consumer-check rules; none referenced the removed helpers at investigation time.

Run each edited test file immediately. Exercise existing cache hash-expiry and Redis session-tracking integration coverage with an isolated Redis service; rely on CI for the full Redis/Valkey/Cluster matrix. Validate Composer metadata and optional-extension conflict behavior, run source analysis and formatting, then self-review and obtain code review before committing and publishing.

The final change must contain no obsolete client branches, test stubs, skips or explanatory text. Preserve the server/build/topology checks above. This is a requirement and maintenance improvement, with no new hot-path work or changes to application-facing Redis operations.
Loading
Loading