Data Laravel Package

Technical Evaluation

• Architecture fit: gcego/data is a Laravel-native, domain-agnostic data access and query engine that fits applications needing a unified read/write layer over Eloquent models, database tables, query builders, collections, and class-based providers. It is strongest for multi-tenant SaaS or internal platforms that need consistent filtering, search, sorting, pagination, relation handling, field-level security, caching, transactions, and audit events. It is likely overkill for simple CRUD apps with narrow query needs.
• Integration feasibility: Feasible if the platform is already on PHP 8.3+, Laravel 13 (Illuminate), illuminate/validation ^13.0, and psr/log ^3.0. Installation is standard Composer plus config publishing in console. The typed Source::define() API centralizes data definitions, and the Data facade gives a single entry point for queries, aggregates, scoped queries, and mutations. The package now depends only on gcego/core ^1.0, reducing coupling to the broader GCEGO ecosystem.
• Technical risk: The Laravel 13 requirement is a hard gating risk if the platform is not already there. v1.0.0 contains major breaking changes from pre-1.0, including removal of new Source(...), legacy source factory methods, Property, Support\Callback, Paginate, legacy Sort/Sortable, Search, With, Includable, ->named(), FilterOperator/ValueType enums, and CustomOperator. Existing gcego/blueprints, gcego/registry, and Integration\SourceRenderer integrations are removed. Custom providers must adapt to the changed ResolvesRecords::find() signature. Security behavior around tenancy, field access, mutations, and cache isolation is high-impact and must be validated carefully.
• Key questions: Is Laravel 13 approved and available in our stack? Do we need read-only querying first, or mutations and transactions immediately? Are we replacing existing repositories/query services or wrapping them? Which source types are required: Eloquent, table, builder, collection, or custom provider? Is multi-tenancy required, and what is the tenant resolution strategy? Do we need field-level security and audit events at launch? What cache isolation model is appropriate: User, Tenant, or Shared? What is the support and release cadence for gcego/core? Do our databases support the new statement timeouts? What is the migration effort from any pre-1.0 usage? What performance overhead do caching, profiling, authorization, and transforms add?

Integration Approach

• Stack fit: Best fit is a Laravel 13 application on PHP 8.3+ with Eloquent or query-builder-backed data access. The package supports database-side aggregation and scoped queries for Eloquent and query-builder sources, with in-memory aggregation for collections. It exposes configuration for cache, transactions, performance, and events, so platform teams can tune behavior per environment.
• Migration path: For greenfield adoption, start with read-only sources and incrementally enable filters, search, sorting, pagination, relations, tenancy, field security, caching, profiling, then mutations and transactions. For brownfield pre-1.0 usage, follow docs/migration.md and replace legacy Source construction, filter definitions, removed support classes, and custom operators/providers. For replacing existing repositories, use a strangler pattern: wrap current query methods behind sources, run parallel paths, and cut over domain by domain.
• Compatibility: Treat Laravel 13 as a prerequisite, not an optional upgrade. Older Laravel versions are not supported. Custom providers implementing ResolvesRecords::find() must add the fifth $aggregates parameter. Custom operators must move to Contracts\CustomOperator and filter value types to Contracts\FilterValueType. Any prior gcego/blueprints or gcego/registry integration must be redesigned because that integration is removed.
• Sequencing: 1) Confirm PHP 8.3 and Laravel 13 readiness. 2) Install gcego/data and gcego/core. 3) Define one non-critical read source with Source::define() and typed definitions. 4) Add filtering, search, sorting, pagination, and relations. 5) Add tenant scoping and field-level security. 6) Enable profiling and slow-query diagnostics. 7) Add query caching and invalidation tests. 8) Introduce mutations and transactions behind feature flags. 9) Migrate custom providers/operators. 10) Run security, performance, and failure-mode tests before broad rollout.

Operational Impact

• Maintenance: Source definitions become part of the application’s data contract and must be maintained alongside schema and authorization changes. Pin gcego/data and gcego/core versions and track upgrades deliberately; the pre-1.0 to 1.0 break indicates meaningful API churn. Custom operators, filters, providers, and field-security rules need clear ownership.
• Support: The package relies on the GCEGO ecosystem through gcego/core, so confirm vendor support expectations, release cadence, and security response process. Internal support will need documentation for source definitions, tenant resolution, field access rules, cache invalidation, and transaction retry behavior. Laravel 13 upgrade timing should be tracked closely.
• Scaling: The package provides DB-side aggregates, scoped queries for analytics, query caching with User/Tenant/Shared isolation, stampede locks, pagination offsets, collection item limits, and statement timeouts. Profiling and N+1 detection help control query growth. Note that authorization, field rules, and transforms still run on every caller even when cached, so cache wins must be measured against security overhead.
• Failure modes: Missing tenant fails closed with 403; query timeouts return 503; mutation failures raise MutationException; deadlocks and serialization failures may retry with backoff; cache invalidation depends on version tokens, model events, and Data::invalidate(). Lazy-loading prevention on returned models may break code that relies on implicit lazy loads. Relation depth and search field limits may require query redesign. Misconfigured field security can hide or reject fields unexpectedly. Build runbooks for 403/503 responses, cache invalidation, transaction retries, and field-access changes.
• Ramp-up: Expect a moderate-to-high learning curve because the package introduces many concepts: typed source definitions, filter value types, operators, providers, tenancy, field security, caching, transactions, transforms, and profiling. Start with a small read-only pilot, use the migration guide, and build internal examples before enabling writes or tenant-scoped production paths. A realistic pilot is one to two sprints for read-only integration, with additional time for mutations, transactions, caching, and security hardening.