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: 1. The field name matches the current session token (Session::getToken()). 2. 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.'
    ]
]

Who catches it, and where that leaves your application¶

The flash-and-redirect this guide describes — errors and submitted input into the session, browser sent back to the form — is written inside Application::exec().

That is the whole MVC request cycle. An application that dispatches with Router::dispatch() never calls it, so it gets an uncaught ValidationException where this page promises a redirect. One line restores it:

$router->addGlobalMiddleware(new \Pramnos\Http\Middleware\ValidationRedirectMiddleware());

It catches only ValidationException — anything else passes through, because turning a real fault into a redirect back to the form is the most confusing outcome available: the visitor sees the page again with nothing wrong on it. Pass a path to the constructor for a form that should always return to one place; otherwise it uses HTTP_REFERER, exactly as Application::exec() does, falling back to the site root when there is none (some privacy tooling strips the header).

Two session conventions, and they do not interoperate¶

This is the sharp edge in this system, and it is invisible from either side:

Written by	Keys	Read by
`Request::validate()` + `Application::exec()` + `ValidationRedirectMiddleware`	`_validation_errors`, `_old_input`	`View::__construct()` → `$this->errors`; `Request::old()`
`FormRequest::failWith()`	`_form_errors`, `_form_old_input`	`FormRequest::errors()`, `FormRequest::old()` — statics

A view using $this->errors sees nothing after a FormRequest failure. The form redraws with no errors on it and no indication why, which reads as "validation is broken" rather than as "two conventions".

Pick one per form. If your templates use $this->errors and $request->old() — what the View gives you for free — use Request::validate(). Reach for FormRequest when you want the rules in their own class, and read the errors back through FormRequest's statics in the same place.

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.

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¶

Who catches it, and where that leaves your application¶

Two session conventions, and they do not interoperate¶

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`¶