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

Snapshot-Protected Migrations (Development)

• Change: Migrations require database snapshot in development environments
• Affected: php artisan migrate command in development
• Reason: Prevents partial migrations from corrupting database, LLM-friendly error recovery
• Implementation: Enhanced Maint_Migrate command with snapshot commands
• Commands: migrate:begin, migrate:commit, migrate:rollback, migrate:status
• Bypass: Use --production flag to skip snapshot requirement
• Note: Only enforced in development with Docker, production runs normally
• Date: 2025-08-13

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