MojoX-Dispatcher-FilterChain/lib/MojoX/Dispatcher/FilterChain.pm

   1 package MojoX::Dispatcher::FilterChain;
   2
   3 use strict;
   4 use warnings;
   5
   6 use base 'Mojo::Base';
   7
   8 use MojoX::FilterChain::Constants;
   9
  10 our $VERSION = '0.03';
  11
  12 use constant DEBUG => $ENV{MOJOX_DISPATCHER_FILTERCHAIN_DEBUG} || 0;
  13
  14 __PACKAGE__->attr('filters', default => sub { [] });
  15
  16 sub add {
  17     my $self   = shift;
  18     my $filter = shift;
  19
  20     my $name = ref $filter;
  21     warn "Adding filter '$name'" if DEBUG;
  22
  23     push @{$self->filters}, $filter;
  24 }
  25
  26 sub process {
  27     my $self = shift;
  28
  29     foreach my $filter (@{$self->filters}) {
  30         my $name = ref $filter;
  31
  32         warn "Running '$name' filter" if DEBUG;
  33
  34         my $proceed = $filter->run(@_);
  35
  36         warn "Stop filter chain after '$name' filter"
  37           if DEBUG and $proceed == LAST;
  38
  39         last if $proceed == LAST;
  40     }
  41 }
  42
  43 1;
  44 __END__
  45
  46 =head1 NAME
  47
  48 MojoX::Dispatcher::FilterChain - Intercepting filter manager
  49
  50 =head1 SYNOPSIS
  51
  52     use MojoX::Dispatcher::FilterChain;
  53
  54     my $chain = MojoX::Dispatcher::FilterChain->new();
  55     $chain->add(LanguageDetect->new);
  56     $chain->add(Authorization->new);
  57     $chain->add(RenderView->new);
  58
  59     ...
  60
  61     $chain->process($c);
  62
  63 =head1 DESCRIPTION
  64
  65 L<MojoX::Dispatcher::FilterChain> is a intercepting filter manager pattern
  66 implementation.
  67
  68 Standart dispatch process can look like this:
  69
  70     sub dispatch {
  71         my ($self, $c) = @_;
  72
  73         # Try to find a static file
  74         $self->static->dispatch($c);
  75
  76         # Use routes if we don't have a response code yet
  77         $self->routes->dispatch($c) unless $c->res->code;
  78
  79         # Nothing found, serve static file "public/404.html"
  80         unless ($c->res->code) {
  81            #$self->static->serve($c, '/404.html');
  82            #$c->res->code(404);
  83         }
  84     }
  85
  86 Problem is that we have repetitive code that is checking whether to go to the
  87 next dispatcher or stop.
  88
  89 What we want to have is a list of independent filters that are called in
  90 specific order and one of them can intercept the chain.
  91
  92 Now we can rewrite our dispatch example.
  93
  94     __PACKAGE__->attr('chain',
  95         default => sub { MojoX::Dispatcher::FilterChain->new } );
  96
  97     sub dispatch {
  98         my ($self, $c) = @_;
  99
 100         # run filter chain
 101         $self->chain->process($c);
 102     }
 103
 104     sub startup {
 105         my $self = shift;
 106
 107         my $chain = $self->chain;
 108
 109         $chain->add(MyApp::FilterChain::StaticDispatch->new($c));
 110         $chain->add(MyApp::FilterChain::RoutesDispatch->new($c));
 111         $chain->add(MyApp::FilterChain::RenderView->new($c));
 112     }
 113
 114 Filter itself inherits L<MojoX::FilterChain::Base> and has method B<run> that
 115 is called when chain is processed. L<MojoX::FilterChain::Constants>
 116 module exports two self explaining constants B<NEXT> and B<LAST>. Depending on
 117 which value is returned after running current filter, chain proceeds or stops.
 118
 119 Regular filter can look like this:
 120
 121     package MyApp::FilterChain::Routes;
 122
 123     use strict;
 124     use warnings;
 125
 126     use base 'MojoX::FilterChain::Base';
 127
 128     # export LAST and NEXT constants
 129     use MojoX::FilterChain::Constants;
 130
 131     sub run {
 132         my ( $self, $c ) = @_;
 133
 134         $c->app->routes->dispatch($c);
 135
 136         return $c->res->code ? LAST : NEXT;
 137     }
 138
 139     1;
 140
 141 =head1 METHODS
 142
 143 L<MojoX::Dispatcher::FilterChain> inherits all methods from L<Mojo::Base> and
 144 implements the following the ones.
 145
 146 =head2 C<new>
 147
 148     my $chain = MojoX::Dispatcher::FilterChain->new;
 149
 150 =head2 C<add>
 151
 152     Add filter instance to filter chain.
 153
 154     my $chain->add(Filter->new);
 155
 156 =head2 C<process>
 157
 158     Run filter chain. Parameters provided will be passed on to every filter.
 159
 160     $chain->process($c);
 161
 162
 163 =head1 COPYRIGHT & LICENSE
 164
 165 Copyright 2008 Viacheslav Tikhanovskii, all rights reserved.
 166
 167 This program is free software; you can redistribute it and/or modify it
 168 under the same terms as Perl itself.
 169
 170 =cut
 171
 172 1;