Enhanced Resources Laravel Package

## Technical Evaluation

### **Architecture Fit**
- **Laravel 13.x Support**: The package now officially supports **Laravel 13.x**, reinforcing its alignment with modern Laravel ecosystems (e.g., **Laravel Octane**, **Pint**, and **PHP 8.3+ features**). This makes it a **strong fit for new Laravel projects** or those upgrading to the latest LTS.
- **API Resource Enhancement**: Continues to excel in **RESTful/GraphQL-like APIs**, **B2B/SaaS platforms**, and **microservices aggregators** where dynamic payloads are critical.
- **Legacy System Integration**: Still **not ideal for monolithic systems** with rigid serialization, but Laravel 13’s improved performance may mitigate some overhead concerns.
- **New Use Cases**:
  - **Real-time APIs**: Enhanced resources can now leverage Laravel 13’s **WebSocket/Event Bus** integrations for dynamic payload updates.
  - **AI/ML Pipelines**: Useful for structuring **feature payloads** in machine learning workflows (e.g., conditional fields for model inputs).

### **Integration Feasibility**
- **Laravel 13.x Compatibility**: **No breaking changes** reported; the package leverages Laravel 13’s under-the-hood improvements (e.g., **faster routing**, **optimized service container**) without exposing them to users.
- **PHP 8.3+**: Requires **PHP 8.3+** (implicitly, given Laravel 13’s requirements). Verify compatibility with existing **legacy PHP extensions** (e.g., `ext/redis`, `ext/pdo_mysql`).
- **Database/ORM**: **Zero impact** on Eloquent or database schema. However, Laravel 13’s **query builder optimizations** may indirectly improve nested resource performance.
- **Testing**: **Increased rigor needed** due to:
  - Laravel 13’s **new testing helpers** (e.g., `assertSeeInOrder()`).
  - Potential **interactions with Laravel’s new `Http\Resources\Json\JsonResource`** (if using Laravel’s built-in resources).

### **Technical Risk**
| Risk Area               | Severity | Mitigation Strategy                          | Update for v7.3.0                     |
|-------------------------|----------|-----------------------------------------------|---------------------------------------|
| **Overhead in Payloads** | Medium   | Profile with Laravel 13’s **OpCache** and **JIT**. | Laravel 13’s optimizations may reduce memory usage. |
| **Complexity Sprawl**   | High     | Enforce **resource naming conventions** + **Laravel 13’s `make:resource` scaffolding**. | New `make:resource` command in Laravel 13 speeds up adoption. |
| **Testing Debt**        | High     | Use **Pest 2.0+** (Laravel 13’s default) for snapshot testing. | Pest 2.0’s **live assertions** simplify payload validation. |
| **Dependency Bloat**    | Low      | MIT license; no changes.                     | Dependabot updates (e.g., `actions/cache`) are non-critical. |
| **Nested Relationships**| Medium   | Monitor with **Laravel Telescope 5.0+** (Laravel 13 compatible). | Telescope’s **query logging** helps debug N+1 issues. |
| **Laravel 13 Breaking Changes** | Low | Test with **Laravel’s upgrade guide** and **package’s test suite**. | No reported breaking changes; proceed with caution. |

### **Key Questions**
1. **Laravel 13 Migration**:
   - Are we upgrading to Laravel 13? If not, can we **pin to v7.2.x** for stability?
2. **PHP 8.3 Features**:
   - Can we leverage **new PHP features** (e.g., **read-only properties**, **enums**) in resources?
3. **Performance Gains**:
   - Will Laravel 13’s **optimized service container** reduce resource initialization time?
4. **Tooling Synergy**:
   - How does this package interact with **Laravel 13’s new tools** (e.g., **Pint**, **Artisan schedule optimizations**)?
5. **Deprecation Policy**:
   - Will older Laravel versions (e.g., 10.x) receive **long-term support** for this package?

---

## Integration Approach

### **Stack Fit**
- **Primary Fit**:
  - **Laravel 13.x** (PHP 8.3+).
  - APIs using **Eloquent**, **API Resources**, or **Laravel Livewire/Inertia.js**.
- **Secondary Fit**:
  - **Lumen 10.x** (with Laravel 13 compatibility layer).
  - **Octane-powered real-time APIs** (e.g., WebSocket payloads).
- **Non-Fit**:
  - Laravel **<10.x** (unless pinned to v7.2.x).
  - Non-Laravel PHP stacks (Symfony, etc.).
- **New Opportunities**:
  - **AI Feature Stores**: Use resources to structure **training data payloads**.
  - **Event-Driven Architectures**: Serialize **domain events** with conditional fields.

### **Migration Path**
1. **Pre-Migration Checklist**:
   - Upgrade Laravel to **13.x** (follow [official guide](https://blog.laravel.com/laravel-13-released)).
   - Update PHP to **8.3+** and dependencies (`composer update`).
   - Test with **Laravel’s upgrade helper**: `php artisan upgrade`.
2. **Pilot Migration**:
   - Refactor **one high-traffic resource** (e.g., `ProductResource`).
   - Benchmark performance with **Laravel Forge/Sail** before/after.
3. **Full Rollout**:
   - Replace all `JsonResource` classes with `EnhancedResource`.
   - Update **API contracts** (e.g., OpenAPI) to reflect dynamic fields.
4. **Deprecation**:
   - Deprecate legacy `Resource` classes via **feature flags** (e.g., `config('app.legacy_resources')`).

### **Compatibility**
- **Backward Compatibility**:
  - **No breaking changes** in v7.3.0. Existing `Resource` classes **continue to work**.
  - New features (e.g., Laravel 13 integrations) are **opt-in**.
- **Dependency Conflicts**:
  - **Dependabot updates** (e.g., `actions/cache`) are **non-breaking**.
  - Potential conflicts with:
    - `spatie/laravel-fractal` (if using both, test for payload collisions).
    - `darkaonline/l5-swagger` (update annotations for dynamic fields).
- **Database Impact**:
  - **None**. Changes are **application-layer only**.

### **Sequencing**
1. **Pre-requisites**:
   - Upgrade Laravel: `composer require laravel/framework:^13.0`.
   - Update PHP: `php -v` must show **8.3+**.
   - Install package: `composer require sourcetoad/enhanced-resources:^7.3`.
2. **Core Integration**:
   - Publish config (if any): `php artisan vendor:publish --tag=enhanced-resources`.
   - Extend `EnhancedResource` in **new resource classes**:
     ```php
     use Sourcetoad\EnhancedResources\EnhancedResource;

     class UserResource extends EnhancedResource {
         public function toArray($request): array {
             return [
                 'id' => $this->id,
                 'name' => $this->name,
                 // Laravel 13: Use new PHP 8.3 features
                 'roles' => array_filter($this->roles, fn($role) => $role->isActive()),
             ];
         }
     }
     ```
3. **Testing**:
   - Update tests with **Pest 2.0** assertions:
     ```php
     use function Pest\Laravel\assertApiResponse;

     it('returns conditional fields', function () {
         assertApiResponse()->json([
             'data' => [
                 'id' => 1,
                 'name' => 'John',
                 // Only included if admin
                 'email_verified' => true,
             ],
         ]);
     });
     ```
   - Use **Laravel 13’s `TestCase` improvements** (e.g., `actingAs()` with tokens).
4. **Deployment**:
   - Roll out in **blue-green deployment** to mitigate payload schema risks.
   - Monitor with **Laravel Telescope 5.0** for serialization errors.

---

## Operational Impact

### **Maintenance**
- **Pros**:
  - **Laravel 13 Optimizations**: Faster **service container**, **OpCache**, and **JIT** reduce resource overhead.
  - **PHP 8.3 Features**: Use **read-only properties** for immutable resource data.
  - **Tooling Synergy**: Integrates with **Pint**, **Artisan optimizations**, and **new testing helpers**.
- **Cons**:
  - **Steep Learning Curve**: Laravel 13 + new package features may require **dedicated training**.
  - **Testing Complexity**: Dynamic fields need **comprehensive snapshot testing**.
- **Tooling**:
  - **PHPStan 1.