Implementing Custom InputFilters for Data Validation in Laminas

The Problem: Leaky Validation Logic

When validation logic is placed directly inside a controller or handler, the application becomes difficult to test and maintain. Business rules—such as ensuring an email is unique or a password meets complexity requirements—become scattered across the codebase, leading to inconsistent data entry across different API endpoints or forms.

The solution is to encapsulate these rules within a Laminas\InputFilter. This allows you to decouple data normalization (filtering) and verification (validation) from the request-handling logic, ensuring that only sanitized, valid data reaches your domain models.

Prerequisites

• A working Laminas MVC or Mezzio installation.
• The laminas/laminas-inputfilter package installed via Composer.
• Basic familiarity with the ServiceManager for dependency injection.

Defining the InputFilter

A custom InputFilter should extend Laminas\InputFilter\InputFilter. This allows you to define a set of Input objects, each containing a Filter Chain (to transform data) and a Validator Chain (to verify data).

Implementation Example

Consider a user registration scenario where we need to trim whitespace, normalize email casing, and ensure a username is not empty.

namespace App\InputFilter;

use Laminas\InputFilter\InputFilter;
use Laminas\InputFilter\Input;
use Laminas\Filter\StringTrim;
use Laminas\Filter\StringToLower;
use Laminas\Validator\EmailAddress;
use Laminas\Validator\NotEmpty;

class UserRegistrationFilter extends InputFilter
{
    public function init()
    {
        // Username Input
        $this->add([
            'name' => 'username',
            'required' => true,
            'filters' => [
                ['name' => StringTrim::class],
            ],
            'validators' => [
                ['name' => NotEmpty::class],
            ],
        ]);

        // Email Input
        $this->add([
            'name' => 'email',
            'required' => true,
            'filters' => [
                ['name' => StringTrim::class],
                ['name' => StringToLower::class],
            ],
            'validators' => [
                ['name' => EmailAddress::class],
            ],
        ]);
    }
}

Integrating with the ServiceManager

To maintain testability, avoid instantiating the filter with new inside your controller. Instead, register it in your configuration so the InputFilterPluginManager can handle its creation.

Configuration (module.config.php):

return [
    'input_filters' => [
        'factories' => [
            App\InputFilter\UserRegistrationFilter::class => 
                Laminas\ServiceManager\Factory\InvokableFactory::class,
        ],
    ],
];

Executing the Validation Task

Run the following logic within your Controller or Middleware. You must inject the InputFilterPluginManager or the specific filter instance via the constructor.

1. Set Data: Pass the raw request data (usually an array from $this->params()->fromPost() or $request->getParsedBody()) into the filter using setData().
2. Validate: Call isValid(). This triggers the filter chain first, then the validator chain.
3. Retrieve Results: If valid, use getValues() to retrieve the normalized data. If invalid, use getMessages() to retrieve a map of errors.

// Inside a Controller action
public function registerAction()
{
    $requestData = $this->params()->fromPost();
    $filter = $this->inputFilterManager->get(UserRegistrationFilter::class);
    
    $filter->setData($requestData);

    if (!$filter->isValid()) {
        return new JsonModel([
            'status' => 'error',
            'messages' => $filter->getMessages()
        ]);
    }

    // getValues() returns the TRIMMED and LOWERCASED data
    $safeData = $filter->getValues();
    // Proceed to save $safeData to database
}

Verification and Diagnostics

To verify the implementation, perform these three checks:

1. Normalization Check: Pass an email as " [contact removed] " . Verify that getValues() returns "[contact removed]".
2. Validation Failure: Pass an empty string for the username. Verify that isValid() returns false and getMessages()['username'] contains the NotEmpty error.
3. Type Safety: Ensure the data passed to setData() is an array. Passing a null value or a string will result in a TypeError.

Limitations and Risks

• External Dependencies: If a validator requires a database connection (e.g., Laminas\Validator\Db\NoRecordExists), you cannot use InvokableFactory. You must write a custom factory to inject the DbAdapter into the InputFilter.
• Performance: Large chains of complex validators (especially those hitting external APIs or DBs) can slow down request handling. Cache validation results if the data is immutable for the session.

Rollback and Recovery

Since InputFilters are stateless data processors, they do not change the state of the application or database. To "roll back" a configuration change, remove the entry from the input_filters config array and revert the controller to its previous data-handling logic.