rspade_system/docs/framework_divergences.md

# RSpade Framework Divergences from Laravel

This file documents all intentional divergences from standard Laravel behavior. These are framework-level changes that alter how developers interact with common Laravel features.

**Note**: This log tracks behavioral changes to existing Laravel functionality, not new architectural additions like RSX. A divergence is when we take something Laravel already does and make it work differently.

## Database & Models

### Mass Assignment Prevention
- **Change**: All mass assignment methods throw `MassAssignmentException`
- **Affected**: `Model::create()`, `fill()`, `forceFill()`, `update()`, `firstOrCreate()`, `firstOrNew()`, `updateOrCreate()`
- **Reason**: Security and code clarity - forces explicit field assignment
- **Implementation**: `Model_Abstract` base class overrides these methods
- **Date**: 2025-08-12

### Eager Loading Prevention
- **Change**: ALL eager loading methods throw `RuntimeException`
- **Affected**: `with()`, `load()`, `loadMissing()`, `loadCount()`, `loadMorph()`, `loadAggregate()`, `loadMax()`, `loadMin()`, `loadSum()`, `loadAvg()`, `loadExists()`, `withCount()`, `withMax()`, `withMin()`, `withSum()`, `withAvg()`, `withExists()`, `withAggregate()`
- **Reason**: Enforce explicit queries for relationships, prevent N+1 optimization patterns that complicate code
- **Implementation**: `Model_Abstract` overrides instance methods, `RestrictedEloquentBuilder` blocks query methods, `RestrictedEloquentCollection` blocks collection methods
- **Date**: 2025-08-19

## Routing

### Route Parameter Syntax
- **Change**: Route parameters use `:param` syntax instead of Laravel's `{param}`
- **Affected**: All route definitions in #[Route] attributes
- **Reason**: Clearer syntax, prevents confusion with Blade syntax
- **Implementation**: RouteResolver validates and rejects old {param} syntax with fatal errors
- **Date**: 2025-09-07

### Resource Routes Prevention
- **Change**: Resource route methods throw `RuntimeException`
- **Affected**: `Route::resource()`, `Route::apiResource()`, `Route::resources()`, `Route::apiResources()`, `Route::singleton()`, `Route::singletons()`
- **Reason**: Enforce explicit route definitions, prevent REST pattern assumptions
- **Implementation**: `RestrictedRouter` class overrides these methods
- **Date**: 2025-08-20

### HTTP Method Restrictions
- **Change**: Non-GET/POST HTTP methods throw `RuntimeException`
- **Affected**: `Route::put()`, `Route::patch()`, `Route::delete()`, `Route::options()`, `Route::any()`
- **Reason**: Simplify HTTP semantics, use POST for all data modifications
- **Implementation**: `RestrictedRouter` class blocks these methods, `addRoute()` validates allowed methods
- **Date**: 2025-08-20

### Forward-Only Migrations
- **Change**: Migration stubs no longer include `down()` methods
- **Affected**: All generated migrations via `make:migration`
- **Reason**: Prevent data loss, enforce forward-only database evolution
- **Implementation**: Customized stubs in `/stubs/migration*.stub`
- **Notice**: Warning displayed after migration creation
- **Date**: 2025-08-12

### Restricted Database Commands
- **Change**: Several database commands are disabled with professional error messages
- **Affected**: `db:wipe`, `migrate:fresh`, `migrate:reset`, `migrate:refresh`, `migrate:rollback`
- **Reason**: Prevent accidental data loss in production
- **Implementation**: `RestrictedDatabaseCommand` base class
- **Date**: 2025-08-06

## Naming Conventions

### Underscore Case Enforcement
- **Change**: All custom methods must use underscore_case (not camelCase)
- **Affected**: Controllers, Models, Services - any custom PHP methods
- **Reason**: Consistency and readability
- **Implementation**: `rsx:check` command checks and reports violations
- **Note**: Framework methods keep original names (e.g., `toArray`, `broadcastOn`)
- **Date**: 2025-08-12

## Git Operations

### Force Full Staging
- **Change**: All git operations must use `git add -A` (full staging)
- **Affected**: Git workflow
- **Reason**: Prevent partial commits and ensure complete change tracking
- **Implementation**: Documented directive, not enforced in code
- **Date**: 2025-05-15

## Session & Authentication

### Extended Session Lifetime
- **Change**: Sessions last 365 days instead of Laravel's default 120 minutes
- **Affected**: User sessions
- **Reason**: Better user experience for long-term applications
- **Implementation**: `config/session.php` configuration
- **Date**: 2025-05-15

## Code Organization

### No $fillable or $guarded Properties
- **Change**: Models should not define `$fillable` or `$guarded` arrays
- **Affected**: All Eloquent models
- **Reason**: Mass assignment is prohibited, making these properties unnecessary
- **Implementation**: `rsx:check` warns when these properties are found
- **Date**: 2025-08-12

## Development Workflow

### No Service Restart for Code Changes
- **Change**: Never restart PHP-FPM or Nginx after code changes
- **Affected**: Development and deployment workflow
- **Reason**: OPcache is disabled, changes take effect immediately
- **Implementation**: Environment configuration
- **Date**: 2025-05-15

### Automatic Snapshot-Protected Migrations (Development)
- **Change**: `php artisan migrate` automatically handles snapshots in development
- **Affected**: `php artisan migrate` command
- **Reason**: Prevents partial migrations from corrupting database, LLM-friendly error recovery
- **Implementation**: Unified `Maint_Migrate` command with automatic snapshot/rollback
- **Behavior**: Creates snapshot, runs migrations, commits on success, auto-rollbacks on failure
- **Note**: Only in development mode with Docker; debug/production runs without snapshots
- **Date**: 2025-01-15

## Error Handling

### Educational Exception Messages
- **Change**: Custom exceptions include detailed explanations and correct code examples
- **Affected**: All custom exception classes
- **Reason**: Help developers learn framework patterns quickly
- **Implementation**: `MassAssignmentException` and similar custom exceptions
- **Date**: 2025-08-12

---

*When adding entries, include: Change description, Affected areas, Reason, Implementation method, and Date*