☰
Trongate PHP Framework Docs
Introduction
Quick Start
Basic Concepts
Understanding Routing
Intercepting Requests
Module Fundamentals
Database Operations
Templates
Helpers
Form Handling
Form Validation
Working With Files
Image Manipulation
Working With Dates & Times
Language Control
Security
Tips And Best Practices

Retrieving Form Data

One function handles all POST data: .

Basic Usage

PHP
post($field_name, $clean_up, $cast_numeric);
  • $field_name - field name, null, or true (to get all data)
  • $clean_up - trim and collapse whitespace (optional, default: false)
  • $cast_numeric - convert numbers to int/float (optional, default: false)

Get All Data (Returns array)

PHP
// All data, no cleaning
$raw_data = post(); // or post(null)

// All data with whitespace cleaning
$clean_data = post(true);

Get a Specific Field

PHP
// Raw value (string/array/bool)
$username = post('username');

// Cleaned value
$clean_name = post('username', true);

// Cleaned and cast if numeric
$quantity = post('quantity', true, true);

Understanding the $clean_up Parameter

When $clean_up is true, performs two operations on string values:

  1. Trimming: Removes whitespace from the beginning and end of strings
  2. Collapsing: Reduces multiple consecutive spaces, tabs, or line breaks to a single space
PHP
// Input: "   Hello    World   \n\n"
$raw = post('message');               // Returns: "   Hello    World   \n\n"
$clean = post('message', true);       // Returns: "Hello World"

// Works recursively on arrays
$clean_array = post('items', true);   // Cleans each string in array

Numeric Casting

When $cast_numeric is true, purely numeric strings are converted to their appropriate PHP types:

PHP
// "42" → 42 (integer)
// "3.14" → 3.14 (float)
// "abc" → "abc" (string - not numeric)
// "0123" → "0123" (string - preserves leading zero)
$value = post('field', false, true);

Nested Data Access & JSON Payloads

post() automatically detects and parses JSON, and supports both common array notations:

Dot Notation (JSON/Nested Arrays)

PHP
// Data: {"user": {"profile": {"age": "25"}}}
$age = post('user.profile.age'); // "25"

Bracket Notation (Form/Arrays)

PHP
// Data: colors[0]=red&colors[1]=blue
$first = post('colors[0]'); // 'red'

JSON parsing: Malformed JSON throws an Exception. Wrap API endpoints in try-catch blocks.

Checkbox Values: A Special Case

Checkboxes require special handling because unchecked checkboxes don't submit any data. This is HTML behavior, not Trongate.

PHP
// After form submission:
$raw = post('subscribe', true); 

// If checkbox WAS checked: returns '1'
// If checkbox was NOT checked: returns '' (empty string)

// Convert to boolean for view display:
$for_view = (bool) post('subscribe', true);    // true or false

// Convert to integer for database storage:
$for_db = (int) (bool) post('subscribe', true); // 1 or 0

This pattern is essential for proper checkbox handling in Trongate applications.

Real-World Patterns

Form Processing Example

PHP
public function submit(): void {
    $data['name'] = post('name', true);
    $data['email'] = post('email', true);
    $data['age'] = post('age', true, true); // Clean and cast to int
    
    // Checkbox conversion pattern
    $data['active'] = (int) (bool) post('active', true);
    $data['newsletter'] = (int) (bool) post('newsletter', true);

    $this->db->insert($data, 'users');
    redirect('users/manage');
}

API Endpoint with JSON

PHP
public function api_create(): void {
    try {
        // JSON data automatically parsed
        $title = post('article.title', true);
        $content = post('article.content', true);
        
        // Process API request...
    } catch (Exception $e) {
        http_response_code(400);
        echo json_encode(['error' => 'Invalid JSON']);
    }
}

The function is solely for data retrieval, cleanup, and type casting. It does not perform HTML escaping.

Always use the framework's output helper (i.e., ) or htmlspecialchars() when displaying retrieved form data in a view to prevent Cross-Site Scripting (XSS) vulnerabilities.

Important Notes

  • Missing fields return empty string ('').
  • Data is parsed once and cached for the duration of the request.
  • Use post() for all data, post('field', true) for specific fields (recommended).
  • Checkboxes require (bool) conversion for views and (int) (bool) for database.
  • Data validation must be handled separately using the Validation class.

Instantly view the entire request POST payload (including JSON and nested arrays) by combining with the helper. For example:

PHP
json(post(), true);

This makes form debugging super easy!

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.

Leave Feedback About This Page