NAME

Params::Filter - Secure field filtering for parameter construction

SYNOPSIS

use Params::Filter	qw/filter/;    # import filter() subroutine

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

# Functional interface
# Apply filter to incoming data (from web form, CLI, API, etc.)
my ($filtered_data, $status) = filter(
    $incoming_params,    # Data from external source
    \@required_fields,
    \@accepted_fields,
    \@excluded_fields,
);

if ($filtered_data) {
    # Success - use filtered data
    process_user($filtered_data);
} else {
    # Error - missing required fields
    die "Filtering failed: $status";
}

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

# Apply same filter to multiple incoming datasets
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);

# Closure interface (maximum speed)
use Params::Filter qw/make_filter/;

my $fast_filter = make_filter(
    [qw(id username)],      # required
    [qw(email bio)],        # accepted
    [qw(password token)],   # excluded
);

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

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:

**Field filtering** (this module) - Check which fields are present/absent
**Value validation** (later step) - Check if field values are correct

Primary Benefits

The main advantages of using Params::Filter are:

**Consistency** - Converts varying incoming data formats to consistent key-value pairs
**Security** - Sensitive fields (passwords, SSNs, credit cards) never reach your validation code or database statements
**Compliance** - Automatically excludes fields that shouldn't be processed or stored (e.g., GDPR, PCI-DSS)
**Correctness** - Ensures only expected fields are processed, preventing accidental data leakage or processing errors
**Maintainability** - Clear separation between data filtering (what fields to accept) and validation (whether values are correct)

Performance Considerations

Important: The functional and OO interfaces include features that add overhead compared to manual hash lookups, especially when the incoming data is in a known consistent format. The value of Params::Filter shows in its capability to assure the security, compliance, and correctness benefits listed above.

For speed with fewer features, the "CLOSURE INTERFACE" (make_filter) provides maximum performance and can be faster than hand-written Perl filtering code due to pre-computed exclusion lookups and specialized closure variants. Use make_filter for hot code paths or high-frequency filtering.

For all interfaces, Params::Filter CAN improve overall performance when downstream validation is expensive (database statements, API calls, complex regex) by failing fast when required fields are missing.

A simple benchmark comparing the validation cost of typical input to that of input restricted to required fields would reveal any speed gain with expensive downstream validations.

This Approach Handles Common Issues

Subroutine signatures can become unwieldy with many parameters
Ad-hoc argument checking is error-prone
Validation may not catch missing inputs quickly enough
Many fields to check multiplies validation time (for expensive validation)

When to Use This Module

This module is useful when you have:

Known parameters for downstream input or processes (API calls, method/subroutine arguments, database operations)
- Fields that must be provided for success downstream ("required")
- Fields useful downstream if provided ("accepted")
- Fields to remove before further processing ("excluded")
Incoming data from external sources (web forms, APIs, databases, user input)
No guarantee that incoming data is consistent or complete
Multiple data instances to process with the same rules
Multiple uses tapping incoming data
A distinction between missing and "false" data

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 module's expected use is to apply pre-defined rules to data that may be inconsistent or incomplete for its intended use. If there isn't repetition or an unknown/unreliable data structure, this might be overkill.

This Module Does NOT Do Fancy Stuff

As much as this module attempts to be versatile in usage, there are some VERY HANDY AFFORDANCES IT DOES NOT PROVIDE:

No regex field name matching for designating fields to require, accept, or exclude

No conditional field designations within a filter:

C<if 'mailing_address' require 'postal_code'>   # No way a filter can do this

No coderefs or callbacks for use when filtering
No substitutions or changes to field names
No built-in filter lists except null [] = none
No fields ADDED to yielded data, EXCEPT:
- If the provided data resolves to a list or array with an odd number of elements, the LAST element is treated as a flag, set to the value 1
- If the provided data resolves to a single non-reference scalar (probably a text string) the data is stored as a hashref value with the key '_', and returned if '_' is included in the accepted list or the list is set to ['*'] (accept all)

SECURITY

This module provides important security benefits by excluding sensitive fields before they reach downstream systems like logging, validation, or storage.

Safe Logging - Exclude Credentials

A common security requirement is logging user activity without exposing credentials:

use Params::Filter qw/make_filter/;

# Create filter for safe logging - exclude credentials
my $log_filter = make_filter(
    [qw(timestamp action)],           # required
    [qw(username email ip_address)],  # accepted - safe to log
    [qw(user_id password session_token)], # excluded - never logged
);

# Web form submission from user login
my $form_data = {
    timestamp    => '2026-01-27T10:30:00Z',
    action       => 'login_attempt',
    username     => 'alice',
    email        => 'alice@example.com',
    ip_address   => '192.168.1.100',
    user_id      => 12345,
    password     => 'secret123',      # MUST NOT appear in logs
    session_token => 'abc123xyz',     # MUST NOT appear in logs
};

# Filter for logging - credentials automatically excluded
my $log_entry = $log_filter->($form_data);
write_audit_log($log_entry);
# Logged: { timestamp, action, username, email, ip_address }
# Never logged: user_id, password, session_token

Multiple Filters for Data Segregation

Use different filters on the same input to route data to appropriate subsystems, ensuring credentials only reach authentication and never reach public display:

# Auth filter - requires credentials, excludes public data
my $auth_filter = Params::Filter->new_filter({
    required => ['user_id', 'password'],
    accepted => [],  # Only credentials, nothing else
    excluded => ['name', 'comment', 'category', 'date'],
});

# Comment filter - accepts public data, excludes credentials
my $comment_filter = Params::Filter->new_filter({
    required => ['name', 'comment'],
    accepted => ['category', 'date'],
    excluded => ['user_id', 'password'],  # Never show on comment page
});

# Single web form submission with mixed data
my $form_submission = {
    user_id  => 12345,
    password => 'secret123',
    name     => 'Alice',
    comment  => 'Great article!',
    category => 'feedback',
    date     => '2026-01-27',
};

# Route to authentication system - only credentials
my ($auth_data, $auth_msg) = $auth_filter->apply($form_submission);
if ($auth_data) {
    $app->authenticate($auth_data);
    # Sent to auth: { user_id => 12345, password => 'secret123' }
}

# Route to comment display - only public data
my ($comment_data, $comment_msg) = $comment_filter->apply($form_submission);
if ($comment_data) {
    $app->add_comment($comment_data);
    # Sent to comment page: { name => 'Alice', comment => '...', category => '...', date => '...' }
    # Password and user_id NEVER reach the comment display system
}

Compliance Benefits

Helps meet regulatory requirements by design:

**PCI-DSS** - Ensure credit card numbers never touch logging or validation code
**GDPR** - Exclude fields you shouldn't store before processing
**Data Minimization** - Only process fields you actually need for each subsystem
**Audit Trails** - Clear record of what fields are accepted/excluded per destination

Defense in Depth

Even if downstream validation code has bugs or is later modified, excluded fields never reach it:

# Logging system updated to dump all input - credentials still excluded
my $safe_data = $log_filter->($user_activity);
log_everything($safe_data);  # Password field was already filtered out

This provides defense in depth: sensitive data is removed at the filter layer, regardless of what happens downstream.

CLOSURE INTERFACE (Maximum Performance)

The closure interface provides maximum performance through specialized, pre-compiled closures. This is the most important performance feature of Params::Filter and can be faster than hand-written Perl filtering code.

Key Characteristics:

**Fastest interface** - Pre-computed exclusions, specialized variants
**Hashref input only** - No input parsing overhead (unlike functional/OO interfaces)
**Immutable** - Filter cannot be modified after creation (unlike OO interface)
**No error messages** - Returns undef on failure (unlike functional/OO interfaces)
**No debug mode** - Minimal overhead for maximum speed

Use this interface when: Performance is critical, you have high-frequency filtering operations, or you're processing large datasets.

make_filter

use Params::Filter qw/make_filter/;

# Create a reusable filter closure
my $filter = make_filter(
    \@required,     # Arrayref of required field names
    \@accepted,     # Arrayref of optional field names (default: [])
    \@excluded,     # Arrayref of names of fields to remove (default: [])
);

# Apply filter to data (must be hashref)
my $result = $filter->($input_hashref);

Creates a fast, reusable closure that filters hashrefs according to field specifications. The closure checks only for presence/absence of fields, not field values.

Parameters

\@required - Arrayref of names of fields that must be present
\@accepted - Arrayref of optional names of fields to accept (default: [])
\@excluded - Arrayref of names of fields to remove even if accepted (default: [])

Returns

A code reference that accepts a single hashref argument and returns a filtered hashref, or undef if required fields are missing.

Important: No error message is returned. The closure only returns the filtered hashref or undef. Use the functional or OO interfaces if you need error messages.

Specialized Closure Variants

The closure is optimized based on your configuration:

**Required-only** - When @accepted is empty, returns only required fields
**Wildcard** - When @accepted contains '*', accepts all input fields except exclusions
**Accepted-specific** - When @accepted has specific fields, returns required plus those accepted fields (minus exclusions)

Example

# Create filter for user registration
my $user_filter = make_filter(
    [qw(username email)],     # required
    [qw(full_name bio)],      # accepted
    [qw(password confirm)],   # excluded
);

# Apply to multiple records - very fast
for my $record (@records) {
    my $filtered = $user_filter->($record);
    next unless $filtered;  # Skip if required fields missing
    process_user($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
);

Performance Characteristics

Non-destructive - Original hashref is never modified
Pre-computed - Exclusion hash built once at filter creation
Specialized - No runtime conditionals, closure is tailored during construction
Can be faster than raw Perl - Up to 20-25% faster than hand-written filtering code in many cases
No overhead for multiple uses - Create once, apply many times

Trade-offs Compared to Other Interfaces

**Advantages**: Maximum speed, lightweight, no feature overhead, fastest option available
**Limitations**: No error messages, no debug mode, no modifier methods, no input parsing (only accepts hashrefs), immutable after creation
**When to use**: High-frequency filtering, performance-critical code, hot code paths, large dataset processing
**When to use OO/functional instead**: When you need error messages, debug mode, input format flexibility (arrayrefs/scalars), or dynamic reconfiguration

FUNCTIONAL INTERFACE

The functional interface provides direct parameter filtering through the filter() function. This interface supports flexible input parsing (hashrefs, arrayrefs, scalars) and returns detailed error messages.

Use this interface when: You need flexible input formats, detailed error messages, or one-off filtering operations.

filter

my ($filtered, $status) = filter(
    $input_data,     # Hashref, arrayref, or scalar
    \@required,      # Arrayref of required field names
    \@accepted,      # Arrayref of optional field names (default: [])
    \@excluded,      # Arrayref of names of fields to remove (default: [])
    $debug_mode,     # Boolean: enable warnings (default: 0)
);

# Scalar context - returns filtered hashref or undef on failure
my $result = filter($input, \@required, \@accepted);

Filters input data according to field specifications. Only checks for presence/absence of fields, not field values.

Parameters

$input_data - Input parameters (hashref, arrayref, or scalar)
\@required - Arrayref of names of fields that must be present
\@accepted - Arrayref of optional names of fields to accept (default: [])
\@excluded - Arrayref of names of fields to remove even if accepted (default: [])
$debug_mode - Boolean to enable warnings (default: 0)

Returns

In list context: (hashref, status_message) or (undef, error_message)

In scalar context: Hashref with filtered parameters, or undef on failure

Example

# Define filter rules (could be from config file)
my @required = qw(username email);
my @accepted = qw(full_name phone);
my @excluded = qw(password ssn);

# Apply to incoming data from web form
my ($user_data, $msg) = filter(
    $form_submission,
    \@required,
    \@accepted,
    \@excluded,
);

if ($user_data) {
    create_user($user_data);
} else {
    log_error($msg);
}

OBJECT-ORIENTED INTERFACE

The OO interface provides reusable filter objects that can be configured once and applied to multiple datasets. This interface includes the most features, including modifier methods for dynamic configuration.

new_filter

my $filter = Params::Filter->new_filter({
    required => ['field1', 'field2'],
    accepted => ['field3', 'field4', 'field5'],
    excluded => ['forbidden_field'],
    DEBUG    => 1,              # Optional debug mode
});

# Empty constructor - rejects all fields by default
my $strict_filter = Params::Filter->new_filter();

Creates a reusable filter object with predefined field rules. The filter can then be applied to multiple datasets using the "apply" method.

Parameters

required - Arrayref of names of required fields (default: [])
accepted - Arrayref of names of optional fields (default: [])
excluded - Arrayref of names of fields to always remove (default: [])
DEBUG - Boolean to enable debug warnings (default: 0)

Returns

A Params::Filter object

Example

# Create filter for user registration data
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 incoming datasets
my ($user1, $msg1) = $user_filter->apply($web_form_data);
my ($user2, $msg2) = $user_filter->apply($api_request_data);

apply

my ($filtered, $status) = $filter->apply($input_data);

Applies the filter's predefined rules to input data. This is the OO equivalent of the "filter" function.

Parameters

$input_data - Hashref, arrayref, or scalar to filter

Returns

In list context: (hashref, status_message) or (undef, error_message)

In scalar context: Hashref with filtered parameters, or undef on failure

Example

my $filter = Params::Filter->new_filter({
    required => ['id', 'type'],
    accepted => ['name', 'value'],
});

# Process multiple records from database
for my $record (@db_records) {
    my ($filtered, $msg) = $filter->apply($record);
    if ($filtered) {
        process_record($filtered);
    } else {
        log_error("Record failed: $msg");
    }
}

MODIFIER METHODS

The OO interface provides methods to modify a filter's configuration after creation.

Modifier Methods for Dynamic Configuration

The OO interface provides methods to modify a filter's configuration after creation.

# Start with an empty filter (rejects all by default)
my $filter = Params::Filter->new_filter();

# Configure it in steps as needed
$filter->set_required(['id', 'name']);
# later:
$filter->set_accepted(['email', 'phone'])
$filter->set_excluded(['password']);

Available Modifier Methods

**set_required(\@fields | @fields)** - Set required fields (accepts arrayref or list)
**set_accepted(\@fields | @fields)** - Set accepted fields (accepts arrayref or list)
**set_excluded(\@fields | @fields)** - Set excluded fields (accepts arrayref or list)
**accept_all()** - Convenience method: sets accepted to ['*'] (wildcard mode)
**accept_none()** - Convenience method: sets accepted to [] (reject all extras)

Important Behavior Notes

Empty Modifier Calls Set Empty Arrays:

If no fields are provided to set_required(), set_accepted(), or set_excluded(), the respective list is set to an empty array []:

$filter->set_accepted();  # Sets accepted to `[]`
# Result: Only required fields will be accepted (extras rejected)

Method Chaining:

All modifier methods return $self for chaining:

$filter->set_required(['id'])
        ->set_accepted(['name'])
        ->accept_all();  # Overrides set_accepted

Mutability:

A filter may call its modifier methods more than once, and the changes take effect immediately.

Meta-Programming Use Cases

These methods enable dynamic configuration for conditional scenarios:

# Environment-based configuration
my $filter = Params::Filter->new_filter();

if ($ENV{MODE} eq 'production') {
    $filter->set_required(['api_key', 'endpoint'])
          ->set_accepted(['timeout', 'retries'])
          ->set_excluded(['debug_info']);
}
else {
    $filter->set_required(['debug_mode'])
          ->accept_all();
}

# Dynamic field lists from config
my $config_fields = load_config('fields.json');
$filter->set_required($config_fields->{required})
      ->set_accepted($config_fields->{accepted})
      ->set_excluded($config_fields->{excluded});

INPUT PARSING

Note: This section applies to the "FUNCTIONAL INTERFACE" and "OBJECT-ORIENTED INTERFACE" only. The "CLOSURE INTERFACE (Maximum Performance)" accepts only hashrefs for maximum speed.

The filter() function parses multiple common input formats into a consistent internal structure. This flexibility allows you to use the module with data from differing sources such as form input, arguments to subroutines/methods, fetched database records, and test input, without pre-processing.

Supported Input Formats

1. Hashref (Most Common)

##### Uses the hashref's key-value pairs as provided

# External data source (e.g., from web form, API, or database)
my $incoming_user = { name => 'Alice', email => 'alice@example.com', phone => '555-1234' };

# Apply filter with rules defined inline
my ($result, $msg) = filter(
    $incoming_user,
    ['name', 'email'],
    ['phone'],
);
# Result: { name => 'Alice', email => 'alice@example.com', phone => '555-1234' }

2. Arrayref with Even Number of Elements

##### Makes key-value pairs from arrayref elements, reading left to right

# Pre-defined filter rules (typically defined at package level or in config)
my @required_fields = qw(name email);
my @accepted_fields = qw(age);

# External data from command-line arguments or similar list source
my @cli_args = ('name', 'Bob', 'email', 'bob@example.com', 'age', 30);

my ($result, $msg) = filter(
    \@cli_args,
    \@required_fields,
    \@accepted_fields,
);
# Result: { name => 'Bob', email => 'bob@example.com', age => 30 }

3. Arrayref with Odd Number of Elements

##### Makes key-value pairs from arrayref elements, reading left to right, but when an array has an odd number of elements, the last element (right-most) becomes a flag assigned the value 1:

# Pre-defined filter configuration
my @required = qw(name);
my @accepted = qw(verbose force);

# External data with odd number of elements (e.g., CLI args with flags)
my $command_args = ['name', 'Charlie', 'verbose', 'debug', 'force'];

my ($result, $msg) = filter(
    $command_args,
    \@required,
    \@accepted,
    [], 1,  # Debug mode to see warning
);
# Result: { name => 'Charlie', verbose => 'debug', force => 1 }
# Message includes: "Odd number of arguments provided; last element 'force' treated as flag"

4. Arrayref with Hashref as First Element

##### Uses the hashref's key-value pairs as provided, ignores rest of arrayref

# Pre-configured filter
my @required = qw(name);
my @accepted = qw(age title);

# External data source with hashref wrapped in array
my $arg0    = { name => 'Diana', age => 25, hire_date => 2026-01-09, title => 'CTO' };
my $arg1    = $something;
my $arg2    = $something_else;

my $api_response = [ $arg0, $arg1, $arg2, ];
my ($result, $msg) = filter(
    $api_response,
    \@required,
    \@accepted,
);
# Result: { name => 'Diana', age => 25, title => 'CTO' }

5. Single-Element Arrayref

##### Creates a hashref with the element as the value and '_' as its key. To make use of this feature, '_' or the wildcard '*' must be included in the appropriate filter lists.

# Filter configuration accepting special '_' key
my @required = ();
my @accepted = qw(_);

# External data: single-element array
my $single_value = ['search_query'];

my ($result, $msg) = filter(
    $single_value,
    \@required,
    \@accepted,
);
# Result: { _ => 'search_query' }

6. Plain Scalar (String)

##### Creates a hashref with the scalar as the value and '_' as its key. To make use of this feature, '_' or the wildcard '*' must be included in the appropriate filter lists.

Note: No attempt is made to parse strings into data.

# Pre-configured filter setup
my @required = ();
my @accepted = qw(_);

# External scalar data (e.g., raw input from file or stream)
my $raw_input = 'plain text string';

my ($result, $msg) = filter(
    $raw_input,
    \@required,
    \@accepted,
    [], 1,  # Debug mode to see warning
);
# Result: { _ => 'plain text string' }
# Message includes: "Plain text argument accepted with key '_': 'plain text string'"

7. List Passed as Arrayref

##### Flattened key-value lists must be wrapped in an arrayref

# Filter rules defined once, reused
my @req_fields = qw(name email);
my @acc_fields = qw(city);

# External key-value list data must be wrapped in arrayref
my ($result, $msg) = filter(
    [name => 'Eve', email => 'eve@example.com', city => 'Boston'],
    \@req_fields,
    \@acc_fields,
);
# Result: { name => 'Eve', email => 'eve@example.com', city => 'Boston' }

Special Parsing Keys

The `'_'` Key

- Used for scalar input and single-element arrays - Must be in accepted list or use wildcard ['*'] - Stores non-reference data that doesn't fit the hashref pattern

Parsing Status Messages (Always Provided)

These messages appear in the status message to inform you about structural transformations:

**Odd array elements**: "Odd number of arguments provided; last element 'X' treated as flag"
**Scalar input**: "Plain text argument accepted with key '_': 'preview...'"
**Single array element**: "Plain text argument accepted with key '_': 'preview...'"

These messages help you understand when your input format differs from the standard hashref.

RETURN VALUES

Both "filter" and "apply" return data in a consistent format, regardless of how the input was provided. The returned result's structure depends on context.

Return Structure

Scalar Context

# Pre-defined filter rules
my @required = qw(name);
my @accepted = qw(email);

# External input data
my $input = { name => 'Alice', email => 'alice@example.com' };

my $result = filter($input, \@required, \@accepted);
# Returns: hashref or undef on failure
if ($result) {
    say $result->{name};
}

List Context (Recommended)

# Filter configuration
my @required = qw(name email);
my @accepted = qw(phone);

# External data source
my $input = get_external_data();  # e.g., from API, web form, etc.

my ($data, $message) = filter($input, \@required, \@accepted);
# Returns: (hashref, status_message) or (undef, error_message)
if ($data) {
    say $data->{name};
} else {
    say "Error: $message";
}

Success

On success, returns a hashref containing only the fields that passed filtering:

# Pre-configured filter rules
my @required_fields = qw(name email);
my @accepted_fields = qw(phone);
my @excluded_fields = qw(password spam);

# External data source (e.g., web form submission)
my $web_form_data = {
    name     => 'Alice',
    email    => 'alice@example.com',
    password => 'secret',
    spam     => 'yes'
};

my ($user, $msg) = filter(
    $web_form_data,
    \@required_fields,
    \@accepted_fields,
    \@excluded_fields,
);

# $user = { name => 'Alice', email => 'alice@example.com' }
# $msg = "Admitted"

# Notes:
# - 'name' and 'email' included (required and present)
# - 'password' and 'spam' excluded (removed even if present)
# - 'phone' not in input, so not included
# - 'spam' not in required/accepted, so ignored

Failure

On failure (missing required fields), returns undef and an error message:

# Filter rules defined once, reused
my @required = qw(name email);
my @accepted = qw(phone);

# Incomplete external data
my $incomplete_data = { name => 'Bob' };  # email missing!

my ($data, $msg) = filter(
    $incomplete_data,
    \@required,
    \@accepted,
);

# $data = undef
# $msg = "Unable to initialize without required arguments: 'email'"

Status Message Types

The status message provides feedback about the filtering operation:

1. **"Admitted"** - Success, all required fields present
2. **"Unable to initialize without required arguments: 'field1', 'field2'"** - Failure, missing required fields
3. **Parsing messages** - Information about input format transformations (always provided)
4. **Debug warnings** - Information about excluded/unrecognized fields (provided in debug mode only)

Consistent Output Format

Regardless of input format, output is always a hashref:

# Filter rules (could be pre-defined constants)
my @req1 = qw(name);
my @acc1 = qw();

# Hashref input → hashref output
my $hash_input = { name => 'Alice' };
my $result1 = filter($hash_input, \@req1, \@acc1);
# → { name => 'Alice' }

# Arrayref input → hashref output
my @req2 = qw(name);
my @acc2 = qw(age);
my $array_input = ['name', 'Bob', 'age', 30];
my $result2 = filter($array_input, \@req2, \@acc2);
# → { name => 'Bob', age => 30 }

# Scalar input → hashref output with '_' key
my @req3 = qw();
my @acc3 = qw(_);
my $scalar_input = 'text';
my $result3 = filter($scalar_input, \@req3, \@acc3);
# → { _ => 'text' }

This consistency makes the filtered data easy to use in downstream code without worrying about the original input format.

FEATURES

**Dual interface** - Functional or OO usage
**Fast-fail** - Returns immediately on missing required parameters
**Fast-success** - Returns immediately if all required parameters are provided and no others are provided or will be accepted
**Flexible input** - Accepts hashrefs, arrayrefs, or scalars
**Wildcard support** - Use '*' in accepted list to accept all fields
**No value checking** - Only presence/absence of fields
**Debug mode** - Optional warnings about unrecognized or excluded fields
**Method chaining** - Modifier methods return $self
**Perl 5.36+** - Modern Perl with signatures and post-deref
**No dependencies** - Only core Perl's Exporter

DEBUG MODE

Note: This feature applies to the "FUNCTIONAL INTERFACE" and "OBJECT-ORIENTED INTERFACE" only. The "CLOSURE INTERFACE (Maximum Performance)" does not support debug mode for maximum speed.

Debug mode provides additional information about field filtering during development:

my ($filtered, $msg) = filter(
    $input,
    ['name'],
    ['email'],
    ['password'],
    1,  # Enable debug mode
);

Debug warnings (only shown when debug mode is enabled):

Excluded fields that were removed
Unrecognized fields that were ignored

Parsing messages (always shown, regardless of debug mode):

Plain text arguments accepted with key '_'
Odd number of array elements converted to flags

Parsing messages inform you about transformations the filter made to your input format. These are always reported because they affect the structure of the returned data. Debug warnings help you understand which fields were filtered out during development.

WILDCARD SUPPORT

Wildcard for Accepting Fields

# Accept all fields
filter($input, [], ['*']);

# Accept all fields except specific exclusions
filter($input, [], ['*'], ['password', 'ssn']);

# Required + all other fields
filter($input, ['id', 'name'], ['*']);

# Wildcard can appear anywhere in accepted list
filter($input, [], ['name', 'email', '*']);  # debugging: add '*' to see everything
filter($input, [], ['*', 'phone', 'address']);

Important Notes

'*' is only special in the accepted parameter
In required or excluded, '*' is treated as a literal field name
Empty [] for accepted means "accept none beyond required"
Multiple wildcards are redundant but harmless
Exclusions are always removed before acceptance is processed

Debugging Pattern

A common debugging pattern is to add '*' to an existing accepted list:

# Normal operation
filter($input, ['id'], ['name', 'email']);

# Debugging - see all inputs
filter($input, ['id'], ['name', 'email', '*']);

EXAMPLES

Form Field Filtering

use Params::Filter	qw/filter/;    # import filter() subroutine

# Define filtering rules (could be from config file)
my @required = qw(name email);
my @accepted = qw(phone city state zip);

# Apply to incoming web form data
my ($user_data, $status) = filter(
    $form_submission,   # Data from web form
    \@required,
    \@accepted,
);

if ($user_data) {
    register_user($user_data);
} else {
    show_error($status);
}

Reusable Filter for Multiple Data Sources

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

# Apply to multiple incoming datasets
my ($user1, $msg1) = $user_filter->apply($web_form_data);
my ($user2, $msg2) = $user_filter->apply($api_request_data);
my ($user3, $msg3) = $user_filter->apply($csv_import_data);

Environment-Specific Filtering

my $filter = Params::Filter->new_filter();

if ($ENV{APP_MODE} eq 'production') {
    # Strict: only specific fields allowed
    $filter->set_required(['api_key'])
          ->set_accepted(['timeout', 'retries'])
          ->set_excluded(['debug_info', 'verbose']);
} else {
    # Development: allow everything
    $filter->set_required(['debug_mode'])
          ->accept_all();
}

my ($config, $msg) = $filter->apply($incoming_config);

Security Filtering

# Remove sensitive fields from user input
my ($safe_data, $msg) = filter(
    $user_input,
    ['username', 'email'],           # required
    ['full_name', 'phone', 'bio'],    # accepted
    ['password', 'ssn', 'api_key'],   # excluded
);

# Result contains only safe fields
# password, ssn, api_key are removed even if provided

Dynamic Configuration from File

# Load filter rules from config file
my $config = decode_json(`cat filters.json`);

my $filter = Params::Filter->new_filter()
    ->set_required($config->{user_create}{required})
    ->set_accepted($config->{user_create}{accepted})
    ->set_excluded($config->{user_create}{excluded});

# Apply to incoming data
my ($filtered, $msg) = $filter->apply($api_data);

Data Segregation for Multiple Subsystems

Complex Data Flows

An application may need to handle incoming data from varying sources and prepare it for the same downstream processing. Filtering rules can be tailored to assure that only usable data is passed on.

An application may need to split incoming data into subsets for different handlers or storage locations. Multiple filters may be applied to a given input, and each filter extracts only the fields needed for its specific purpose, simplifying next steps and improving security through compartmentalization.

This example demonstrates how Params::Filter can integrate incoming data and segregate the yielded data for multiple outputs.

# Three different Subscription forms collect overlapping data:

#  Main subscription signup form collects:
#   name, email, zip,
#   user_id, password, credit_card_number, subscription_term

#  Subscription form with full profile collects:
#  name, email, address, city, state, zip,
#  user_id, password, credit_card_number, subscription_term,
#  phone, occupation, position, education
#  alt_card_number, billing_address, billing_zip

#  Promo subscription form collects:
#  name, email, zip, subscription_term,
#  user_id, password, credit_card_number, promo_code

my $data = $webform->input(); # From any of the above

# Three different uses for the data:
#  Personal contact info to be stored
#  Subscription business to be transacted
#  Authentication credentials to be encrypted and stored

# Personal data filter - general user info (no sensitive data)
my $person_filter = Params::Filter->new_filter({
    required => ['name', 'user_id', 'email'],
    accepted => ['address', 'city', 'state', 'zip', 'phone',
                 'occupation', 'position', 'education'],
    excluded => ['password', 'credit_card_number'],
});

# Business data filter - subscription and billing info
my $biz_filter = Params::Filter->new_filter({
    required => ['user_id', 'name', 'subscription_term', 'credit_card_number', 'zip'],
    accepted => ['alt_card_number', 'billing_address', 'billing_zip', 'promo_code'],
    excluded => ['password'],
});

# Authentication data filter - only credentials
my $auth_filter = Params::Filter->new_filter({
    required => ['user_id', 'password'],
    accepted => [],
    excluded => [],
});

# Apply all filters to the same web form submission
my ($person_data,     $pmsg) = $person_filter->apply($data);
my ($biz_data,        $bmsg) = $biz_filter->apply($data);
my ($auth_data,       $amsg) = $auth_filter->apply($data);

# One way to use the filter results:
# Set the requirement that all filtering requirements must be met
# with data provided by any of the three webform sources:
unless ($person_data && $biz_data && $auth_data) {
  return "Unable to add user: " .
    join ' ' => grep { $_ ne 'Admitted' } ($pmsg, $bmsg, $amsg);
}

# Route each filtered data subset to appropriate handler
$self->add_user(         $person_data   );    # User profile
$self->set_subscription( $biz_data      );    # Billing system
$self->set_password(     $auth_data     );    # Auth system

Note: The original $data is not modified during filtering, so the same data can be safely processed by multiple filters.

AUTHOR

Bruce Van Allen <bva@cruzio.com>

LICENSE

This module is licensed under the same terms as Perl itself. See perlartistic.

COPYRIGHT

To install Params::Filter, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Params::Filter

CPAN shell

perl -MCPAN -e shell
install Params::Filter

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Primary Benefits

Performance Considerations

This Approach Handles Common Issues

When to Use This Module

When NOT to Use This Module

This Module Does NOT Do Fancy Stuff

SECURITY

Safe Logging - Exclude Credentials

Multiple Filters for Data Segregation

Compliance Benefits

Defense in Depth

CLOSURE INTERFACE (Maximum Performance)

make_filter

Parameters

Returns

Specialized Closure Variants

Example

Performance Characteristics

Trade-offs Compared to Other Interfaces

FUNCTIONAL INTERFACE

filter

Parameters

Returns

Example

OBJECT-ORIENTED INTERFACE

new_filter

Parameters

Returns

Example

apply

Parameters

Returns

Example

MODIFIER METHODS

Modifier Methods for Dynamic Configuration

Available Modifier Methods

Important Behavior Notes

Meta-Programming Use Cases

INPUT PARSING

Supported Input Formats

1. Hashref (Most Common)

2. Arrayref with Even Number of Elements

3. Arrayref with Odd Number of Elements

4. Arrayref with Hashref as First Element

5. Single-Element Arrayref

6. Plain Scalar (String)

7. List Passed as Arrayref

Special Parsing Keys

The '_' Key

Parsing Status Messages (Always Provided)

RETURN VALUES

Return Structure

Scalar Context

List Context (Recommended)

Success

Failure

Status Message Types

Consistent Output Format

FEATURES

DEBUG MODE

WILDCARD SUPPORT

Wildcard for Accepting Fields

Important Notes

Debugging Pattern

EXAMPLES

Form Field Filtering

Reusable Filter for Multiple Data Sources

Environment-Specific Filtering

Security Filtering

Dynamic Configuration from File

Data Segregation for Multiple Subsystems

SEE ALSO

AUTHOR

LICENSE

COPYRIGHT

Module Install Instructions

The `'_'` Key