J. Shirley > CatalystX-Controller-Verifier-0.02 > CatalystX::Controller::Verifier

Download:
CatalystX-Controller-Verifier-0.02.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.02   Source  

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.

syntax highlighting: