rspade_system/app/RSpade/man/class_override.txt

# Class Override System

## NAME

class_override - Override framework classes with application-specific versions

## SYNOPSIS

Copy a framework class to your rsx/ directory with the same class name:

    # Override User_Model
    cp system/app/RSpade/Core/Models/User_Model.php rsx/models/user_model.php

    # Edit the copy to customize behavior
    nano rsx/models/user_model.php

    # Manifest automatically detects and activates override

## DESCRIPTION

The class override system allows developers to replace framework classes with
custom implementations. When a class with the same name exists in both rsx/
and app/RSpade/, the manifest automatically:

1. Renames the framework file to .upstream (e.g., User_Model.php.upstream)
2. Uses the rsx/ version as the authoritative class
3. Rebuilds to reflect the change

This enables customization without forking the entire framework.

## HOW IT WORKS

During manifest build, when duplicate class names are detected:

    Framework file: app/RSpade/Core/Models/User_Model.php
    Override file:  rsx/models/user_model.php

    Result:
    - app/RSpade/Core/Models/User_Model.php renamed to .upstream
    - rsx/models/user_model.php becomes the active class

The .upstream file preserves the original for reference and framework updates.

## COMMON OVERRIDE TARGETS

These framework classes are commonly overridden to add application-specific
fields, relationships, or behavior:

    User_Model          - Add custom user fields, relationships, methods
    User_Profile_Model  - Extend profile with application-specific data
    Site_Model          - Add site-specific settings or relationships

Location of originals:

    system/app/RSpade/Core/Models/User_Model.php
    system/app/RSpade/Core/Models/User_Profile_Model.php
    system/app/RSpade/Core/Models/Site_Model.php

## CREATING AN OVERRIDE

1. Copy the framework file to rsx/:

        cp system/app/RSpade/Core/Models/User_Model.php rsx/models/user_model.php

2. Update the namespace in your copy:

        namespace Rsx\Models;  // Was: namespace App\RSpade\Core\Models;

3. Modify the class as needed (add fields, methods, relationships)

4. Run manifest build or load any page (triggers automatic rebuild):

        php artisan rsx:manifest:build

5. Verify the override is active:

        php artisan tinker --execute="echo Manifest::php_find_class('User_Model');"
        # Output: rsx/models/user_model.php

## EXAMPLE: EXTENDING USER_MODEL

    <?php

    namespace Rsx\Models;

    use App\RSpade\Core\Database\Models\Rsx_Model_Abstract;

    class User_Model extends Rsx_Model_Abstract
    {
        protected $table = 'users';

        public static $enums = [
            'role_id' => [
                1 => ['constant' => 'ROLE_ADMIN', 'label' => 'Administrator'],
                2 => ['constant' => 'ROLE_USER', 'label' => 'User'],
            ],
        ];

        // Add application-specific relationships
        public function projects()
        {
            return $this->hasMany(Project_Model::class, 'owner_id');
        }

        // Add custom methods
        public function can_access_admin(): bool
        {
            return $this->role_id === self::ROLE_ADMIN;
        }

        // Include all original User_Model functionality...
    }

## FRAMEWORK UPDATES

When updating the framework with `php artisan rsx:framework:pull`:

1. Before checking for uncommitted changes, the update script automatically:
   - Restores any deleted framework files (git checkout)
   - Deletes any .upstream files
2. Git pull brings in updated framework files
3. Your rsx/ override remains unchanged
4. On next manifest build, override detection runs again
5. The updated framework file is re-renamed to .upstream

This automatic cleanup ensures framework updates work seamlessly with overrides.
The next manifest build will re-detect your overrides and rename the (now updated)
framework files back to .upstream.

To see what changed in the framework version after an update:

    diff rsx/models/user_model.php \
         system/app/RSpade/Core/Models/User_Model.php.upstream

## REMOVING AN OVERRIDE

To revert to the framework version:

1. Delete your override file:

        rm rsx/models/user_model.php

2. Restore the framework file:

        mv system/app/RSpade/Core/Models/User_Model.php.upstream \
           system/app/RSpade/Core/Models/User_Model.php

3. Rebuild manifest:

        php artisan rsx:manifest:build

## LIMITATIONS

- Only works for classes in rsx/ overriding app/RSpade/ classes
- Both files must define the same class name
- Cannot override multiple framework classes with one file
- JavaScript classes follow the same override pattern

## TROUBLESHOOTING

### Override not detected

Ensure class names match exactly. Check with:

    grep -r "^class " rsx/models/user_model.php
    grep -r "^class " system/app/RSpade/Core/Models/User_Model.php

### Missing methods after override

Your override replaces the entire class. Copy all needed functionality from
the .upstream file or extend from a different base class.

### Framework file not renamed

Run a clean manifest build:

    php artisan rsx:manifest:build --clean

## SEE ALSO

rsx_upstream(7) - Framework update management
manifest_api(7) - Manifest system documentation
model(7) - Model documentation