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. Use required first 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 $label parameter 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]'
Email '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.