set_rules()
function set_rules(string $key, string $label, string $rules): void
Description
Defines validation rules for a specific form field or file upload. This method is the foundation of Trongate's validation system, allowing you to specify which fields are required, what format they should have, and what constraints they must meet. Each call to set_rules() validates one field according to the specified rules.
Quick Start: Call set_rules() for each field you want to validate, then call $this->validation->run() to execute all validations at once.
Parameters
| Parameter | Type | Description |
|---|---|---|
| $key | string | The name attribute of the form field (e.g., 'email', 'password', 'task_title'). |
| $label | string | A human-readable label used in error messages (e.g., 'Email Address', 'Password', 'Task Title'). |
| $rules | string | Validation rules separated by pipe characters (|). For rules requiring parameters, use square brackets (e.g., 'required|min_length[8]|max_length[255]'). |
Return Value
| Type | Description |
|---|---|
| void | This method does not return a value. Errors are stored internally and retrieved via validation_errors(). |
Available Validation Rules
Basic Rules
| Rule | Description | Example |
|---|---|---|
required |
Field must not be empty | 'required' |
numeric |
Field must contain only numbers | 'numeric' |
integer |
Field must be a whole number (no decimals) | 'integer' |
decimal |
Field must contain a decimal number | 'decimal' |
valid_email |
Field must be a valid email address with DNS verification | 'valid_email' |
Length Rules
| Rule | Description | Example |
|---|---|---|
min_length[n] |
Field must be at least n characters long | 'min_length[8]' |
max_length[n] |
Field must be no more than n characters long | 'max_length[255]' |
exact_length[n] |
Field must be exactly n characters long | 'exact_length[10]' |
Comparison Rules
| Rule | Description | Example |
|---|---|---|
matches[field] |
Field must match another field (useful for password confirmation) | 'matches[password]' |
differs[field] |
Field must not match another field | 'differs[old_password]' |
greater_than[n] |
Numeric field must be greater than n | 'greater_than[0]' |
less_than[n] |
Numeric field must be less than n | 'less_than[100]' |
Date and Time Rules
| Rule | Description | Example |
|---|---|---|
valid_date |
Field must be a valid date in YYYY-MM-DD format | 'valid_date' |
valid_time |
Field must be a valid time in HH:MM or HH:MM:SS format | 'valid_time' |
valid_datetime_local |
Field must be a valid datetime in YYYY-MM-DDTHH:MM format | 'valid_datetime_local' |
valid_month |
Field must be a valid month in YYYY-MM format | 'valid_month' |
valid_week |
Field must be a valid week in YYYY-W## format (e.g., 2025-W52) | 'valid_week' |
File Upload Rules
| Rule | Description | Example |
|---|---|---|
allowed_types[ext1,ext2] |
File must have one of the specified extensions | 'allowed_types[jpg,png,gif]' |
max_size[kb] |
File size must not exceed specified kilobytes | 'max_size[2048]' |
max_width[px] |
Image width must not exceed specified pixels | 'max_width[1920]' |
max_height[px] |
Image height must not exceed specified pixels | 'max_height[1080]' |
min_width[px] |
Image width must be at least specified pixels | 'min_width[800]' |
min_height[px] |
Image height must be at least specified pixels | 'min_height[600]' |
square |
Image must be square (width equals height) | 'square' |
Custom Validation Rules
| Rule | Description | Example |
|---|---|---|
callback_method_name |
Calls a custom validation method in your controller | 'callback_check_username' |
Basic Usage Pattern
Simple Form Validation
This is the most common pattern for validating form submissions:
Advanced Examples
Example #1: User Registration Form
Example #2: File Upload Validation
Example #3: Custom Callback Validation
Callback Return Values: Custom validation methods must return true for success or a string error message for failure. Use {label} as a placeholder in your error message, which will be replaced with the field label.
Example #4: Date Range Validation
Combining Multiple Rules
Rules are separated by pipe characters and evaluated in order from left to right:
File Upload Validation Details
Automatic File Security: When validating file uploads, Trongate automatically scans the first 256 bytes of uploaded files for dangerous patterns like PHP code, shell commands, and malicious scripts. This security check happens before any custom validation rules are applied.
Complete File Upload Example
Important Notes
- Order matters:
set_rules()calls are processed in the order they're written. Userequiredfirst for fields that must have a value. - Empty fields skip rules: Most validation rules (except
required) are automatically skipped if a field is empty. This allows optional fields to have format requirements. - Automatic cleaning: Field values are automatically retrieved with
post($key, true), which trims whitespace and collapses multiple spaces. - CSRF protection: CSRF validation happens automatically when
$this->validation->run()is called. - Error storage: Validation errors are stored in the session, allowing them to persist across redirects.
- Field labels in errors: The
$labelparameter is used in all error messages, making them more user-friendly.
Common Validation Patterns
| Field Type | Typical Rules |
|---|---|
| Username | 'required|min_length[3]|max_length[50]' |
'required|valid_email|max_length[254]' |
|
| Password | 'required|min_length[8]|max_length[255]' |
| Phone (10 digits) | 'required|exact_length[10]|numeric' |
| Age | 'required|integer|greater_than[0]|less_than[150]' |
| Price | 'required|numeric|greater_than[0]' |
| ZIP Code (5 digits) | 'required|exact_length[5]|numeric' |
| Optional URL | 'valid_url' (no required) |
Error Handling
After calling set_rules(), use $this->validation->run() to execute all validations. Display errors using validation_errors():
For more information on displaying validation errors, see the validation_errors() function documentation.