Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
78 commits
Select commit Hold shift + click to select a range
8cd5fd3
docs: plan reliable server reloads
binaryfire Aug 9, 2026
7f99de9
Merge remote-tracking branch 'origin/0.4' into feature/server-reloader
binaryfire Aug 12, 2026
d476ee8
feat(foundation): define worker configuration reload contract
binaryfire Aug 12, 2026
b17fcbc
fix(container): forget cached instances through aliases
binaryfire Aug 12, 2026
2724c45
feat(server): add programmatic worker reloading
binaryfire Aug 12, 2026
d5fe5cf
feat(managers): reset named instances during worker reload
binaryfire Aug 12, 2026
9db76bd
feat(auth): refresh auth and password managers on reload
binaryfire Aug 12, 2026
1d52bc8
feat(broadcasting): rebuild broadcasters after config reload
binaryfire Aug 12, 2026
95bde95
feat(bus): rebuild batch repositories after config reload
binaryfire Aug 12, 2026
bfc0c8d
feat(cache): refresh stores and seal pre-fork Swoole tables
binaryfire Aug 12, 2026
a4cbbc3
feat(database): rebuild connection resolvers after config reload
binaryfire Aug 12, 2026
1ca0297
feat(security): refresh encryption and hashing services
binaryfire Aug 12, 2026
e9fdc7d
feat(filesystem): rebuild disks after config reload
binaryfire Aug 12, 2026
d5b3d87
fix(config): replay derived worker configuration
binaryfire Aug 12, 2026
a77cc28
feat(log): refresh channels and the retained stdout logger
binaryfire Aug 12, 2026
9d17758
feat(mail): refresh mail and notification services
binaryfire Aug 12, 2026
03ef2b2
fix(object-pool): clear inherited pools before server fork
binaryfire Aug 12, 2026
764db15
feat(queue): rebuild connections after config reload
binaryfire Aug 12, 2026
2f13f97
feat(session): refresh retained cookie and session state
binaryfire Aug 12, 2026
b06f0f1
feat(routing): refresh the retained URL generator
binaryfire Aug 12, 2026
dd9da35
feat(packages): refresh optional manager state on reload
binaryfire Aug 12, 2026
8c637c7
feat(reverb): refresh worker-owned application state
binaryfire Aug 12, 2026
46003e5
feat(jwt): refresh claims, parsing, and blacklist state
binaryfire Aug 12, 2026
50d0703
feat(sentry): rebind clients without replacing the shared hub
binaryfire Aug 12, 2026
0ba75d4
feat(telescope): refresh retained storage repositories
binaryfire Aug 12, 2026
cd4fe0b
feat(translation): preserve registered lines across config reload
binaryfire Aug 12, 2026
d0c57b8
feat(view): refresh retained finder and compiler configuration
binaryfire Aug 12, 2026
2fca1e7
feat(foundation): refresh provider state before worker readiness
binaryfire Aug 12, 2026
268f2a0
docs: explain worker configuration reload boundaries
binaryfire Aug 12, 2026
bdf7c7d
docs(plan): record the server reload design
binaryfire Aug 12, 2026
2b04cb6
fix(foundation): separate the CLI output property
binaryfire Aug 12, 2026
64dfbe2
Merge remote-tracking branch 'origin/0.4' into feature/server-reloader
binaryfire Aug 13, 2026
9aad6eb
Merge remote-tracking branch 'origin/0.4' into feature/server-reloader
binaryfire Aug 13, 2026
2e0b6fd
fix(http): refresh connection state across worker reloads
binaryfire Aug 13, 2026
fcd12fb
Merge remote-tracking branch 'origin/0.4' into feature/server-reloader
binaryfire Aug 13, 2026
1a9e5f2
Merge remote-tracking branch 'origin/0.4' into feature/server-reloader
binaryfire Aug 14, 2026
fb4d826
docs(server): simplify reload process guidance
binaryfire Aug 14, 2026
75c22a4
fix(queue): preserve fakes during worker refresh
binaryfire Aug 14, 2026
5e6a1c4
Merge pull request #511 from hypervel/feature/server-reloader
binaryfire Aug 14, 2026
98b4c5b
Register the lost connection detector contract
binaryfire Aug 14, 2026
c57d131
Expand Laravel porting guidance
binaryfire Aug 14, 2026
f5ed358
Test request binding context behavior
binaryfire Aug 14, 2026
181d4c7
Document request context setup in tests
binaryfire Aug 14, 2026
ad3e8ea
Rewrite framework README
binaryfire Aug 14, 2026
4c3a2bc
Rewrite framework introduction
binaryfire Aug 14, 2026
45daf6a
Standardize Composer package metadata
binaryfire Aug 14, 2026
1246f07
Clarify 0.4 documentation status
binaryfire Aug 14, 2026
9c01cd2
Track skeleton README documentation links
binaryfire Aug 14, 2026
a4b4819
Credit upstream package projects
binaryfire Aug 14, 2026
d5f887b
Fix concurrency driver configuration ownership
binaryfire Aug 14, 2026
051611d
Use named container APIs in foundation runtime
binaryfire Aug 14, 2026
7c63a51
Preserve middleware bindings after test overrides
binaryfire Aug 14, 2026
acc61bf
Use named services in foundation test helpers
binaryfire Aug 14, 2026
4214308
Use named container APIs in database components
binaryfire Aug 14, 2026
80b187b
Use named container APIs in queue components
binaryfire Aug 14, 2026
77d64e2
Type the facade application as a container
binaryfire Aug 14, 2026
99852ef
Use named container APIs in support components
binaryfire Aug 14, 2026
8f97cfd
Use named application APIs in Testbench
binaryfire Aug 14, 2026
9dd9961
Use named container APIs in testing utilities
binaryfire Aug 14, 2026
1b9e065
Use named container APIs in console components
binaryfire Aug 14, 2026
e64145d
Use named container APIs in cache components
binaryfire Aug 14, 2026
a7cee3c
Use named container APIs in logging components
binaryfire Aug 14, 2026
9e89938
Resolve Sentry configuration through typed APIs
binaryfire Aug 14, 2026
434bc7f
Resolve filesystem URL services by name
binaryfire Aug 14, 2026
4cbdee5
Use named container APIs in validation
binaryfire Aug 14, 2026
74b790d
Use named container APIs in foundation tests
binaryfire Aug 14, 2026
e9f9f89
Use named container APIs in foundation integration tests
binaryfire Aug 14, 2026
98c7dda
Use named application APIs in command integration tests
binaryfire Aug 14, 2026
643fcf8
Use named container APIs in authentication tests
binaryfire Aug 14, 2026
65cc1f4
Use named container APIs in HTTP and routing tests
binaryfire Aug 14, 2026
5853acb
Use named container APIs in application feature tests
binaryfire Aug 14, 2026
3d894fc
Use named container APIs in Horizon tests
binaryfire Aug 14, 2026
3c85a63
Use named container APIs in Reverb tests
binaryfire Aug 14, 2026
369fc89
Use named container APIs in Telescope tests
binaryfire Aug 14, 2026
e0af49f
Remove container array and dynamic property access
binaryfire Aug 14, 2026
1dce49c
Document the named-only container API
binaryfire Aug 14, 2026
21738fe
Align contribution guidance with named container APIs
binaryfire Aug 14, 2026
a019b3f
Add the container named API implementation plan
binaryfire Aug 14, 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: 6 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,7 @@ The Working rules and the Avoid overengineering rules apply to all work in this

- **Use one source of truth** — Put all user documentation in `src/docs/`. Package READMEs are intentionally minimal, not a second documentation surface, and must not duplicate user documentation.
- **Write user documentation in Laravel-docs prose** — Use the simple, direct, human-friendly style of first-party Laravel documentation. Prefer natural explanations and examples over implementation language; avoid internal jargon, stiff wording, and needless detail.
- **Keep the Laravel porting guide current and focused** — Whenever a framework change introduces, changes, or removes a public API, feature, configuration surface, or supported integration in a way that a Laravel application or package porter genuinely must account for, update `src/docs/porting-from-laravel.md` in the same change. Hard boot or runtime failures, silent semantic differences, and commonly used framework surfaces normally qualify. Internal implementation differences, performance work that preserves the public contract, incidental source drift, package-specific details, and narrow edge cases that do not change normal porting decisions do not. The guide is a high-signal starting context for humans and LLMs, not an exhaustive framework diff or dumping ground. Treat its context size as a design constraint: keep additions concise and action-oriented, link to the canonical feature documentation instead of duplicating its detail, and remove stale or duplicated guidance whenever editing the guide.

#### Package READMEs

Expand Down Expand Up @@ -194,14 +195,14 @@ Build complete, long-term solutions, not MVPs or local workarounds. A broad chan
- **Use `Sleep::usleep()` / `Sleep::sleep()` for delays in source code** — `Sleep` is fakeable in tests. Use raw `sleep()` / `usleep()` only where real time must pass, such as test harnesses and external-process polling.
- **Use `xxh128` for internal non-cryptographic hashing** — cache and context keys, content checksums, and change detection. It is faster than `sha256`, which is reserved for trust boundaries: stored credential digests, signatures, and anything an attacker gains by forging. Seed it when the hashed value comes from user input, as `SwooleStore` does for its physical table keys.
- **Use immutable dates by default** — Hypervel defaults to `Hypervel\Support\CarbonImmutable`, including where Laravel uses mutable Carbon. Create public or application-configurable dates through the `Date` facade or date helpers, and use exact `CarbonImmutable` for framework-owned internal or held values. Type configurable Carbon boundaries as `CarbonInterface` and native or third-party boundaries as `DateTimeInterface`. Capture the return value of every date modifier whose result must persist. Use `Hypervel\Support\Carbon` only for explicit mutable opt-out or conversion behavior.
- **Use typed config getters and avoid duplicate defaults** — prefer `$config->string()`, `$config->integer()`, `$config->float()`, `$config->boolean()`, and `$config->array()` over `$config->get()` for values that cannot be null. Framework and package defaults are shallow-merged with application config. `mergeableOptions()` is only for named groups such as connections or stores: application entries replace matching defaults, while other default entries remain. Other nested arrays are replaced as a whole. Keep a fallback when a setting inside one of those replaced arrays is intentionally optional.
- **Use typed config getters and avoid duplicate defaults** — prefer `$config->string()`, `$config->integer()`, `$config->float()`, `$config->boolean()`, and `$config->array()` over `$config->get()` for values that cannot be null. Do not pass a code-level fallback when the framework or package config defines the key; missing or misspelled keys should fail loudly instead of silently using a second default. Framework and package defaults are shallow-merged with application config. `mergeableOptions()` is only for named groups such as connections or stores: application entries replace matching defaults, while other default entries remain. Other nested arrays are replaced as a whole. Keep a fallback when a setting inside one of those replaced arrays is intentionally optional.
- **Env var naming** — Ported config keeps upstream names. New Hypervel-specific settings should use the established prefix for the package or subsystem that owns the value (`SERVER_`, `CACHE_`, `REDIS_`, etc.). Determine ownership semantically, not from the config filename: aggregate files such as `app.php` contain multiple domains, and `APP_` is for genuinely application-wide settings. If a value mirrors another config key, reuse that key's environment variable instead of defining a duplicate.
- **Use `resolve...Using` for Hypervel-owned config resolvers** — prefer this naming for callbacks that resolve config-derived values, unless an established Laravel domain convention already exists, such as `redirectUsing()`.
- **Always use American English spelling** — E.g., "behavior" vs "behaviour", "utilize" vs "utilise".

## Container

Hypervel's container keeps Laravel's API surface — `bind()`, `singleton()`, `scoped()`, `instance()`, aliases, contextual bindings — with resolution adapted for long-lived Swoole workers. `make()` and `get()` resolve identically; `get()` is just the PSR-compliant exception wrapper. Use `make()`, and use it instead of array access too: `offsetGet()` always returns `mixed`, while `make()` carries class-string generics phpstan can follow, `make()` can take parameters, and `$app[$key] = $value` is a hidden `bind()`. Converting `$app['...']` in ported code to `make()` is an approved modernization (see Policy under Porting Packages). `Container::getInstance()` auto-creates via `??= new static()`, so it always returns a container.
Hypervel's container keeps Laravel's named API surface — `bind()`, `singleton()`, `scoped()`, `instance()`, aliases, contextual bindings — with resolution adapted for long-lived Swoole workers. Container ArrayAccess and dynamic service properties are intentionally unsupported. `make()` and `get()` resolve identically; `get()` is the PSR-compliant exception wrapper. `Container::getInstance()` auto-creates via `??= new static()`, so it always returns a container.

### Resolution semantics vs Laravel

Expand Down Expand Up @@ -726,7 +727,7 @@ Full PHPStan runs through `composer fix` at checkpoints. During implementation,
When porting Laravel packages, whether first-party or third-party, keep them as close to 1:1 with upstream as possible so future changes are easy to merge. The exceptions are:
- Modernizing PHP types, including native parameter, return, property, and class-constant types, plus other appropriate PHP 8.4+ features, strict types, and strict comparisons
- Converting mutable Laravel date construction to Hypervel's immutable date conventions, typing configurable factory output as `CarbonInterface`, and capturing date-modifier return values
- Converting container array access (`$app['events']`) to `make()`, and untyped `$config->get()` calls to the typed getters where the key isn't nullable (see Container and the typed-getter rule under Development Conventions)
- Converting container array access (`$app['events']`) and dynamic service-property access (`$app->events`) in ported code to named container methods, and untyped `$config->get()` calls to typed getters where the key isn't nullable (see Container and the typed-getter rule under Development Conventions)
- Adding Laravel-style title docblocks to methods (not classes — see Development Conventions)
- For ported Laravel packages: making them coroutine-safe, adding Swoole performance enhancements (e.g., static property caching), making them pass PHPStan
- Not porting upstream framework-specific integrations that only make sense in the source framework (for example packages, drivers) unless Hypervel intentionally has an equivalent surface
Expand Down Expand Up @@ -879,6 +880,7 @@ Tests for these features should be **removed** (not commented out) without askin
- **Databases:** SQL Server, MongoDB, DynamoDB — Hypervel only supports MySQL, MariaDB, PostgreSQL, and SQLite
- **Cache drivers:** Memcached, DynamoDB, MongoDB
- **Dynamic connections:** `DB::build()`, `DB::connectUsing()` — incompatible with Swoole connection pooling
- **Container access:** ArrayAccess and dynamic service properties

This list is exhaustive. Any other missing functionality requires investigation and reporting per When to Stop and Report.

Expand All @@ -893,5 +895,5 @@ This list is exhaustive. Any other missing functionality requires investigation
7. Fix mock types (PDO, QueryBuilder, Grammar, etc.)
8. Add `->andReturnSelf()` to chained method mocks
9. Use a test-specific namespace only when helper classes have generic, collision-prone names — already-specific helper names do not need extra namespace ceremony.
10. Remove tests for unsupported features (SQL Server/MongoDB/DynamoDB databases, Memcached/DynamoDB/MongoDB cache, dynamic connections)
10. Remove tests only for the approved unsupported features listed above
11. Run tests and fix any remaining type errors
Loading
Loading