form_radio()
function form_radio(string $name, string|bool|int $value = '', mixed $checked = false, array $attributes = []): string
Description
Generates an HTML radio button input element. Radio buttons allow users to select exactly one option from a group of choices.
Unlike checkboxes, radio buttons always submit a value to the server, provided one in the group is selected.
Parameters
| Parameter |
Type |
Description |
| $name |
string |
The name attribute for the radio button element. All radio buttons in a group must share the same name. |
| $value |
string|bool|int |
(optional) The value submitted when this radio button is selected. Defaults to empty string. |
| $checked |
mixed |
(optional) Whether this radio button should be checked. Default is false. Accepts true, false, 'true', 'false', 1, 0, '1', '0', 'yes', 'no', 'on', 'off'. |
| $attributes |
array |
(optional) HTML attributes like class, id, etc. Defaults to an empty array ([]). |
Return Value
| Type |
Description |
| string |
HTML radio button input element. |
Example Usage
Imagine you're building a task manager where users can select a priority level. Here's how radio buttons work in Trongate:
1. Creating a Radio Button Group
In your view, you typically create multiple radio buttons with the same name:
<?php
echo form_label('Priority Level:');
echo '<div class="radio-group">';
echo '<div>';
echo form_radio('priority', 'low', $priority === 'low');
echo form_label('Low Priority', ['for' => 'priority_low']);
echo '</div>';
echo '<div>';
echo form_radio('priority', 'medium', $priority === 'medium');
echo form_label('Medium Priority', ['for' => 'priority_medium']);
echo '</div>';
echo '<div>';
echo form_radio('priority', 'high', $priority === 'high');
echo form_label('High Priority', ['for' => 'priority_high']);
echo '</div>';
echo '</div>';
?>
2. In Your Controller
The controller handles both displaying and processing radio buttons:
class Tasks extends Trongate {
public function create(): void {
$update_id = segment(3, 'int');
if ($update_id > 0 && REQUEST_TYPE === 'GET') {
// Editing existing task
$task = $this->db->get_where($update_id, 'tasks');
$data['priority'] = $task->priority; // e.g., 'medium'
} else {
// New task or redisplay after validation error
$data['priority'] = post('priority', true);
}
$this->view('task_form', $data);
}
public function submit(): void {
$this->validation->set_rules('priority', 'priority level', 'required');
if ($this->validation->run() === true) {
$data['task_title'] = post('task_title', true);
$data['priority'] = post('priority', true); // Simple - no conversion needed
$this->db->insert($data, 'tasks');
}
}
}
Flexible Checked Parameter
The $checked parameter accepts various truthy/falsy values, making comparisons easy:
// All of these produce a checked radio button:
echo form_radio('option', 'yes', true);
echo form_radio('option', 'yes', 'true');
echo form_radio('option', 'yes', 'yes');
echo form_radio('option', 'yes', 'on');
echo form_radio('option', 'yes', '1');
echo form_radio('option', 'yes', 1);
// All of these produce an unchecked radio button:
echo form_radio('option', 'yes', false);
echo form_radio('option', 'yes', 'false');
echo form_radio('option', 'yes', 'no');
echo form_radio('option', 'yes', 'off');
echo form_radio('option', 'yes', '0');
echo form_radio('option', 'yes', 0);
Key Differences from Checkboxes
Radio buttons don't need the complex conversion patterns that checkboxes require.
// Radio buttons - simple string values
$selected_value = post('priority', true); // Returns 'low', 'medium', 'high', or '' (if not set in POST data)
// Checkboxes - require conversion
$checkbox_value = (int) (bool) post('complete', true); // Returns 1 or 0
Simple Examples
Basic radio button (unchecked):
echo form_radio('color', 'red');
// Output: <input type="radio" name="color" value="red">
Checked radio button:
echo form_radio('color', 'blue', true);
// Output: <input type="radio" name="color" value="blue" checked="checked">
With comparison logic (common pattern):
$selected_color = 'blue';
echo form_radio('color', 'red', $selected_color === 'red');
echo form_radio('color', 'blue', $selected_color === 'blue');
echo form_radio('color', 'green', $selected_color === 'green');
Working with Radio Button Groups
Radio buttons work in groups where only one can be selected. Here's a complete example:
// Define options
$status_options = [
'pending' => 'Pending',
'in_progress' => 'In Progress',
'completed' => 'Completed'
];
$selected_status = post('status', true) ?? 'pending';
foreach ($status_options as $value => $label) {
echo '<div>';
echo form_radio('status', $value, $selected_status === $value);
echo ' ' . $label;
echo '</div>';
}
Common Attributes
Add HTML attributes as needed:
$attributes = [
'class' => 'form-radio',
'id' => 'option-premium',
'data-price' => '99.99'
];
echo form_radio('plan', 'premium', $selected_plan === 'premium', $attributes);
Form Submission Behavior
When a form with radio buttons submits:
// If a radio button is selected:
$value = post('priority', true); // Returns the selected value, e.g., 'high'
// If NO radio button is selected:
$value = post('priority', true); // Returns '' (empty string)
**Important:** If none of the radio buttons in a group are checked, the field will not be present in the `$_POST` array. The post() function with the second parameter set to `true` (XSS cleaning) handles this gracefully by returning an empty string ('').
Database Schema
Store radio button values as strings or enums in your database:
CREATE TABLE tasks (
id INT PRIMARY KEY AUTO_INCREMENT,
task_title VARCHAR(255),
priority ENUM('low', 'medium', 'high') DEFAULT 'medium',
status ENUM('pending', 'in_progress', 'completed') DEFAULT 'pending'
);
Quick Reference
| Element |
View Code |
To View (Re-population) |
To Database (Processing) |
| Radio Button |
form_radio('field', 'value', $selected === 'value') |
post('field', true) |
post('field', true) |
| Checkbox |
form_checkbox('field', 1, (bool) $checked) |
(bool) post('field', true) |
(int) (bool) post('field', true) |
| Text Input |
form_input('field', $value) |
post('field', true) |
post('field', true) |
Remember: Radio buttons use the same string value for both views and databases. The main challenge is determining which radio button should be checked when displaying the form.