/ 
Params-Filter-0.016
/ README.md

Params::Filter

Secure field filtering for parameter construction.

Description

Params::Filter provides lightweight parameter filtering that checks only for the presence or absence of specified fields. It does NOT validate values - no type checking, truthiness testing, or lookups.

This module separates field filtering from value validation:

Why Use This Module

Installation

perl Makefile.PL
make
make test
make install

Quick Start

Functional Interface

use Params::Filter qw/filter/;

# Define filter rules
my @required_fields = qw(name email);
my @accepted_fields = qw(phone city state zip);
my @excluded_fields = qw(ssn password);

# Apply filter to incoming data
my ($filtered_data, $status) = filter(
    $incoming_params,    # From web form, CLI, API, etc.
    \@required_fields,
    \@accepted_fields,
    \@excluded_fields,
);

if ($filtered_data) {
    process_user($filtered_data);
} else {
    die "Filtering failed: $status";
}

Object-Oriented Interface

use Params::Filter;

# Create a reusable filter object
my $user_filter = Params::Filter->new_filter({
    required => ['username', 'email'],
    accepted => ['first_name', 'last_name', 'phone', 'bio'],
    excluded => ['password', 'ssn', 'credit_card'],
});

# Apply to multiple data sources
my ($user1, $msg1) = $user_filter->apply($web_form_data);
my ($user2, $msg2) = $user_filter->apply($api_request_data);
my ($user3, $msg3) = $user_filter->apply($db_record_data);

if ($user1) {
    process_user($user1);
} else {
    return_error($msg1);
}

Closure Interface (Maximum Speed)

use Params::Filter qw/make_filter/;

# Create a high-performance filter closure
my $fast_filter = make_filter(
    [qw(id username)],      # required
    [qw(email bio)],        # accepted
    [qw(password token)],   # excluded
);

# Apply to high-volume data streams
for my $record (@large_dataset) {
    my $filtered = $fast_filter->($record);
    next unless $filtered;  # Skip if required fields missing
    process($filtered);
}

# Wildcard example - accept everything except sensitive fields
my $safe_filter = make_filter(
    [qw(id type)],
    ['*'],                      # accept all other fields
    [qw(password token ssn)],   # but exclude these
);

my $log_entry = $safe_filter->($incoming_data);
log_to_file($log_entry);  # Passwords, tokens, SSNs never logged

The closure interface provides maximum performance for hot code paths. It creates a specialized, optimized closure based on your configuration and can be faster than hand-written Perl filtering code.

Security Example

# Remove sensitive fields early in processing pipeline
my $user_filter = Params::Filter->new_filter({
    required => ['username', 'email'],
    accepted => ['name', 'bio'],
    excluded => ['password', 'ssn', 'credit_card', 'admin_token'],
});

# Even if malicious user submits admin_token, it never reaches validation
my ($filtered, $msg) = $user_filter->apply($untrusted_input);
# Excluded fields are removed before any downstream processing

When to Use This Module

Use Params::Filter when you have:

When NOT to Use This Module

If you're constructing both the filter rules AND the data structure at the same point in your code, you probably don't need this module. The expected use is to apply pre-defined rules to data that may be inconsistent or incomplete. If there isn't repetition or an unknown/unreliable data structure, this might be overkill.

Documentation

For comprehensive documentation, see:

perldoc Params::Filter

The POD documentation includes:

Examples Directory

The examples/ directory contains working scripts demonstrating various features:

Features

Author

Bruce Van Allen bva@cruzio.com

License

perl_5

Copyright (C) 2026, Bruce Van Allen