/ 
CGI-Application-Plugin-ValidateQuery-1.0.5
River stage zero No dependents
/ CGI::Application::Plugin::ValidateQuery

NAME

CGI::Application::Plugin::ValidateQuery - lightweight query validation for CGI::Application

VERSION

Version 1.0.5

SYNOPSIS

use CGI::Application::ValidateQuery qw(validate_query
                                       validate_app_params
                                       validate_query_config
                                       :types);

sub setup {
    my $self = shift;

    $self->validate_query_config(
           # define a page to show for invalid queries, or default to
           # serving a plain, internal page
           error_mode            => 'my_invalid_query_run_mode',
           log_level             => 'notice',
           allow_extra           => 0
    );

}

sub my_run_mode {
   my $self = shift;

   # validate select options stored in the app itself
   $self->validate_app_params(
       user_id  => qr/\A[a-zA-Z]\z/,
   );

   # move on...
}

sub another_run_mode {
   my $self = shift;

   # validate the query and return a standard error page on failure.
   $self->validate_query(
           pet_id    => SCALAR,
           direction => { type => SCALAR, default => 'up' },
   );

   # go on with life...

}

DESCRIPTION

This plugin is for small query validation tasks. For example, perhaps you link to a page where a "pet_id" is required, and you need to reality check that this exists or return essentially a generic error message to the user.

Even if your application generates the link, it may become altered through tampering, malware, or other unanticipated events.

This plugin uses Params::Validate to validate either a query object or values stored in a CGI::Application object. You can define your own error page to return on failure, or import a plain default one that we supply.

You may also define a log_level, if you do, we will also log each validation failure at the chosen level like this:

$self->log->$loglevel("Query validation failed: $@");

CGI::Application::Plugin::LogDispatch is one plugin which implements this logging API.

validate_query

$self->validate_query(
                        pet_id      => qr/\A\d+\z/, # implies regex and type=>SCALAR
                        species     => { type => SCALAR, default => 'lizard' },
                        log_level   => 'critical',  # optional
                        allow_extra => 1  # optional, default is 0
 );

Validates $self->query using Params::Validate. If any required query param is missing or invalid, the run mode defined with validate_query_config will be used. If you don't want to supply one, you can import a plain error run mode--validate_query_error_mode that we provide. It will be returned by default. validate_query_config is usually called in setup(), or a in a project super-class.

If log_level is defined, it will override the the log level provided in validate_query_config and log a validation failure at that log level.

If allow_extra is defined and true, any parameter found in $self->query not listed in the call to validate_query will be ignored by the check (in other words, it will be included in the profile passed to Params::Validate but marked only as optional). If this is all the validation you're performing, don't use this; this option is here for cases where, for example, a bunch of POST values are already being checked by something heavier like Data::FormValidator and you just want to check one or two GET values.

If you set a default for any parameter, the query will be modified with that value should that parameter be missing.

validate_app_params

$self->validate_app_params(
    user_id  => qr/\A[a-zA-Z]\z/,
);

Behaves like validate_query with these exceptions:

  • allow_extra is set to true

  • items specified are looked for and validated using $self-param> instead of $self-query->param>.

IMPLENTATION NOTES

We re-export the constants provided in Params::Validate. They can be loaded using either the :all tag or by including the :types tag along with the validate_query methods. Using :all will import everything from both this module and from Params::Validate.

We set "local $Params::Validate::NO_VALIDATION = 0;" to be sure that Params::Validate works for us, even if is globally disabled.

To alter the application flow when validation fails, we set 'error_mode()' at the last minute, and then die, so the error mode is triggered. Other uses of error_mode() should continue to work as normal.

This module is intended to be use for simple query validation tasks, such as a link with query string with a small number of arguments or a page with a few dispatched args. For larger validation tasks, especially for processing form submissions using Data::FormValidator is recommended, along with CGI::Application::ValidateRM if you're using CGI::Application.

FUTURE

This concept could be extended to all check values set through $ENV{PATH_INFO}.

This plugin does not handle file upload validations, and won't in the future.

Providing untainting is not a goal of this module, but if it's easy and if someone else provides a patch, perhaps support will be added. Params::Validate provides untainting functionality and may be useful.

AUTHOR

Nate Smith nate@summersault.com, Mark Stosberg mark@summersault.com

BUGS & ISSUES

Please report any bugs or feature requests to bug-cgi-application-plugin-validatequery at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Application-Plugin-ValidateQuery. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT & LICENSE

Copyright 2009 Summersault, LLC., all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.