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 validation_errors() 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 set_rules() and executed with included-validation-run()
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