Pramnos Validation System Guide

The Pramnos Framework includes a lightweight validation system for validating incoming data in a centralized and reusable way.

This feature was designed to reduce manual validation code inside controllers and provide a cleaner, more maintainable flow for both WWW and API applications.

Overview

Validation is primarily performed through the Request object.

$request = new \Pramnos\Http\Request();

$data = $request->validate([
    'name' => 'required|string|min:3|max:255',
]);

If validation succeeds, the validated input is returned as an array.

If validation fails, a Pramnos\Validation\ValidationException is thrown.

Main Components

The validation system is built around the following classes:

Pramnos\Validation\Validator
Pramnos\Validation\ValidationException
Pramnos\Http\Request

It is also integrated into:

Pramnos\Application\Application
Pramnos\Application\Api
Pramnos\Application\View

Basic Usage

Validating Request Data

$request = new \Pramnos\Http\Request();

$data = $request->validate([
    'name' => 'required|string|min:3|max:255',
    'type' => 'nullable|integer|in:0,1',
    'value' => 'nullable|numeric',
], [], [], 'POST');

Returned Value

If validation passes, validate() returns an array containing the validated input values.

[
    'name' => 'Main metric',
    'type' => '1',
    'value' => '12.5'
]

Available Request Helper Methods

The following helper methods are available on Pramnos\Http\Request.

`all()`

Returns all input data from a specific input source.

$request->all('POST');
$request->all('GET');
$request->all('PUT');
$request->all('DELETE');

`allCurrent()`

Returns all input data from the current request method.

$data = $request->allCurrent();

`only()`

Returns only selected keys from the request input.

$data = $request->only(['name', 'email'], 'POST');

`validate()`

Validates request input using the validation rules.

$data = $request->validate([
    'name' => 'required|string|max:255',
]);

`errors()`

Returns flashed validation errors for the current request.

$errors = $request->errors();

`old()`

Returns old input values stored after validation failure.

$request->old('name');
$request->old('name', 'default value');

`clearValidationState()`

Clears validation errors and old input values.

$request->clearValidationState();

Validation Rules

Rules are declared as strings separated by |.

Supported Rules

Rule	Description
`required`	The field must be present and must not be empty
`nullable`	The field may be missing, `null`, or an empty string
`string`	The field must be a string
`integer`	The field must be an integer
`numeric`	The field must be numeric
`min:x`	Minimum numeric value or minimum string length
`max:x`	Maximum numeric value or maximum string length
`between:min,max`	Value or length must be within the specified interval
`in:a,b,c`	The field value must be one of the allowed values
`csrf`	The security token must be valid for the session
`url`	The field must be a valid URL format
`json`	The field must be a valid JSON string

Rule Details

`min`, `max`, and `between`

These rules are type-aware and adapt their behavior based on the input:

Strings: Validates the number of characters (using mb_strlen).
Numbers: Validates the numeric value.
Arrays: Validates the number of elements in the array.

Rule	String Example	Numeric Example	Array Example
`min:3`	At least 3 chars	Value >= 3	At least 3 items
`max:10`	At most 10 chars	Value <= 10	At most 10 items
`between:1,5`	1 to 5 chars	Value from 1 to 5	1 to 5 items

`csrf`

The csrf rule verifies the security token for the request. Because Pramnos uses dynamic parameter names for CSRF tokens, the rule automatically verifies that:

The field name matches the current session token (Session::getToken()).
The field value is set to '1'.

Note: This rule requires an active session.

`url`

Validates that the input is a valid URL. It automatically adds http:// if a protocol is missing (e.g., google.com becomes http://google.com).

`json`

Validates that the input is a valid JSON string. Uses json_validate() on PHP 8.3+ for better performance.

Example

$session = \Pramnos\Http\Session::getInstance();
$token = $session->getToken();

$request->validate([
    $token => 'csrf', // Dynamic CSRF validation
    'name' => 'required|string|min:3|max:255',
    'type' => 'required|integer|in:0,1',
    'interval' => 'nullable|integer|min:0',
    'value' => 'nullable|numeric|between:0,100',
    'website' => 'nullable|url',
]);

How Validation Failures Work

When validation fails, the validator throws:

\Pramnos\Validation\ValidationException

Example

try {
    $data = $request->validate([
        'name' => 'required|string|min:3|max:255',
    ]);
} catch (\Pramnos\Validation\ValidationException $e) {
    $errors = $e->errors();
}

Error Structure

The exception stores validation errors as an array grouped by field name.

[
    'name' => [
        'The name field is required.'
    ]
]

WWW Application Flow

In standard WWW applications, validation failures are automatically handled by the framework.

Inside Pramnos\Application\Application::exec():

validation errors are stored in session
old input is stored in session
the user is redirected back to the previous page

This means controllers only need to call validate() and do not need to manually handle failed validation in the common web flow.

Example Controller

public function save()
{
    $request = new \Pramnos\Http\Request();

    $data = $request->validate([
        'name' => 'required|string|min:3|max:255',
    ], [], [], 'POST');

    // Continue only if validation passes
}

Using Validation in Views

The framework exposes request and validation data to views.

Inside Pramnos\Application\View, the following are available:

$this->request
$this->errors

This allows validation state to be used directly in templates.

Example: Displaying All Errors

<?php if (!empty($this->errors)) : ?>
    <div class="alert alert-danger">
        <strong>There are validation errors:</strong>
        <ul>
            <?php foreach ($this->errors as $fieldErrors) : ?>
                <?php foreach ($fieldErrors as $error) : ?>
                    <li><?php echo $error; ?></li>
                <?php endforeach; ?>
            <?php endforeach; ?>
        </ul>
    </div>
<?php endif; ?>

Example: Repopulating Old Input

<input
    type="text"
    name="name"
    value="<?php echo $this->request->old('name', $this->model->name); ?>"
>

This is especially useful in edit/create forms after failed validation.

Flash Validation State

Validation state is flashed for the next request only.

This means:

after a failed validation, errors and old input are available on the redirected page
refreshing again should not keep showing the same validation state forever
opening a different form should not reuse old validation state from another page

This behavior makes validation act like a standard form flash session workflow.

API Usage

In API applications, validation should typically be handled by returning a structured response.

Example

try {
    $data = $request->validate([
        'name' => 'required|string|max:255',
    ], [], [], 'POST');
} catch (\Pramnos\Validation\ValidationException $e) {
    return [
        'status' => 422,
        'message' => $e->getMessage(),
        'error' => 'ValidationError',
        'errors' => $e->errors(),
    ];
}

The framework API handling can then translate this into a proper JSON response.

Standalone Validator Usage

The validator can also be used without the Request object.

This is useful when validating plain arrays outside the HTTP layer.

use Pramnos\Validation\Validator;

$data = [
    'name' => 'Example'
];

$rules = [
    'name' => 'required|string|min:3|max:255'
];

$validated = Validator::validate($data, $rules);

If validation fails, a ValidationException is thrown.

Practical Notes

1. Validation should not change existing project behavior without a reason

When introducing validation into old controllers, it is usually better to start with forgiving rules and preserve existing behavior where possible.

For example, if a field used to allow an empty string, avoid making it suddenly required unless that is an intentional business rule change.

2. Use database structure as a guide, but not blindly

Database schema is useful for identifying maximum string lengths, nullable fields, and numeric fields, but old projects may still contain legacy behavior that is more forgiving than the raw schema.

3. Nullable foreign keys should be handled carefully

If a foreign key field is optional, it is often safer to map an empty request value to null instead of 0, especially when the database enforces foreign key constraints.

Example: Typical Controller Pattern

public function save()
{
    $model = new \App\Models\Metric($this);
    $request = new \Pramnos\Http\Request();

    $data = $request->validate([
        'name' => 'required|string|max:255',
        'label' => 'nullable|string|max:255',
        'unitLabel' => 'nullable|string|max:128',
        'unit' => 'nullable|string|max:50',
        'datapointid' => 'nullable|integer|min:1',
        'locationid' => 'nullable|integer|min:1',
        'type' => 'nullable|integer|in:0,1',
        'value' => 'nullable|numeric',
    ], [], [], 'POST');

    $model->name = trim(strip_tags($data['name']));
    $model->label = isset($data['label']) ? trim(strip_tags($data['label'])) : '';
    $model->unitLabel = isset($data['unitLabel']) ? trim(strip_tags($data['unitLabel'])) : '';
    $model->unit = isset($data['unit']) ? trim(strip_tags($data['unit'])) : '';

    $model->datapointid = ($request->get('datapointid', '', 'post') === '')
        ? null
        : (int) $data['datapointid'];

    $model->locationid = ($request->get('locationid', '', 'post') === '')
        ? null
        : (int) $data['locationid'];

    $model->type = isset($data['type']) ? (int) $data['type'] : 0;
    $model->value = isset($data['value']) ? (float) $data['value'] : null;

    $model->save();
}

Future Improvements

Possible future enhancements for the validation system include:

additional validation rules
custom validation messages
custom attribute names
field-level error helpers in views
Form Request classes
middleware integration
schema-aware validation helpers

Summary

The Pramnos validation system provides:

centralized validation logic
reusable validation rules
integration with requests, views, WWW applications, and APIs
old input preservation
session-based error flashing

It is designed to be lightweight, extensible, and safe to introduce gradually into existing projects.

FilesExpand file tree

Pramnos_Validation_System_Guide.md

Latest commit

History

Pramnos_Validation_System_Guide.md

File metadata and controls

Pramnos Validation System Guide

Overview

Main Components

Basic Usage

Validating Request Data

Returned Value

Available Request Helper Methods

all()

allCurrent()

only()

validate()

errors()

old()

clearValidationState()

Validation Rules

Supported Rules

Rule Details

min, max, and between

csrf

url

json

Example

How Validation Failures Work

Example

Error Structure

WWW Application Flow

Example Controller

Using Validation in Views

Example: Displaying All Errors

Example: Repopulating Old Input

Flash Validation State

API Usage

Example

Standalone Validator Usage

Practical Notes

1. Validation should not change existing project behavior without a reason

2. Use database structure as a guide, but not blindly

3. Nullable foreign keys should be handled carefully

Example: Typical Controller Pattern

Future Improvements

Summary

`all()`

`allCurrent()`

`only()`

`validate()`

`errors()`

`old()`

`clearValidationState()`

`min`, `max`, and `between`

`csrf`

`url`

`json`