NAME

CatalystX::Controller::Verifier - Moose Role for verifying request parameters on a per action basis.

VERSION

version 0.02

SYNOPSIS

    package MyApp::Controller::Foo;

    use Moose;
    BEGIN { extends 'Catalyst::Controller'; }

    with 'CatalystX::Controller::Verifier';

    __PACKAGE__->config(
        'verifiers' => {
            # The action name
            'search' => {
                # Everything here gets passed to Data::Verifier->new for the scope
                filters => [ 'trim' ],
                # Just a plain Data::Verifier profile here:
                profile => {
                    page => {
                        type => 'Int',
                        post_check => sub { shift->get_value('page') > 0 }
                    },
                    query => {
                        type     => 'Str',
                        required => 1,
                    }
                }
            },
        },
        # Additional options can be passed in:
    
        # If verification fails, detach to the 'bad_args' action
        'detach_on_failure' => 'bad_args',
        
        # If you want to override where the Data::Manager objects get tucked away:
            '_verifier_stash_key' => 'a secret garden',
    );
    
    sub search : Local {
        my ( $self, $c ) = @_;
        my $results = $self->verify( $c );
     
        $c->model('Search')->search(
            # If invalid, it will be undef here.
            $results->get_value('page') || 1,
            $results->get_value('query')
        );
    }

If you run verify in an action that does not have a profile, this will throw an exception informing you of your transgressions.

But wait, there's more! Data::Verifier allows you to also define coercions.

ATTRIBUTES

verifiers

This stores the verifier configuration, which should be a hash ref of action names to verification profiles.

detach_on_failure

This attribute is used to instruct the verify method to detach to the action specified. If this is unset, no detaching happens.

METHODS

verify

    $self->verify($c);

The heart of the action, the verify method takes the current context object and verifies based on the profiles supplied in the configuration. If the detach_on_failure attribute is set, it will detach on an unsuccessful verification.

Returns a Data::Verifier::Results object. Note that this can be serialized and tucked away in the flash for later use.

messages

    $self->messages($c);

Returns a Message::Stack for the action in question (after verification).

data_manager

    $self->data_manager($c);

Returns a Data::Manager object that is used for this request (specific to the controller and the request).

COERCE YOUR PARAMETERS

So, in the above example lets say you wanted to parse your search query using Search::Query. Piece of cake!

    use Search::Query;
    
    __PACKAGE__->config(
        'verifiers' => {
            # The action name
            'search' => {
                # ... include the rest from synopsis ...
                query => {
                    type     => 'Search::Query',
                    required => 1,
                    coercion => Data::Verifier::coercion(
                        from => 'Str',
                        via  => sub { Search::Query->parser->parse($_) }
                    )
                }
            },
        }
    );
    
    sub search : Local {
        my ( $self, $c ) = @_;

        my $results = $self->verify( $c );
     
        $results->get_value('query');          # isa Search::Query object now!
        $results->get_original_value('query'); # Still valid
    }

MESSAGES

Got a validation error? Well, Data::Manager covers that, too.

The messages method will return a Message::Stack specific to that action.

    sub search : Local {
        my ( $self, $c ) = @_;
    
        my $results = $self->verify($c);
        unless ( $results->success ) {
            # Returns a Message::Stack for the action in question
            $self->messages($c);
        
            # You can also get the Data::Manager object 
            $self->data_manager($c);

        }
    }

LIFECYCLE

Each controller gets its own Data::Manager per request. This is probably not blindly fast. It lives in the stash

AUTHOR

J. Shirley <jshirley@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Cold Hard Code, LLC.

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

cpanm CatalystX::Controller::Verifier

perl -MCPAN -e shell
install CatalystX::Controller::Verifier