NAME

Dancer2::Plugin::ParamTypes - Parameter type checking plugin for Dancer2

VERSION

version 0.006

SYNOPSIS

package MyApp;
use Dancer2;
use Dancer2::Plugin::ParamTypes;

# First we define some type checks
# Read below for explanation
register_type_check 'Int' => sub {...};
register_type_check 'Str' => sub {...};

get '/:id' => with_types [
    # Required
    [ 'route', 'id',  'Int' ],
    [ 'query', 'num', 'Int' ],

    # Optional, either as query or body
    'optional' => [ [ 'query', 'body' ], 'name', 'Str' ],
] => sub {
    my $id  = route_parameters->{'id'};
    my @num = query_parameters->get_all('num');
    ...
};

# If we define our own action
register_type_action 'SpecialError' => sub {...};

# We can now use it in the type check
get '/' => with_types [
    [ 'query', 'id', 'Int', 'SpecialError' ]
] => sub {
    ...
};

DESCRIPTION

This is a simple module that allows you to provide a stanza of parameter type checks for your routes.

It supports all three possible sources: route, query, and body.

Currently no types are available in the system, so you will need to write your own code to add them. See the following methods below.

Methods

register_type_check

First you must register a type check, allowing you to test stuff:

register_type_check 'Int' => sub {
    return Scalar::Util::looks_like_number( $_[0] );
};

register_type_action

register_type_action 'MyError' => sub {
    my ( $self, $details ) = @_;

    my $source = $details->{'source'};
    my $name   = $details->{'name'};
    my $type   = $details->{'type'};
    my $action = $details->{'action'};

    send_error("Type check failed for $name ($type)");
}

with_types

with_types defines checks for parameters for a route request.

get '/:name' => with_types [

    # Basic usage
    [ SOURCE, NAME, TYPE ]

    # Provide a custom action
    [ SOURCE, NAME, TYPE, ACTION ]

    # Provide multiple sources (either one will work)
    [ [ SOURCE1, SOURCE2 ], NAME, TYPE ],

    # Optional type check
    # (if available will be checked, otherwise ignored)
    'optional' => [ SOURCE, NAME, TYPE ]

] => sub {
    ...
};

Above are all the options, but they will also work in any other combination.

Connecting existing type systems

Because each type check is a callback, you can connect these to other type systems:

register_type_check 'Str' => sub {
    require MooX::Types::MooseLike::Base;

    # This call will die when failing,
    # so we put it in an eval
    eval {
        MooX::Types::MooseLike::Base::Str->( $_[0] );
        1;
    } or return;

    return 1;
};

Creating your own pre-defined type checks

The following is a simple example of introducing a subclass of this plugin in order to create your own version with pre-defined checks.

package Dancer2::Plugin::MyParamTypes;
use strict;
use warnings;
use Dancer2::Plugin;

# subclass
extends('Dancer2::Plugin::ParamTypes');

# define our own plugin keyword
plugin_keywords('with_types');

# which simply calls the parent
sub with_types {
    my $self = shift;
    return $self->SUPER::with_types(@_);
}

sub BUILD {
    my $self = shift;

    # register our own type checks
    $self->register_type_check(
        'Int' => sub { Scalar::Util::looks_like_number( $_[0] ) },
    );
}

Later, the application can simply use this module:

package MyApp;
use Dancer2;
use Dancer2::Plugin::MyParamTypes;

get '/' => with_types [
    [ 'query', 'id', 'Int' ],
] => sub {...};

AUTHOR

Sawyer X

COPYRIGHT AND LICENSE

This software is Copyright (c) 2019 by Sawyer X.

This is free software, licensed under:

The MIT (X11) License

cpanm Dancer2::Plugin::ParamTypes

perl -MCPAN -e shell
install Dancer2::Plugin::ParamTypes