rspade_system/app/RSpade/man/enums.txt

ENUMS(7)                           RSpade Developer Manual                           ENUMS(7)

NAME
    Enums - Database field enumeration system for RSX models

SYNOPSIS
    public static $enums = [
        'field_name' => [
            value => ['constant' => 'NAME', 'label' => 'Display Name', ...]
        ]
    ];

DESCRIPTION
    The enum system provides a powerful way to define predefined values for database
    fields with associated metadata. It automatically generates constants, magic
    properties, helper methods, and JavaScript equivalents for both PHP and JavaScript
    code.

DEFINING ENUMS

    Basic Definition
        Define enums as a static property on your model class:

        public static $enums = [
            'status_id' => [
                1 => [
                    'constant' => 'STATUS_ACTIVE',
                    'label' => 'Active',
                ],
                2 => [
                    'constant' => 'STATUS_INACTIVE',
                    'label' => 'Inactive',
                ],
            ],
        ];

    Standard Properties
        constant        - PHP constant name (generates Model::STATUS_ACTIVE)
        label           - Human-readable display name
        order           - Sort order (defaults to 0)
        selectable      - Whether shown in dropdowns (defaults to true)

    Custom Properties
        You can add any custom properties for business logic:

        'status_id' => [
            1 => [
                'constant' => 'STATUS_PUBLISHED',
                'label' => 'Published',
                'badge' => 'bg-success',           // CSS class for styling
                'visible_frontend' => true,        // Visibility control
                'can_edit' => false,               // Business rule
                'icon' => 'fa-check',              // Icon class
            ],
        ];

PHP MAGIC PROPERTIES (Instance)

    For a model instance with an enum field, these properties are automatically available:

    field_label         Returns the label for the current value
                       $user->status_id = 1;
                       echo $user->status_label; // "Active"

    field_constant      Returns the constant name for the current value
                       echo $user->status_constant; // "STATUS_ACTIVE"

    field_enum_val      Returns ALL properties for the current value
                       $props = $user->status_enum_val;
                       // ['constant' => 'STATUS_ACTIVE', 'label' => 'Active', ...]

    field_[property]    Returns any custom property for the current value
                       echo $user->status_badge; // "bg-success"
                       echo $user->status_visible_frontend; // true

STATIC METHODS (PHP and JavaScript)

    These four methods are available as static methods on model classes in both PHP
    and JavaScript. The JavaScript stubs are auto-generated to mirror PHP behavior.

    Model::field_enum_val()
        Returns all enum definitions for a field with full metadata:

        $statuses = User_Model::status_id_enum_val();
        // [1 => ['constant' => 'STATUS_ACTIVE', 'label' => 'Active', ...], ...]

        // JavaScript equivalent:
        const statuses = User_Model.status_id_enum_val();

    Model::field_enum_select()
        Returns selectable items for dropdowns (respects 'selectable' and 'order'):

        $options = User_Model::status_id_enum_select();
        // [1 => 'Active', 2 => 'Inactive']  (excludes selectable: false items)

        // JavaScript equivalent:
        const options = User_Model.status_id_enum_select();

    Model::field_enum_labels()
        Returns simple id => label map (all items, ignores selectable flag):

        $labels = User_Model::status_id_enum_labels();
        // [1 => 'Active', 2 => 'Inactive', 3 => 'Archived']

        // JavaScript equivalent:
        const labels = User_Model.status_id_enum_labels();

    Model::field_enum_ids()
        Returns array of all valid enum IDs:

        $ids = User_Model::status_id_enum_ids();
        // [1, 2, 3]

        // JavaScript equivalent:
        const ids = User_Model.status_id_enum_ids();

PHP CONSTANTS

    Constants are automatically generated via rsx:migrate:document_models command:

    class User_Model extends Rsx_Model_Abstract
    {
        const STATUS_ACTIVE = 1;
        const STATUS_INACTIVE = 2;
    }

    Usage:
        if ($user->status_id === User_Model::STATUS_ACTIVE) {
            // User is active
        }

JAVASCRIPT ACCESS

    The framework generates JavaScript stub classes with full enum support.
    See: php artisan rsx:man model_fetch (JAVASCRIPT CLASS ARCHITECTURE)

    Static Constants
        Project_Model.STATUS_ACTIVE    // 2
        Project_Model.STATUS_PLANNING  // 1

    Static Methods (same as PHP - see STATIC METHODS section above)
        Project_Model.status_enum_val()     // Full enum definitions with metadata
        Project_Model.status_enum_select()  // Selectable items for dropdowns
        Project_Model.status_enum_labels()  // Simple id => label map
        Project_Model.status_enum_ids()     // Array of valid IDs

    Instance Properties (after fetch)
        const project = await Project_Model.fetch(1);
        project.status         // 2 (raw value)
        project.status_label   // "Active"
        project.status_badge   // "bg-success"

AJAX/JSON EXPORT

    When models are converted to arrays/JSON, enum properties are automatically included:

    $user->toArray() returns:
    [
        'id' => 1,
        'status_id' => 1,
        'status_id_label' => 'Active',           // Added automatically
        'status_id_constant' => 'STATUS_ACTIVE', // Added automatically
        'status_id_badge' => 'bg-success',       // Custom properties too
        // ... all enum properties for current value
    ]

ADVANCED FEATURES

    Ordering
        Use the 'order' property to control sort order in dropdowns:

        'priority' => [
            3 => ['label' => 'Low', 'order' => 3],
            1 => ['label' => 'High', 'order' => 1],
            2 => ['label' => 'Medium', 'order' => 2],
        ]
        // enum_select() returns: [1 => 'High', 2 => 'Medium', 3 => 'Low']

    Selective Options
        Use 'selectable' => false to hide options from dropdowns while keeping them valid:

        3 => [
            'constant' => 'STATUS_ARCHIVED',
            'label' => 'Archived',
            'selectable' => false,  // Won't appear in new dropdowns
        ]

    Context-Specific Labels
        Define different labels for different contexts:

        'label' => 'New Listing',           // Backend label
        'label_frontend' => 'Coming Soon',  // Frontend label
        'label_short' => 'New',             // Abbreviated version

PRACTICAL APPLICATIONS

    Populating Select Boxes
        <!-- Blade template -->
        <select name="status_id">
            @foreach(User_Model::status_id_enum_select() as $id => $label)
                <option value="{{ $id }}">{{ $label }}</option>
            @endforeach
        </select>

    Dynamic CSS Classes
        <span class="badge {{ $auction->auction_status_badge }}">
            {{ $auction->auction_status_label }}
        </span>

    Business Logic Flags
        if ($auction->auction_status_can_bid) {
            // Show bidding interface
        }

    Permission Systems
        'role' => [
            1 => [
                'constant' => 'ROLE_ADMIN',
                'label' => 'Administrator',
                'permissions' => ['users.create', 'users.delete'],
                'can_admin_roles' => [2, 3, 4], // Can manage these role IDs
            ]
        ]

        // Check permissions
        if (in_array('users.create', $user->role_permissions)) {
            // User can create users
        }

    Visual Indicators
        'priority' => [
            1 => [
                'label' => 'Critical',
                'color' => '#FF0000',
                'icon' => 'fa-exclamation-circle',
                'badge_class' => 'badge-danger pulse-animation',
            ]
        ]

BOOLEAN FIELDS

    For boolean fields, use 0/1 as keys:

    'is_verified' => [
        0 => ['label' => 'Not Verified'],
        1 => ['label' => 'Verified'],
    ]

BEST PRACTICES

    1. Always define constants for code readability
    2. Use descriptive labels that make sense to end users
    3. Add 'order' when dropdown order matters
    4. Use 'selectable' => false for deprecated/archived values
    5. Keep enum values immutable - add new values, don't change existing
    6. Document custom properties in your model
    7. Run rsx:migrate:document_models after adding enums

EXAMPLE IMPLEMENTATION

    // rsx/models/project_model.php
    class Project_Model extends Rsx_Model_Abstract
    {
        public static $enums = [
            'status' => [
                1 => [
                    'constant' => 'STATUS_PLANNING',
                    'label' => 'Planning',
                    'badge' => 'badge-secondary',
                    'can_edit' => true,
                    'order' => 1,
                ],
                2 => [
                    'constant' => 'STATUS_IN_PROGRESS',
                    'label' => 'In Progress',
                    'badge' => 'badge-primary',
                    'can_edit' => true,
                    'order' => 2,
                ],
                3 => [
                    'constant' => 'STATUS_REVIEW',
                    'label' => 'Under Review',
                    'badge' => 'badge-warning',
                    'can_edit' => false,
                    'order' => 3,
                ],
                4 => [
                    'constant' => 'STATUS_COMPLETE',
                    'label' => 'Complete',
                    'badge' => 'badge-success',
                    'can_edit' => false,
                    'visible_in_reports' => true,
                    'order' => 4,
                ],
                5 => [
                    'constant' => 'STATUS_CANCELLED',
                    'label' => 'Cancelled',
                    'badge' => 'badge-danger',
                    'can_edit' => false,
                    'selectable' => false, // Hide from new projects
                    'order' => 5,
                ],
            ],
            'priority' => [
                1 => ['constant' => 'PRIORITY_LOW', 'label' => 'Low', 'days' => 30],
                2 => ['constant' => 'PRIORITY_MEDIUM', 'label' => 'Medium', 'days' => 14],
                3 => ['constant' => 'PRIORITY_HIGH', 'label' => 'High', 'days' => 7],
                4 => ['constant' => 'PRIORITY_CRITICAL', 'label' => 'Critical', 'days' => 1],
            ],
        ];
    }

    // Usage in controller
    if ($project->status === Project_Model::STATUS_IN_PROGRESS) {
        if ($project->priority_days < 3) {
            // Escalate critical project
        }
    }

    // Usage in Blade view
    <div class="{{ $project->status_badge }}">
        {{ $project->status_label }}
        @if($project->status_can_edit)
            <button>Edit</button>
        @endif
    </div>

SEE ALSO
    php artisan rsx:migrate:document_models - Generate constants and type hints
    php artisan rsx:man model_fetch - Model fetching from JavaScript
    php artisan rsx:man models - RSX model system overview

RSpade 1.0                           September 2025                                  ENUMS(7)