Form Validation Introduction
In Trongate v2, form validation is handled by the validation module located at modules/validation/. The Trongate v2 validation module delivers enterprise-grade validation with zero configuration - handling everything from simple required fields to complex custom validation rules, complete with automatic CSRF protection and effortless multilingual support.
How It Works: The Three-Step Pattern
Every validation instance follows the same simple pattern:
- Set rules - Define what each field must satisfy
- Run validation tests - Check submitted data against your rules
- Handle the result - Display errors or process valid data
Displaying Errors: Three Scenarios
Trongate provides three distinct ways to display validation errors. The helper function plays a pivotal role by automatically selecting the appropriate output format based on its first argument.
| Scenario | How to Invoke | Best For | Clears Session? |
|---|---|---|---|
| General Errors | validation_errors() |
Simple forms, login pages, admin panels | Yes - all errors |
| Inline Errors | validation_errors('field_name') |
Long forms, multi-step forms, better UX | No - allows multiple field calls |
| JSON Response | validation_errors(422) |
API endpoints, AJAX forms, mobile apps | Yes + exits script |
How the helper decides: Pass nothing for general errors, a field name string for inline errors, or an HTTP status code (400-499) for JSON. The helper handles the rest automatically.
Scenario 1: General Errors
Display all errors at once, typically at the top of your form:
Scenario 2: Inline Errors
Display errors next to specific fields for better user experience:
Pro tip: Inline errors don't clear the entire session. You can call validation_errors('field') for multiple different fields throughout your form.
Scenario 3: JSON Response (APIs)
Return structured JSON for API endpoints or AJAX requests:
JSON output:
Important: JSON responses terminate script execution with exit(). No code after validation_errors(422) will run.
Setting Validation Rules
Trongate supports two syntax styles for defining rules. Choose the one that fits your needs.
Option 1: Pipe Syntax (Concise)
Ideal for simple forms and quick prototyping:
Option 2: Array Syntax (Organized)
Ideal for complex forms and programmatic rule building:
Common Built-In Rules
| Rule | Description |
|---|---|
required | Field cannot be empty |
min_length[n] | Minimum character length |
max_length[n] | Maximum character length |
valid_email | Valid email format |
numeric | Must be a number |
integer | Must be an integer |
matches[field] | Must match another field (e.g., password confirmation) |
See Validation Rules Reference for the complete list including date/time and file upload rules.
Special Case: Checkbox Validation
Checkboxes behave differently because unchecked boxes submit nothing. An unchecked checkbox returns '' (empty string) from post().
Complete Working Example
Here's a full implementation using the create/update pattern:
Key Points
- Validation rules are set with and executed with
- Use lowercase field labels for natural error messages: "The email address field is required"
- Always use
post('field', true)to get cleaned, trimmed values - CSRF protection is automatic - every POST form is protected
- Errors survive redirects via session storage
- Optional fields skip validation when empty - only validate what matters
Validation lifecycle: Validation fails → errors stored in session → form redisplays with errors. Validation passes → data saves → flashdata set → redirect to success page.
What's Next
The following pages cover everything you need to master form validation:
- Validation Rules Reference - Complete list of built-in rules
- Custom Validation Rules - Write your own validation logic with callbacks
- Multilingual Validation - Display errors in multiple languages
- Styling Validation Errors - CSS, automatic field highlighting, and UX best practices
We're continually improving the Trongate documentation. If anything is incorrect, unclear, incomplete, or could be better, we'd genuinely appreciate your input.
Share your thoughts in the Documentation Feedback.