# phpman > perldoc > CGI::Untaint

## NAME
    [CGI::Untaint](https://www.chedong.com/phpMan.php/perldoc/CGI%3A%3AUntaint/markdown) - process CGI input parameters

## SYNOPSIS
      use [CGI::Untaint](https://www.chedong.com/phpMan.php/perldoc/CGI%3A%3AUntaint/markdown);

      my $q = new CGI;
      my $handler = [CGI::Untaint](https://www.chedong.com/phpMan.php/perldoc/CGI%3A%3AUntaint/markdown)->new( $q->Vars );
      my $handler2 = [CGI::Untaint](https://www.chedong.com/phpMan.php/perldoc/CGI%3A%3AUntaint/markdown)->new({
            INCLUDE_PATH => '[My::Untaint](https://www.chedong.com/phpMan.php/perldoc/My%3A%3AUntaint/markdown)',
      }, $apr->parms);

      my $name     = $handler->extract(-as_printable => 'name');
      my $homepage = $handler->extract(-as_url => 'homepage');

      my $postcode = $handler->extract(-as_postcode => 'address6');

      # Create your own handler...

      package [MyRecipes::CGI::Untaint::legal_age](https://www.chedong.com/phpMan.php/perldoc/MyRecipes%3A%3ACGI%3A%3AUntaint%3A%3Alegalage/markdown);
      use base '[CGI::Untaint::integer](https://www.chedong.com/phpMan.php/perldoc/CGI%3A%3AUntaint%3A%3Ainteger/markdown)';
      sub is_valid {
        shift->value > 21;
      }

      package main;
      my $age = $handler->extract(-as_legal_age => 'age');

## DESCRIPTION
    Dealing with large web based applications with multiple forms is a minefield. It's often hard
    enough to ensure you validate all your input at all, without having to worry about doing it in a
    consistent manner. If any of the validation rules change, you often have to alter them in many
    different places. And, if you want to operate taint-safe, then you're just adding even more
    headaches.

    This module provides a simple, convenient, abstracted and extensible manner for validating and
    untainting the input from web forms.

    You simply create a handler with a hash of your parameters (usually $q->Vars), and then iterate
    over the fields you wish to extract, performing whatever validations you choose. The resulting
    variable is guaranteed not only to be valid, but also untainted.

## CONSTRUCTOR
  new
      my $handler  = [CGI::Untaint](https://www.chedong.com/phpMan.php/perldoc/CGI%3A%3AUntaint/markdown)->new( $q->Vars );
      my $handler2 = [CGI::Untaint](https://www.chedong.com/phpMan.php/perldoc/CGI%3A%3AUntaint/markdown)->new({
            INCLUDE_PATH => '[My::Untaint](https://www.chedong.com/phpMan.php/perldoc/My%3A%3AUntaint/markdown)',
      }, $apr->parms);

    The simplest way to contruct an input handler is to pass a hash of parameters (usually $q->Vars)
    to new(). Each parameter will then be able to be extracted later by calling an extract() method
    on it.

    However, you may also pass a leading reference to a hash of configuration variables.

    Currently the only such variable supported is 'INCLUDE_PATH', which allows you to specify a
    local path in which to find extraction handlers. See "LOCAL EXTRACTION HANDLERS".

## METHODS
  extract
      my $homepage = $handler->extract(-as_url => 'homepage');
      my $state = $handler->extract(-as_us_state => 'address4');
      my $state = $handler->extract(-as_like_us_state => 'address4');

    Once you have constructed your Input Handler, you call the 'extract' method on each piece of
    data with which you are concerned.

    The takes an -as_whatever flag to state what type of data you require. This will check that the
    input value correctly matches the required specification, and return an untainted value. It will
    then call the is_valid() method, where applicable, to ensure that this doesn't just _look_ like
    a valid value, but actually is one.

    If you want to skip this stage, then you can call -as_like_whatever which will perform the
    untainting but not the validation.

  error
      my $error = $handler->error;

    If the validation failed, this will return the reason why.

## LOCAL EXTRACTION HANDLERS
    As well as as the handlers supplied with this module for extracting data, you may also create
    your own. In general these should inherit from '[CGI::Untaint::object](https://www.chedong.com/phpMan.php/perldoc/CGI%3A%3AUntaint%3A%3Aobject/markdown)', and must provide an
    '_untaint_re' method which returns a compiled regular expression, suitably bracketed such that
    $1 will return the untainted value required.

    e.g. if you often extract single digit variables, you could create

      package [My::Untaint::digit](https://www.chedong.com/phpMan.php/perldoc/My%3A%3AUntaint%3A%3Adigit/markdown);

      use base '[CGI::Untaint::object](https://www.chedong.com/phpMan.php/perldoc/CGI%3A%3AUntaint%3A%3Aobject/markdown)';

      sub _untaint_re { qr/^(\d)$/ }

      1;

    You should specify the path '[My::Untaint](https://www.chedong.com/phpMan.php/perldoc/My%3A%3AUntaint/markdown)' in the INCLUDE_PATH configuration option. (See new()
    above.)

    When extract() is called [CGI::Untaint](https://www.chedong.com/phpMan.php/perldoc/CGI%3A%3AUntaint/markdown) will also check to see if you have an is_valid() method
    also, and if so will run this against the value extracted from the regular expression (available
    as $self->value).

    If this returns a true value, then the extracted value will be returned, otherwise we return
    undef.

### is_valid

    e.g. in the above example, if you sometimes need to ensure that the digit extracted is prime,
    you would supply:

      sub is_valid { (1 x shift->value) !~ /^1?$|^(11+?)\1+$/ };

    Now, when users call extract(), it will also check that the value is valid(), i.e. prime:

      my $number = $handler->extract(-as_digit => 'value');

    A user wishing to skip the validation, but still ensure untainting can call

      my $number = $handler->extract(-as_like_digit => 'value');

### [Test::CGI::Untaint](https://www.chedong.com/phpMan.php/perldoc/Test%3A%3ACGI%3A%3AUntaint/markdown)
    If you create your own local handlers, then you may wish to explore [Test::CGI::Untaint](https://www.chedong.com/phpMan.php/perldoc/Test%3A%3ACGI%3A%3AUntaint/markdown),
    available from the CPAN. This makes it very easy to write tests for your handler. (Thanks to
    Profero Ltd.)

## AVAILABLE HANDLERS
    This package comes with the following simplistic handlers:

      printable  - a printable string
      integer    - an integer
      hex        - a hexadecimal number (as a string)

    To really make this work for you you either need to write, or download from CPAN, other
    handlers. Some of the handlers available on CPAN include:

      asin         - an Amazon ID
      boolean      - boolean value
      country      - a country code or name
      creditcard   - a credit card number
      date         - a date (into a [Date::Simple](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3ASimple/markdown))
      datetime     - a date (into a DateTime)
      email        - an email address
      hostname     - a DNS host name
      html         - sanitized HTML
      ipaddress    - an IP address
      isbn         - an ISBN
      uk_postcode  - a UK Postcode
      url          - a URL
      zipcode      - a US zipcode

## BUGS
    None known yet.

## SEE ALSO
    CGI. perlsec. [Test::CGI::Untaint](https://www.chedong.com/phpMan.php/perldoc/Test%3A%3ACGI%3A%3AUntaint/markdown).

## AUTHOR
    Tony Bowden

BUGS and QUERIES
    Please direct all correspondence regarding this module to: <bug-CGI-Untaint@rt.cpan.org>

COPYRIGHT and LICENSE
    Copyright (C) 2001-2005 Tony Bowden. All rights reserved.

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