Add the first-party Data component - #30
Closed
binaryfire wants to merge 39 commits into
Closed
Conversation
Make contextual attribute results authoritative, including null, so constructor resolution cannot silently fall through to defaults, contextual bindings, or fabricated class instances. Keep public build() and buildWith() as raw construction APIs while retaining SelfBuilding dispatch on normal container resolution. Add request-attribute injection, reusable route and authenticated-user property extraction, and declaration-ordered BindWhen support with reevaluation of conditional misses. Document the worker-lifetime BindWhen constraint and Laravel null-resolution difference, declare the Collections dependency used by property extraction, and cover direct construction, binding precedence, contextual stacks, execution scoping, interleaving, extraction failures, and PHP 8.5 conditional bindings.
Move FormRequest's unknown-input check into a Validation-owned helper that reads the validator's effective rules, confirmation fields, declared array subtrees, exact additions, and whole-segment wildcard allowances. Walk the original nested input without flattening literal dot or asterisk keys, retain unescaped public error paths, and fail closed at unsupported escape boundaries. Keep FormRequest's body-versus-query behavior while allowing contents of genuinely free-form array rules and preserving strict structured descendants. Add focused helper and FormRequest regressions for exact, wildcard, escaped, confirmation, opaque-subtree, and structured-array behavior.
Normalize rules before wildcard merging, preserve first-declared wildcard identity, clear implicit state when rule graphs are replaced, and support literal asterisks plus Laravel-compatible partial-segment wildcards without weakening missing-leaf validation. Count immutable presence-check consumers in compiled plans so exact Exists and Unique rules can use the existing guarded batch path alongside wildcard rules. Retain ordinary execution for callbacks, unsafe query shapes, mutation-sensitive cases, custom validators and verifiers, exclusions, uploads, and stop-on-first-failure. Make string-reducing rule detection reusable by Data's conservative comparisons, reject unsupported email validation modes instead of silently changing semantics, align NotIn's native input type with In, and clean the Can constructor. Cover parser precedence, stale rule replacement, wildcard identity and dependent substitution, literal keys, partial patterns, exact database batching, mutation-aware fact reuse, fallbacks, repeated passes, and strict email diagnostics.
Register hypervel/data in the component monorepo and subtree metadata, retain the upstream MIT attribution, and define the package's Data, DTO, resource, collection, validation, transformation, and wrapping capability contracts. Build one typed DataConfig at provider boot from required shallow-merged configuration. Validate mapper, cast, transformer, and normalizer extension classes eagerly; keep only immutable recipes and scalar settings; and provide an atomic boot-only morph alias map with forward and reverse collision checks. Ship familiar OnlyRequests defaults, explicit input and output mapping settings, optional depth and wrapping settings, provider discovery, publishing metadata, and focused configuration, morph-map, discovery, and dependency tests.
Add the familiar mapping, casting, lazy, computed, relation, morph, and validation-control attributes together with immutable DataClass, DataProperty, DataMethod, DataParameter, and native/PHPDoc type models. Resolve constructor ownership, inheritance, promoted and contextual parameters, named factories, iterable annotations, unions, intersections, DNF types, mapper precedence, and duplicate input/output ownership once per declared Data class. Cache only bounded class and source import metadata for the worker lifetime. Keep annotation selection in DataClassFactory, resolve imported names in the class that declared the annotation, preserve late-bound static semantics, and retain reflection recipes rather than request-derived or mutable extension instances. Cover metadata immutability, declaration scope and import precedence, recursive graphs, constructor binding, mapping collisions, method matching, contextual declarations, PHPDoc generics, type guarantees, and actionable invalid-declaration diagnostics.
Provide Spatie-familiar validation attributes for Hypervel's supported Laravel rules, plus thin first-party wrappers for Hypervel-native rules. Preserve backed enums, external references, field references, fluent Exists and Unique constraints, strict numeric strings, and canonical nested null encoding without a second validation implementation. Compile inferred, declared, nested, mapped, contextual, and unknown-field rules into one root Validator. Use structural wildcard graphs for uniform collections, sparse concrete fallbacks for divergent items, conservative accumulator equality for dynamic rules, and marker provenance that preserves Laravel Distinct and dependent-field identity. Construct from filtered validated payloads, restore only declared WithoutValidation and finished values, preserve source key order, support authorization, messages, attributes, redirects, Precognition, and validator hooks, and keep all request state in the root operation. Cover rule denormalization, every attribute family, database constraints, mapped paths, finished subtrees, wildcard and concrete compilation, strict unknown fields, lifecycle hooks, payload ordering, Exact and Distinct identity, dynamic graphs, and validation accumulator equivalence.
Expose Data, Dto, Resource, Optional, Lazy, and typed DataCollection entry points through one non-recursive creation engine. A root operation owns immutable options, mutable traversal state, normalizer and extension reuse, validation orchestration, and bottom-up object construction. Normalize arrays, JSON, Arrayable objects, public object properties, requests, and Eloquent models without broad serialization. Select named factories once, preserve finished compatible values, reconcile hook payloads, resolve absence in default-Optional-null order, and inject contextual constructor parameters only after validation succeeds. Add built-in scalar, enum, date, iterable-item, and Castable handling with explicit Uncastable fallback. Rebuild declared collection shapes through one DataCollectableFactory, preserve raw keys and paginator reconstruction state, and fail clearly for ambiguous or unsupported declarations. Cover source boundaries, prepared and normalized values, sparse structure state, named and container-assisted factories, contextual precedence, private constructors, defaults, casts, enums, dates, nested values, iterable containers, morph selection, and non-recursive creation.
Transform current public values through precompiled metadata without an output cache. Add built-in Arrayable, enum, and date transformers; Optional omission; computed, hidden, appended, and lazy values; JSON output; global and instance wrapping; and configurable maximum-depth failures. Compile include, exclude, only, and except definitions into immutable endpoint, subtree, and child trees. Merge reached nested instance partials at property and iterable-item boundaries, preserve temporary versus permanent ownership, and keep ordinary transforms on the no-partials fast path. Reuse one transformation context and extension memo across nested objects and collection items while keeping per-item partial state isolated. Preserve raw nested identity for all(), consume lazy values only when selected, and expose current values after mutation. Cover partial-tree semantics, nested and repeated instance selections, lazy conditions, wrapping, appended and empty data, live properties, mapped output, typed iterable transformation, context promotion, depth limits, and JSON behavior.
Measure native construction, explicit SDK-style mapping, and the existing flat and nested DataObject paths with warmup, repeated samples, median and p95 latency, operations per second, peak memory, and checksum validation. Record the commit, PHP and OS versions, loaded extensions, OPcache and JIT state, and workload size. Support optional JSON and CSV reports outside the repository so later fixed-engine measurements can be compared on the same machine without encoding arbitrary thresholds into tests.
Register Spatie Laravel Data 4.23.0 in the upstream sync manifest and record the reviewed main and v5 draft commits so future release work can distinguish already-considered changes from new upstream work. Repair the sync guide's stale porting-document references so package syncs consistently use the authoritative Porting Packages and stop-and-report rules in AGENTS.md.
Track TypeScript generation as a general Hypervel package that can inspect ordinary PHP classes and enums as well as Data metadata. Keep filesystem discovery and code generation outside hypervel/data, with an optional adapter for mapping, Optional, lazy, and collection semantics, so runtime Data construction remains independent of that separate tooling concern.
Define the intended public Data, Dto, Resource, Optional, Lazy, collection, mapping, casting, validation, transformation, resource, Eloquent, Inertia, Saloon, and VarDumper surfaces using familiar Laravel and Spatie vocabulary where it remains well designed. Specify Hypervel-native fixed creation and transformation engines, immutable worker-lifetime metadata, per-operation state, one-root validation, wildcard and concrete collection compilation, contextual constructor injection, safe abstract morph persistence, and framework-owned extension points without configurable pipelines or deploy metadata caches. Record the complete upstream research and disposition, framework changes, implementation order, edge-case matrix, performance harness, verification commands, and completion audit. The plan favors first-class Hypervel integration, coroutine safety, measured performance, Laravel ergonomics, and direct code over parity-only machinery.
Bring the Data package worktree onto the latest greenfield framework baseline before finalizing the feature series. This incorporates the current component fixes, dependency constraints, documentation-plan maintenance, and resource collection key handling from 0.4 without changing the Data package design. The merge resolved cleanly; the overlapping root Composer metadata and todo entries retain both the framework updates and the new Data package registration and TypeScript follow-up. The complete merged tree was verified with composer fix, including both PHPStan configurations, 34,181 parallel tests, 542 Testbench tests, and the dogfood package suite. The retained Data benchmark was also rerun against this baseline.
Resolve inherited native and PHPDoc types in their declaration scopes, preserve annotation precedence, and reject ambiguous input and output ownership while metadata is built. Compile the additional type, constructor-binding, mapped-path, and named-factory facts needed by the fixed engines. Expand focused coverage for aliases, multi-namespace imports, inheritance, iterable annotations, mapping collisions, and invalid declarations.
Add Validator::retainRules() so Precognition narrows the graph already expanded for the current payload without replacing wildcard identity or the original declarations used by setData(). Move FormRequest, request macros, and request validation helpers onto the new contract. Tighten unknown-field path handling and cover retained dependent rules, wildcard labels, graph rebuilding, and Precognition behavior.
Finalize mapped validation paths, finished-value suppression, wildcard identity markers, rule denormalization, and root-validator orchestration for uniform and divergent nested data graphs. Align strict validation attributes with Hypervel's native rule contracts, including database constraints, dependent null values, numeric strings, and object rules. Expand the focused compiler, path, attribute, and constraint regression suites.
Finish the single root creation engine for mapped sources, named factories, contextual constructor values, morphs, typed iterables, paginator provenance, validation reconciliation, and bottom-up instantiation. Reuse compiled input paths and a narrow exact-array fast path while preserving the full general path for casts, hooks, lazy values, and complex graphs. Expand regression coverage for defaults, nulls, finished values, factories, mappings, collections, and deferred construction state.
Finalize live transformation, output mapping, nested partial composition, constructable persistence views, resource-specific transformation boundaries, and typed iterable handling without cached result state. Add closure and relation-aware automatic lazy values with pruned replay state, repeatable resolution, and explicit persistence failures. Cover partial lifetimes, nested collections, source retention, dates, enums, Arrayable values, and depth limits.
Complete keyed, lazy, paginated, and cursor-paginated Data collections with precise collect() contracts, source-shape rebuilding, side-effect-free reads, transient lifetimes, and paginator metadata preservation. Integrate transformable Data types with Eloquent JSON casts and Hypervel JSON resources through package-owned adapters. Add per-instance resource wrapping, constructable persistence views, strict morph envelopes, order-insensitive dirty comparison, and focused runtime and PHPStan coverage while removing the database-owned legacy cast.
Add explicit AsData and AsDataCollection adapters that reuse the package creation engine through Foundation's generic Castable contract. Remove Foundation's special-case DataObject branch and legacy array and collection casts. Keep the general request-casting extension unchanged and cover single objects, typed collections, arrays, and explicit target containers.
Adapt Data lazy values to Hypervel Inertia's optional and deferred props, including group and rescue options and exact preservation of existing deferred prop state. Keep the integration behind explicit factories so ordinary Data loading and transformation do not resolve Inertia classes, with focused initial, partial, deferred, serialized, and concurrent-request coverage.
Provide the familiar generic WithData trait for models, requests, and ordinary source objects that declare their associated Data class through a property or method. Preserve property-before-method precedence, return precise static-analysis types, and fail clearly for missing or invalid declarations. Cover request validation and non-request source behavior through the shared construction engine.
Register typed Data configuration at worker boot, add the Laravel-style make:data generator and application stub override, and install one stateless Symfony VarDumper caster for transformable Data values. Extend optional-package test cleanup to the four independent Data macro registries. Cover command naming and overwrite behavior, provider idempotence, custom dump casters, logical dump output, and cleanup without forcing optional package loading.
Cover request- and connector-produced Data objects, DTO priority, static-analysis inference, and attachment of Saloon responses through the existing WithResponse contract. Keep hypervel/data independent from Saloon runtime code while proving generated SDK DTOs can use the first-party Data APIs directly.
Delete the old monolithic DataObject and its API-specific test suite now that construction, validation, transformation, persistence, request casting, and response behavior are owned by hypervel/data. Avoid compatibility aliases, global casting switches, serialized output caches, and duplicate cleanup paths in the greenfield 0.4 codebase.
Retain reproducible warmup, sampling, percentile, throughput, memory, and environment reporting for flat and nested construction, large collections, validation graphs, named factories, metadata reuse, transformation, and Eloquent relation loading. Include exact-array success and miss measurements plus native/manual baselines so future optimizations must show a real same-machine benefit without hard-coded timing gates.
Link the canonical Data Objects guide, retain upstream attribution, and record only the lasting public differences developers need to know when moving from Laravel Data. Document Hypervel's fixed factory contexts, null and Optional semantics, first-source precedence, contextual constructor values, normalized collect factories, and wildcard-aware validation behavior without duplicating the full guide.
Replace the legacy DataObject guide with the complete hypervel/data API: construction, validation, mapping, casts, factories, lazy values, partials, collections, resources, Eloquent persistence, Inertia, VarDumper, and extension contracts. Update API client, Saloon, Eloquent, Validation, and Laravel-porting guidance to use the new package and its owning framework APIs. Keep examples Laravel-shaped while calling out the few deliberate Hypervel behavior differences.
Bring the active design document in line with the signed-off implementation after the full second-opinion and code-review loops. Record the final construction, validation, collection, lazy, persistence, resource, metadata, typing, performance, and framework-integration invariants while removing superseded proposals and implementation history that no longer guides the code.
Bring the latest framework correctness fixes and the Container/Telescope context-state improvements into the Data package branch. Reconcile the Container changes by passing the active ContainerResolutionState through the resolution-only SelfBuilding path while preserving public build() as raw construction. Retain the Data branch's contextual-null and BindWhen documentation and all focused Container coverage.
Precompute bounded Data type partitions, contextual parameter ownership, constructor eligibility, and property-hook facts in immutable worker metadata. Remove repeated filtering and forwarding helpers from creation and validation. Add the measured exact constructor exit, reuse creator-owned configuration for fresh factories, and reject unsupported non-public or variadic ordinary construction through actionable shared errors. Keep direct-returning named factories valid and preserve all ordinary fallback behavior. Reuse immutable default, all, and persistence transformation contexts, retain fresh contexts for partial-bearing objects, and copy plain objects in metadata order while invoking property hooks only when selected. Cover direct-path equivalence, fallback guards, contextual ownership, virtual properties, partial consumption, and inherited property ordering.
Resolve the worker-shared DataTransformer once per Eloquent caster and reuse its immutable constructable context for singular and collection writes. Continue dispatching through each Data object's public transform() boundary so application overrides remain authoritative. Add regressions proving singular and collection casts receive the persistence context, collection items share one context instance, and custom transformation overrides remain active without rebuilding mutable factories per stored value.
Replace deprecated PHPUnit message expectations in the touched date cast suite with independent current constraints. Assert both the concrete target type and accepted format so successive expectations cannot silently overwrite one another.
Add five- and twenty-property plain transformation scenarios to the retained developer harness. These workloads isolate metadata-ordered copying on narrow and SDK-shaped classes while preserving the existing same-machine median, percentile, throughput, and memory reporting.
Explain that ordinary property-based construction cannot infer variadic argument expansion and direct users to a named factory that returns the target object. Add the standard Credits section and upstream Spatie attribution to the canonical Data Objects guide, matching the structure used by other ported Hypervel components.
Record the final measured hot-path design: immutable metadata partitions, creator-owned factories, exact-array and direct-constructor exits, shared readonly transformation contexts, metadata-ordered plain copying, and persistence dispatch through the public transform boundary. Capture the final variadic-constructor ownership and guard-ordering rules, bounded metadata cost, rejected speculative caches, benchmark evidence, focused regression coverage, and completed verification checklist. Mark the package implementation as implemented, verified, and reviewed.
Rewrite the Data guide around observable behavior and common usage, replacing internal creation, validation, transformation, resource, and metadata terminology with direct Laravel-style explanations. Clarify readonly computed properties, named factory and collection dispatch, extension reuse, unvalidated array keys, collection targets, Eloquent persistence, lazy materialization, and worker-lifetime configuration. Restore the public wildcard-rule, class-string, and structure-cache differences that porters need. Keep the package README concise, update the Eloquent cross-reference and Laravel porting guidance, and retain the Spatie credit while documenting the exact omitted APIs and their Hypervel alternatives.
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Team Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Greptile SummaryThe PR replaces the former Support DataObject with a first-party Data component and integrates it across container resolution, validation, HTTP resources, pagination, Foundation, Eloquent, and testing.
Confidence Score: 5/5The PR appears safe to merge because no blocking failure remains within the eligible follow-up review scope. No blocking failure remains.
|
| Filename | Overview |
|---|---|
| src/data/src/Support/Creation/DataCreator.php | Implements the central fixed creation flow for normalization, validation, casting, hooks, nested values, and construction. |
| src/data/src/Support/Validation/DataValidationCompiler.php | Compiles inferred and explicit Data validation rules, including nested and collection paths. |
| src/data/src/Support/Transformation/DataTransformer.php | Implements recursive output transformation, mapping, partials, lazy values, and depth handling. |
| src/validation/src/Validator.php | Extends validation preparation and database-presence batching behavior used by the Data component. |
| src/container/src/Container.php | Makes contextual attribute results, including null, authoritative and preserves raw construction boundaries. |
| src/data/src/Eloquent/AbstractDataEloquentCast.php | Provides the shared persistence envelope and serialization behavior for Data Eloquent casts. |
| src/data/src/Http/Resources/DataCollectionResource.php | Adapts transformed Data collections and cloned paginators to the native JSON-resource response path. |
| src/http/src/Resources/Json/ResourceResponse.php | Adds per-instance resource-wrapper selection while preserving existing static wrapping for other resources. |
| src/pagination/src/AbstractPaginator.php | Preserves generic collection key and value types when replacing paginator items. |
| composer.json | Registers the Data namespace, package replacement, and service provider in the monorepo package. |
Reviews (2): Last reviewed commit: "Merge remote-tracking branch 'origin/0.4..." | Re-trigger Greptile
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR replaces the old
Hypervel\Support\DataObjecthelper with a first-partyhypervel/datacomponent.The package keeps the public vocabulary that Laravel developers know from
spatie/laravel-data:Data,Dto,Resource,Optional, lazy values, typed collections, mapping, casts, transformers, inferred validation, Eloquent casts, resources, and named factories. The runtime is built for Hypervel rather than copied from Laravel's request-per-process design.Why
The previous
DataObjecthandled basic construction and serialization, but it mixed reflection, mutable global settings, output caching, and integration behavior in one class. It could not provide the validation, collection, resource, persistence, mapping, or extension surface needed by larger application and SDK object graphs without growing into a larger version of the same design.This component gives those concerns clear owners:
Data Component
The new component includes:
Data,Dto, andResourcebase classes with distinct creation, validation, transformation, and response capabilities;Optional, constructor defaults, and nullable types;DataCollection,PaginatedDataCollection, andCursorPaginatedDataCollectionwith keyed source preservation and lazy collection support;WithDatasource concern, and themake:datagenerator.The component uses a fixed creation and transformation flow. It does not add configurable pipelines, runtime class discovery, a deploy metadata cache, or mutable shared operation contexts. Custom behavior stays on named factories, attributes, contracts, and the fluent per-call factory.
Framework Integration
Several framework changes make Data a first-party feature instead of an adapter layered over unrelated APIs:
null.CurrentUserandRouteParametersupport property extraction, and the Laravel-styleRequestAttributeandBindWhenattributes are available. Rawbuild()andbuildWith()construction remain distinct from container resolution ofSelfBuildingclasses.AsDataandAsDataCollection, and Precognition narrows an already prepared validation graph instead of rebuilding it.JsonResourcestatic state.The old Support
DataObject, its Foundation casts, and the Database-owned Eloquent cast are removed. Their useful behavior is covered by the new component through the APIs above.Performance
The package analyzes each Data class on first use and keeps its immutable description in worker memory. Request payloads, validation state, factories, transformation selections, and model values remain local to their operation. There are no generated metadata files, cache-store lookups, or runtime class scans.
The following medians were measured on PHP 8.4.23 with OPcache enabled and JIT disabled. Warm scenarios used repeated samples after metadata and services had been initialized.
Data::from()Data::from()Data::from()Analyzing one class takes about 129.88 µs. A worker-cached metadata lookup takes about 82 ns. Metadata is lazy: installing or autoloading an SDK does not analyze every Data class. A stress case that used 500 independent five-property Data classes retained 7.58 MB of metadata per worker, or about 15 KB per used class.
Constructed instances remain small. Retaining 1,000 flat objects added about 221 KB, while 1,000 nested roots and their 1,000 child objects added about 389 KB after metadata was warm.
The developer benchmark harness covers native and manual baselines, cold and warm creation, nested graphs, large collections, validation, named factories, transformation, metadata, Eloquent relations, query counts, and peak memory. It records the runtime environment and supports JSON and CSV output for repeatable same-machine comparisons.
Compatibility
Hypervel 0.4 is unreleased, so this PR does not carry compatibility aliases for the old Hypervel-specific
DataObjectAPI. Existing outcomes remain available through the new package, but they use the new Data APIs.The package deliberately omits deprecated Spatie collection proxies, Livewire integration, TypeScript generation, serialization input casts, optional-value suppression switches, and structure cache commands. Hypervel contextual attributes replace package-specific
From*injection attributes. TypeScript generation remains a general tooling concern rather than a runtime Data dependency.Verification
composer fix;Documentation
The Data Objects guide documents base-class selection, creation, mapping, casting, validation, factories and hooks, transformation, lazy values, partials, collections, resources, Eloquent persistence, contextual constructor values, Inertia, Saloon, generation, worker-lifetime configuration, and upstream credit.
Related validation, Eloquent, API client, Saloon, Container, and Laravel porting guides are updated. The package README remains limited to the lasting public differences a Spatie Laravel Data user needs to account for.