RuleBuilder - Schema Configuration

Revision: 2025/10/31

The RuleBuilder class provides a fluent interface for defining model schemas in the configure() method. It allows you to configure table structure, field types, validation rules, form behaviors, and relationships.

Basic Usage

protected function configure($rule): void {
    $rule->table('#__products')              // Define table name
        ->id()                                // Auto-increment primary key
        ->string('name', 100)->required()     // VARCHAR(100) NOT NULL
        ->decimal('price', 10, 2)->default(0) // DECIMAL(10,2) DEFAULT 0
        ->text('description')->nullable()     // TEXT NULL
        ->boolean('in_stock')->default(true)  // TINYINT(1) DEFAULT 1
        ->created_at();                       // DATETIME with auto-preservation
}

Configuration Methods

Core Configuration

Field Type Methods

Basic Types

Date/Time Types

Special Input Types

Selection Types

Field Configuration Methods

Validation & Constraints

Display & Labeling

Form Configuration

File Upload Configuration

Dynamic Options

Relationships

Relationship Example

// PostsModel
protected function configure($rule): void {
    $rule->table('#__posts')
        ->id()
        ->string('title', 200)->required()
        ->int('user_id')->belongsTo('author', UserModel::class)  // Foreign key here
        ->text('content');
}

// UserModel
protected function configure($rule): void {
    $rule->table('#__users')
        ->id()
            ->hasMany('posts', PostModel::class, 'user_id')      // Load actual posts
            ->withCount('posts_count', PostModel::class, 'user_id')  // Count posts efficiently
        ->title('username', 50)->required()
        ->email('email');
}

// Usage
$user = $userModel->getById(1);
echo $user->posts_count;  // 15 (fast COUNT subquery)
$posts = $user->posts;     // Array of PostModel (lazy loaded)

Advanced Customization

Custom Getters, Setters & Editors

Custom Properties

Utility Methods

Complete Example

namespace Modules\Shop;
use App\Abstracts\AbstractModel;
use Modules\Users\UsersModel;
use Modules\Categories\CategoriesModel;

class ProductsModel extends AbstractModel
{
    protected function configure($rule): void {
        $rule->table('#__shop_products')

            // Primary key
            ->id()

            // Basic fields
            ->title('name', 200)->required()
            ->string('sku', 50)->unique()->required()

            // Relationships
            ->int('category_id')
                ->belongsTo('category', CategoriesModel::class)
                ->required()
                ->index()

            ->int('created_by')
                ->belongsTo('author', UsersModel::class)
                ->hideFromEdit()

            // Pricing
            ->decimal('price', 10, 2)
                ->default(0)
                ->min(0)
                ->step(0.01)
                ->required()

            ->decimal('sale_price', 10, 2)
                ->nullable()
                ->min(0)

            // Description
            ->text('description')->nullable()
            ->text('short_description')->nullable()->hideFromList()

            // Stock management
            ->int('stock_quantity')->default(0)->unsigned()
            ->boolean('track_inventory')->default(true)
            ->boolean('in_stock')->default(true)

            // Status
            ->enum('status', ['draft', 'published', 'archived'])
                ->default('draft')

            // Media
            ->image('featured_image')
                ->accept('image/*')
                ->maxSize(5242880)  // 5MB
                ->uploadDir('/uploads/products')
                ->nullable()

            ->file('gallery')
                ->multiple(10)
                ->accept('image/*')
                ->nullable()

            // Metadata
            ->array('meta_data')->nullable()->excludeFromDatabase()

            // Timestamps
            ->created_at()
            ->datetime('updated_at')->nullable()->hideFromEdit();
    }
}

Field Rule Structure

Each field rule contains the following properties:

[
    'type' => 'string',           // PHP and SQL type
    'length' => 100,              // Max length for strings
    'precision' => 2,             // Precision for floats/decimals
    'nullable' => true,           // Can be NULL
    'default' => null,            // Default value
    'primary' => false,           // Is primary key
    'label' => 'Field Name',      // Display label
    'options' => [],              // Options for list/enum
    'index' => false,             // Create database index
    'unique' => false,            // UNIQUE constraint
    'unsigned' => false,          // Unsigned numeric
    'list' => true,               // Show in list view
    'edit' => true,               // Show in edit form
    'view' => true,               // Show in detail view
    'sql' => true,                // Create in database
    'form-type' => 'text',        // HTML input type
    'form-label' => null,         // Form-specific label
    'form-params' => [],          // HTML attributes
    'relationship' => [],         // Relationship config
    'api_url' => null,            // API endpoint for options
    'save_value' => null,         // Value to always save
    '_auto_created_at' => false,  // Auto-preserve on update
    '_is_title_field' => false,   // Used in belongsTo display
    '_get' => callable,           // Custom getter
    '_set' => callable,           // Custom setter
    '_edit' => callable,          // Custom editor
]

Tests

Next Steps