4 use Moose::Meta::Class ();
5 extends 'Catalyst::Component';
6 use Moose::Util qw/find_meta/;
7 use B::Hooks::EndOfScope ();
8 use Catalyst::Exception;
9 use Catalyst::Exception::Detach;
10 use Catalyst::Exception::Go;
12 use Catalyst::Request;
13 use Catalyst::Request::Upload;
14 use Catalyst::Response;
16 use Catalyst::Controller;
17 use Devel::InnerPackage ();
19 use Module::Pluggable::Object ();
20 use Text::SimpleTable ();
21 use Path::Class::Dir ();
22 use Path::Class::File ();
26 use Tree::Simple qw/use_weak_refs/;
27 use Tree::Simple::Visitor::FindByUID;
28 use Class::C3::Adopt::NEXT;
29 use List::MoreUtils qw/uniq/;
32 use Carp qw/croak carp shortmess/;
34 BEGIN { require 5.008004; }
36 has stack => (is => 'ro', default => sub { [] });
37 has stash => (is => 'rw', default => sub { {} });
38 has state => (is => 'rw', default => 0);
39 has stats => (is => 'rw');
40 has action => (is => 'rw');
41 has counter => (is => 'rw', default => sub { {} });
42 has request => (is => 'rw', default => sub { $_[0]->request_class->new({}) }, required => 1, lazy => 1);
43 has response => (is => 'rw', default => sub { $_[0]->response_class->new({}) }, required => 1, lazy => 1);
44 has namespace => (is => 'rw');
46 sub depth { scalar @{ shift->stack || [] }; }
47 sub comp { shift->component(@_) }
50 my $self = shift; return $self->request(@_);
53 my $self = shift; return $self->response(@_);
56 # For backwards compatibility
57 sub finalize_output { shift->finalize_body(@_) };
62 our $RECURSION = 1000;
63 our $DETACH = Catalyst::Exception::Detach->new;
64 our $GO = Catalyst::Exception::Go->new;
66 #I imagine that very few of these really need to be class variables. if any.
67 #maybe we should just make them attributes with a default?
68 __PACKAGE__->mk_classdata($_)
69 for qw/components arguments dispatcher engine log dispatcher_class
70 engine_class context_class request_class response_class stats_class
73 __PACKAGE__->dispatcher_class('Catalyst::Dispatcher');
74 __PACKAGE__->engine_class('Catalyst::Engine::CGI');
75 __PACKAGE__->request_class('Catalyst::Request');
76 __PACKAGE__->response_class('Catalyst::Response');
77 __PACKAGE__->stats_class('Catalyst::Stats');
79 # Remember to update this in Catalyst::Runtime as well!
81 our $VERSION = '5.80022';
84 my ( $class, @arguments ) = @_;
86 # We have to limit $class to Catalyst to avoid pushing Catalyst upon every
88 return unless $class eq 'Catalyst';
90 my $caller = caller();
91 return if $caller eq 'main';
93 my $meta = Moose::Meta::Class->initialize($caller);
94 unless ( $caller->isa('Catalyst') ) {
95 my @superclasses = ($meta->superclasses, $class, 'Catalyst::Controller');
96 $meta->superclasses(@superclasses);
98 # Avoid possible C3 issues if 'Moose::Object' is already on RHS of MyApp
99 $meta->superclasses(grep { $_ ne 'Moose::Object' } $meta->superclasses);
101 unless( $meta->has_method('meta') ){
102 $meta->add_method(meta => sub { Moose::Meta::Class->initialize("${caller}") } );
105 $caller->arguments( [@arguments] );
109 sub _application { $_[0] }
113 Catalyst - The Elegant MVC Web Application Framework
117 See the L<Catalyst::Manual> distribution for comprehensive
118 documentation and tutorials.
120 # Install Catalyst::Devel for helpers and other development tools
121 # use the helper to create a new application
124 # add models, views, controllers
125 script/myapp_create.pl model MyDatabase DBIC::Schema create=static dbi:SQLite:/path/to/db
126 script/myapp_create.pl view MyTemplate TT
127 script/myapp_create.pl controller Search
129 # built in testserver -- use -r to restart automatically on changes
130 # --help to see all available options
131 script/myapp_server.pl
133 # command line testing interface
134 script/myapp_test.pl /yada
137 use Catalyst qw/-Debug/; # include plugins here as well
139 ### In lib/MyApp/Controller/Root.pm (autocreated)
140 sub foo : Global { # called for /foo, /foo/1, /foo/1/2, etc.
141 my ( $self, $c, @args ) = @_; # args are qw/1 2/ for /foo/1/2
142 $c->stash->{template} = 'foo.tt'; # set the template
143 # lookup something from db -- stash vars are passed to TT
145 $c->model('Database::Foo')->search( { country => $args[0] } );
146 if ( $c->req->params->{bar} ) { # access GET or POST parameters
147 $c->forward( 'bar' ); # process another action
148 # do something else after forward returns
152 # The foo.tt TT template can use the stash data from the database
153 [% WHILE (item = data.next) %]
157 # called for /bar/of/soap, /bar/of/soap/10, etc.
158 sub bar : Path('/bar/of/soap') { ... }
160 # called for all actions, from the top-most controller downwards
162 my ( $self, $c ) = @_;
163 if ( !$c->user_exists ) { # Catalyst::Plugin::Authentication
164 $c->res->redirect( '/login' ); # require login
165 return 0; # abort request and go immediately to end()
167 return 1; # success; carry on to next action
170 # called after all actions are finished
172 my ( $self, $c ) = @_;
173 if ( scalar @{ $c->error } ) { ... } # handle errors
174 return if $c->res->body; # already have a response
175 $c->forward( 'MyApp::View::TT' ); # render template
178 ### in MyApp/Controller/Foo.pm
179 # called for /foo/bar
180 sub bar : Local { ... }
182 # called for /blargle
183 sub blargle : Global { ... }
185 # an index action matches /foo, but not /foo/1, etc.
186 sub index : Private { ... }
188 ### in MyApp/Controller/Foo/Bar.pm
189 # called for /foo/bar/baz
190 sub baz : Local { ... }
192 # first Root auto is called, then Foo auto, then this
193 sub auto : Private { ... }
195 # powerful regular expression paths are also possible
196 sub details : Regex('^product/(\w+)/details$') {
197 my ( $self, $c ) = @_;
198 # extract the (\w+) from the URI
199 my $product = $c->req->captures->[0];
202 See L<Catalyst::Manual::Intro> for additional information.
206 Catalyst is a modern framework for making web applications without the
207 pain usually associated with this process. This document is a reference
208 to the main Catalyst application. If you are a new user, we suggest you
209 start with L<Catalyst::Manual::Tutorial> or L<Catalyst::Manual::Intro>.
211 See L<Catalyst::Manual> for more documentation.
213 Catalyst plugins can be loaded by naming them as arguments to the "use
214 Catalyst" statement. Omit the C<Catalyst::Plugin::> prefix from the
215 plugin name, i.e., C<Catalyst::Plugin::My::Module> becomes
218 use Catalyst qw/My::Module/;
220 If your plugin starts with a name other than C<Catalyst::Plugin::>, you can
221 fully qualify the name by using a unary plus:
225 +Fully::Qualified::Plugin::Name
228 Special flags like C<-Debug> and C<-Engine> can also be specified as
229 arguments when Catalyst is loaded:
231 use Catalyst qw/-Debug My::Module/;
233 The position of plugins and flags in the chain is important, because
234 they are loaded in the order in which they appear.
236 The following flags are supported:
240 Enables debug output. You can also force this setting from the system
241 environment with CATALYST_DEBUG or <MYAPP>_DEBUG. The environment
242 settings override the application, with <MYAPP>_DEBUG having the highest
245 This sets the log level to 'debug' and enables full debug output on the
246 error screen. If you only want the latter, see L<< $c->debug >>.
250 Forces Catalyst to use a specific engine. Omit the
251 C<Catalyst::Engine::> prefix of the engine name, i.e.:
253 use Catalyst qw/-Engine=CGI/;
257 Forces Catalyst to use a specific home directory, e.g.:
259 use Catalyst qw[-Home=/usr/mst];
261 This can also be done in the shell environment by setting either the
262 C<CATALYST_HOME> environment variable or C<MYAPP_HOME>; where C<MYAPP>
263 is replaced with the uppercased name of your application, any "::" in
264 the name will be replaced with underscores, e.g. MyApp::Web should use
265 MYAPP_WEB_HOME. If both variables are set, the MYAPP_HOME one will be used.
267 If none of these are set, Catalyst will attempt to automatically detect the
268 home directory. If you are working in a development envirnoment, Catalyst
269 will try and find the directory containing either Makefile.PL, Build.PL or
270 dist.ini. If the application has been installed into the system (i.e.
271 you have done C<make install>), then Catalyst will use the path to your
272 application module, without the .pm extension (ie, /foo/MyApp if your
273 application was installed at /foo/MyApp.pm)
277 use Catalyst '-Log=warn,fatal,error';
279 Specifies a comma-delimited list of log levels.
283 Enables statistics collection and reporting. You can also force this setting
284 from the system environment with CATALYST_STATS or <MYAPP>_STATS. The
285 environment settings override the application, with <MYAPP>_STATS having the
290 use Catalyst qw/-Stats=1/
294 =head2 INFORMATION ABOUT THE CURRENT REQUEST
298 Returns a L<Catalyst::Action> object for the current action, which
299 stringifies to the action name. See L<Catalyst::Action>.
303 Returns the namespace of the current action, i.e., the URI prefix
304 corresponding to the controller of the current action. For example:
306 # in Controller::Foo::Bar
307 $c->namespace; # returns 'foo/bar';
313 Returns the current L<Catalyst::Request> object, giving access to
314 information about the current client request (including parameters,
315 cookies, HTTP headers, etc.). See L<Catalyst::Request>.
317 =head2 REQUEST FLOW HANDLING
319 =head2 $c->forward( $action [, \@arguments ] )
321 =head2 $c->forward( $class, $method, [, \@arguments ] )
323 Forwards processing to another action, by its private name. If you give a
324 class name but no method, C<process()> is called. You may also optionally
325 pass arguments in an arrayref. The action will receive the arguments in
326 C<@_> and C<< $c->req->args >>. Upon returning from the function,
327 C<< $c->req->args >> will be restored to the previous values.
329 Any data C<return>ed from the action forwarded to, will be returned by the
332 my $foodata = $c->forward('/foo');
333 $c->forward('index');
334 $c->forward(qw/Model::DBIC::Foo do_stuff/);
335 $c->forward('View::TT');
337 Note that L<< forward|/"$c->forward( $action [, \@arguments ] )" >> implies
338 an C<< eval { } >> around the call (actually
339 L<< execute|/"$c->execute( $class, $coderef )" >> does), thus de-fatalizing
340 all 'dies' within the called action. If you want C<die> to propagate you
341 need to do something like:
344 die join "\n", @{ $c->error } if @{ $c->error };
346 Or make sure to always return true values from your actions and write
349 $c->forward('foo') || return;
351 Another note is that C<< $c->forward >> always returns a scalar because it
352 actually returns $c->state which operates in a scalar context.
353 Thus, something like:
357 in an action that is forwarded to is going to return a scalar,
358 i.e. how many items are in that array, which is probably not what you want.
359 If you need to return an array then return a reference to it,
362 $c->stash->{array} = \@array;
364 and access it from the stash.
368 sub forward { my $c = shift; no warnings 'recursion'; $c->dispatcher->forward( $c, @_ ) }
370 =head2 $c->detach( $action [, \@arguments ] )
372 =head2 $c->detach( $class, $method, [, \@arguments ] )
376 The same as L<< forward|/"$c->forward( $action [, \@arguments ] )" >>, but
377 doesn't return to the previous action when processing is finished.
379 When called with no arguments it escapes the processing chain entirely.
383 sub detach { my $c = shift; $c->dispatcher->detach( $c, @_ ) }
385 =head2 $c->visit( $action [, \@captures, \@arguments ] )
387 =head2 $c->visit( $class, $method, [, \@captures, \@arguments ] )
389 Almost the same as L<< forward|/"$c->forward( $action [, \@arguments ] )" >>,
390 but does a full dispatch, instead of just calling the new C<$action> /
391 C<< $class->$method >>. This means that C<begin>, C<auto> and the method
392 you go to are called, just like a new request.
394 In addition both C<< $c->action >> and C<< $c->namespace >> are localized.
395 This means, for example, that C<< $c->action >> methods such as
396 L<name|Catalyst::Action/name>, L<class|Catalyst::Action/class> and
397 L<reverse|Catalyst::Action/reverse> return information for the visited action
398 when they are invoked within the visited action. This is different from the
399 behavior of L<< forward|/"$c->forward( $action [, \@arguments ] )" >>, which
400 continues to use the $c->action object from the caller action even when
401 invoked from the callee.
403 C<< $c->stash >> is kept unchanged.
405 In effect, L<< visit|/"$c->visit( $action [, \@captures, \@arguments ] )" >>
406 allows you to "wrap" another action, just as it would have been called by
407 dispatching from a URL, while the analogous
408 L<< go|/"$c->go( $action [, \@captures, \@arguments ] )" >> allows you to
409 transfer control to another action as if it had been reached directly from a URL.
413 sub visit { my $c = shift; $c->dispatcher->visit( $c, @_ ) }
415 =head2 $c->go( $action [, \@captures, \@arguments ] )
417 =head2 $c->go( $class, $method, [, \@captures, \@arguments ] )
419 The relationship between C<go> and
420 L<< visit|/"$c->visit( $action [, \@captures, \@arguments ] )" >> is the same as
421 the relationship between
422 L<< forward|/"$c->forward( $class, $method, [, \@arguments ] )" >> and
423 L<< detach|/"$c->detach( $action [, \@arguments ] )" >>. Like C<< $c->visit >>,
424 C<< $c->go >> will perform a full dispatch on the specified action or method,
425 with localized C<< $c->action >> and C<< $c->namespace >>. Like C<detach>,
426 C<go> escapes the processing of the current request chain on completion, and
427 does not return to its caller.
431 sub go { my $c = shift; $c->dispatcher->go( $c, @_ ) }
437 Returns the current L<Catalyst::Response> object, see there for details.
441 Returns a hashref to the stash, which may be used to store data and pass
442 it between components during a request. You can also set hash keys by
443 passing arguments. The stash is automatically sent to the view. The
444 stash is cleared at the end of a request; it cannot be used for
445 persistent storage (for this you must use a session; see
446 L<Catalyst::Plugin::Session> for a complete system integrated with
449 $c->stash->{foo} = $bar;
450 $c->stash( { moose => 'majestic', qux => 0 } );
451 $c->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref
453 # stash is automatically passed to the view for use in a template
454 $c->forward( 'MyApp::View::TT' );
458 around stash => sub {
461 my $stash = $orig->($c);
463 my $new_stash = @_ > 1 ? {@_} : $_[0];
464 croak('stash takes a hash or hashref') unless ref $new_stash;
465 foreach my $key ( keys %$new_stash ) {
466 $stash->{$key} = $new_stash->{$key};
476 =head2 $c->error($error, ...)
478 =head2 $c->error($arrayref)
480 Returns an arrayref containing error messages. If Catalyst encounters an
481 error while processing a request, it stores the error in $c->error. This
482 method should only be used to store fatal error messages.
484 my @error = @{ $c->error };
488 $c->error('Something bad happened');
495 my $error = ref $_[0] eq 'ARRAY' ? $_[0] : [@_];
496 croak @$error unless ref $c;
497 push @{ $c->{error} }, @$error;
499 elsif ( defined $_[0] ) { $c->{error} = undef }
500 return $c->{error} || [];
506 Contains the return value of the last executed action.
507 Note that << $c->state >> operates in a scalar context which means that all
508 values it returns are scalar.
510 =head2 $c->clear_errors
512 Clear errors. You probably don't want to clear the errors unless you are
513 implementing a custom error screen.
515 This is equivalent to running
526 sub _comp_search_prefixes {
528 return map $c->components->{ $_ }, $c->_comp_names_search_prefixes(@_);
531 # search components given a name and some prefixes
532 sub _comp_names_search_prefixes {
533 my ( $c, $name, @prefixes ) = @_;
534 my $appclass = ref $c || $c;
535 my $filter = "^${appclass}::(" . join( '|', @prefixes ) . ')::';
536 $filter = qr/$filter/; # Compile regex now rather than once per loop
538 # map the original component name to the sub part that we will search against
539 my %eligible = map { my $n = $_; $n =~ s{^$appclass\::[^:]+::}{}; $_ => $n; }
540 grep { /$filter/ } keys %{ $c->components };
542 # undef for a name will return all
543 return keys %eligible if !defined $name;
545 my $query = ref $name ? $name : qr/^$name$/i;
546 my @result = grep { $eligible{$_} =~ m{$query} } keys %eligible;
548 return @result if @result;
550 # if we were given a regexp to search against, we're done.
553 # skip regexp fallback if configured
555 if $appclass->config->{disable_component_resolution_regex_fallback};
559 @result = grep { $eligible{ $_ } =~ m{$query} } keys %eligible;
561 # no results? try against full names
563 @result = grep { m{$query} } keys %eligible;
566 # don't warn if we didn't find any results, it just might not exist
568 # Disgusting hack to work out correct method name
569 my $warn_for = lc $prefixes[0];
570 my $msg = "Used regexp fallback for \$c->${warn_for}('${name}'), which found '" .
571 (join '", "', @result) . "'. Relying on regexp fallback behavior for " .
572 "component resolution is unreliable and unsafe.";
573 my $short = $result[0];
574 # remove the component namespace prefix
575 $short =~ s/.*?(Model|Controller|View):://;
576 my $shortmess = Carp::shortmess('');
577 if ($shortmess =~ m#Catalyst/Plugin#) {
578 $msg .= " You probably need to set '$short' instead of '${name}' in this " .
580 } elsif ($shortmess =~ m#Catalyst/lib/(View|Controller)#) {
581 $msg .= " You probably need to set '$short' instead of '${name}' in this " .
582 "component's config";
584 $msg .= " You probably meant \$c->${warn_for}('$short') instead of \$c->${warn_for}('${name}'), " .
585 "but if you really wanted to search, pass in a regexp as the argument " .
586 "like so: \$c->${warn_for}(qr/${name}/)";
588 $c->log->warn( "${msg}$shortmess" );
594 # Find possible names for a prefix
596 my ( $c, @prefixes ) = @_;
597 my $appclass = ref $c || $c;
599 my $filter = "^${appclass}::(" . join( '|', @prefixes ) . ')::';
601 my @names = map { s{$filter}{}; $_; }
602 $c->_comp_names_search_prefixes( undef, @prefixes );
607 # Filter a component before returning by calling ACCEPT_CONTEXT if available
608 sub _filter_component {
609 my ( $c, $comp, @args ) = @_;
611 if ( eval { $comp->can('ACCEPT_CONTEXT'); } ) {
612 return $comp->ACCEPT_CONTEXT( $c, @args );
618 =head2 COMPONENT ACCESSORS
620 =head2 $c->controller($name)
622 Gets a L<Catalyst::Controller> instance by name.
624 $c->controller('Foo')->do_stuff;
626 If the name is omitted, will return the controller for the dispatched
629 If you want to search for controllers, pass in a regexp as the argument.
631 # find all controllers that start with Foo
632 my @foo_controllers = $c->controller(qr{^Foo});
638 my ( $c, $name, @args ) = @_;
640 my $appclass = ref($c) || $c;
642 unless ( ref($name) ) { # Direct component hash lookup to avoid costly regexps
643 my $comps = $c->components;
644 my $check = $appclass."::Controller::".$name;
645 return $c->_filter_component( $comps->{$check}, @args ) if exists $comps->{$check};
647 my @result = $c->_comp_search_prefixes( $name, qw/Controller C/ );
648 return map { $c->_filter_component( $_, @args ) } @result if ref $name;
649 return $c->_filter_component( $result[ 0 ], @args );
652 return $c->component( $c->action->class );
655 =head2 $c->model($name)
657 Gets a L<Catalyst::Model> instance by name.
659 $c->model('Foo')->do_stuff;
661 Any extra arguments are directly passed to ACCEPT_CONTEXT.
663 If the name is omitted, it will look for
664 - a model object in $c->stash->{current_model_instance}, then
665 - a model name in $c->stash->{current_model}, then
666 - a config setting 'default_model', or
667 - check if there is only one model, and return it if that's the case.
669 If you want to search for models, pass in a regexp as the argument.
671 # find all models that start with Foo
672 my @foo_models = $c->model(qr{^Foo});
677 my ( $c, $name, @args ) = @_;
678 my $appclass = ref($c) || $c;
680 unless ( ref($name) ) { # Direct component hash lookup to avoid costly regexps
681 my $comps = $c->components;
682 my $check = $appclass."::Model::".$name;
683 return $c->_filter_component( $comps->{$check}, @args ) if exists $comps->{$check};
685 my @result = $c->_comp_search_prefixes( $name, qw/Model M/ );
686 return map { $c->_filter_component( $_, @args ) } @result if ref $name;
687 return $c->_filter_component( $result[ 0 ], @args );
691 return $c->stash->{current_model_instance}
692 if $c->stash->{current_model_instance};
693 return $c->model( $c->stash->{current_model} )
694 if $c->stash->{current_model};
696 return $c->model( $appclass->config->{default_model} )
697 if $appclass->config->{default_model};
699 my( $comp, $rest ) = $c->_comp_search_prefixes( undef, qw/Model M/);
702 $c->log->warn( Carp::shortmess('Calling $c->model() will return a random model unless you specify one of:') );
703 $c->log->warn( '* $c->config(default_model => "the name of the default model to use")' );
704 $c->log->warn( '* $c->stash->{current_model} # the name of the model to use for this request' );
705 $c->log->warn( '* $c->stash->{current_model_instance} # the instance of the model to use for this request' );
706 $c->log->warn( 'NB: in version 5.81, the "random" behavior will not work at all.' );
709 return $c->_filter_component( $comp );
713 =head2 $c->view($name)
715 Gets a L<Catalyst::View> instance by name.
717 $c->view('Foo')->do_stuff;
719 Any extra arguments are directly passed to ACCEPT_CONTEXT.
721 If the name is omitted, it will look for
722 - a view object in $c->stash->{current_view_instance}, then
723 - a view name in $c->stash->{current_view}, then
724 - a config setting 'default_view', or
725 - check if there is only one view, and return it if that's the case.
727 If you want to search for views, pass in a regexp as the argument.
729 # find all views that start with Foo
730 my @foo_views = $c->view(qr{^Foo});
735 my ( $c, $name, @args ) = @_;
737 my $appclass = ref($c) || $c;
739 unless ( ref($name) ) { # Direct component hash lookup to avoid costly regexps
740 my $comps = $c->components;
741 my $check = $appclass."::View::".$name;
742 return $c->_filter_component( $comps->{$check}, @args ) if exists $comps->{$check};
744 my @result = $c->_comp_search_prefixes( $name, qw/View V/ );
745 return map { $c->_filter_component( $_, @args ) } @result if ref $name;
746 return $c->_filter_component( $result[ 0 ], @args );
750 return $c->stash->{current_view_instance}
751 if $c->stash->{current_view_instance};
752 return $c->view( $c->stash->{current_view} )
753 if $c->stash->{current_view};
755 return $c->view( $appclass->config->{default_view} )
756 if $appclass->config->{default_view};
758 my( $comp, $rest ) = $c->_comp_search_prefixes( undef, qw/View V/);
761 $c->log->warn( 'Calling $c->view() will return a random view unless you specify one of:' );
762 $c->log->warn( '* $c->config(default_view => "the name of the default view to use")' );
763 $c->log->warn( '* $c->stash->{current_view} # the name of the view to use for this request' );
764 $c->log->warn( '* $c->stash->{current_view_instance} # the instance of the view to use for this request' );
765 $c->log->warn( 'NB: in version 5.81, the "random" behavior will not work at all.' );
768 return $c->_filter_component( $comp );
771 =head2 $c->controllers
773 Returns the available names which can be passed to $c->controller
779 return $c->_comp_names(qw/Controller C/);
784 Returns the available names which can be passed to $c->model
790 return $c->_comp_names(qw/Model M/);
796 Returns the available names which can be passed to $c->view
802 return $c->_comp_names(qw/View V/);
805 =head2 $c->comp($name)
807 =head2 $c->component($name)
809 Gets a component object by name. This method is not recommended,
810 unless you want to get a specific component by full
811 class. C<< $c->controller >>, C<< $c->model >>, and C<< $c->view >>
812 should be used instead.
814 If C<$name> is a regexp, a list of components matched against the full
815 component name will be returned.
817 If Catalyst can't find a component by name, it will fallback to regex
818 matching by default. To disable this behaviour set
819 disable_component_resolution_regex_fallback to a true value.
821 __PACKAGE__->config( disable_component_resolution_regex_fallback => 1 );
826 my ( $c, $name, @args ) = @_;
829 my $comps = $c->components;
832 # is it the exact name?
833 return $c->_filter_component( $comps->{ $name }, @args )
834 if exists $comps->{ $name };
836 # perhaps we just omitted "MyApp"?
837 my $composed = ( ref $c || $c ) . "::${name}";
838 return $c->_filter_component( $comps->{ $composed }, @args )
839 if exists $comps->{ $composed };
841 # search all of the models, views and controllers
842 my( $comp ) = $c->_comp_search_prefixes( $name, qw/Model M Controller C View V/ );
843 return $c->_filter_component( $comp, @args ) if $comp;
846 # This is here so $c->comp( '::M::' ) works
847 my $query = ref $name ? $name : qr{$name}i;
849 my @result = grep { m{$query} } keys %{ $c->components };
850 return map { $c->_filter_component( $_, @args ) } @result if ref $name;
853 $c->log->warn( Carp::shortmess(qq(Found results for "${name}" using regexp fallback)) );
854 $c->log->warn( 'Relying on the regexp fallback behavior for component resolution' );
855 $c->log->warn( 'is unreliable and unsafe. You have been warned' );
856 return $c->_filter_component( $result[ 0 ], @args );
859 # I would expect to return an empty list here, but that breaks back-compat
863 return sort keys %{ $c->components };
866 =head2 CLASS DATA AND HELPER CLASSES
870 Returns or takes a hashref containing the application's configuration.
872 __PACKAGE__->config( { db => 'dsn:SQLite:foo.db' } );
874 You can also use a C<YAML>, C<XML> or L<Config::General> config file
875 like C<myapp.conf> in your applications home directory. See
876 L<Catalyst::Plugin::ConfigLoader>.
878 =head3 Cascading configuration
880 The config method is present on all Catalyst components, and configuration
881 will be merged when an application is started. Configuration loaded with
882 L<Catalyst::Plugin::ConfigLoader> takes precedence over other configuration,
883 followed by configuration in your top level C<MyApp> class. These two
884 configurations are merged, and then configuration data whose hash key matches a
885 component name is merged with configuration for that component.
887 The configuration for a component is then passed to the C<new> method when a
888 component is constructed.
892 MyApp->config({ 'Model::Foo' => { bar => 'baz', overrides => 'me' } });
893 MyApp::Model::Foo->config({ quux => 'frob', 'overrides => 'this' });
895 will mean that C<MyApp::Model::Foo> receives the following data when
898 MyApp::Model::Foo->new({
906 around config => sub {
910 croak('Setting config after setup has been run is not allowed.')
911 if ( @_ and $c->setup_finished );
918 Returns the logging object instance. Unless it is already set, Catalyst
919 sets this up with a L<Catalyst::Log> object. To use your own log class,
920 set the logger with the C<< __PACKAGE__->log >> method prior to calling
921 C<< __PACKAGE__->setup >>.
923 __PACKAGE__->log( MyLogger->new );
928 $c->log->info( 'Now logging with my own logger!' );
930 Your log class should implement the methods described in
936 Returns 1 if debug mode is enabled, 0 otherwise.
938 You can enable debug mode in several ways:
942 =item By calling myapp_server.pl with the -d flag
944 =item With the environment variables MYAPP_DEBUG, or CATALYST_DEBUG
946 =item The -Debug option in your MyApp.pm
948 =item By declaring C<sub debug { 1 }> in your MyApp.pm.
952 The first three also set the log level to 'debug'.
954 Calling C<< $c->debug(1) >> has no effect.
960 =head2 $c->dispatcher
962 Returns the dispatcher instance. See L<Catalyst::Dispatcher>.
966 Returns the engine instance. See L<Catalyst::Engine>.
969 =head2 UTILITY METHODS
971 =head2 $c->path_to(@path)
973 Merges C<@path> with C<< $c->config->{home} >> and returns a
974 L<Path::Class::Dir> object. Note you can usually use this object as
975 a filename, but sometimes you will have to explicitly stringify it
976 yourself by calling the C<< ->stringify >> method.
980 $c->path_to( 'db', 'sqlite.db' );
985 my ( $c, @path ) = @_;
986 my $path = Path::Class::Dir->new( $c->config->{home}, @path );
987 if ( -d $path ) { return $path }
988 else { return Path::Class::File->new( $c->config->{home}, @path ) }
991 =head2 $c->plugin( $name, $class, @args )
993 Helper method for plugins. It creates a class data accessor/mutator and
994 loads and instantiates the given class.
996 MyApp->plugin( 'prototype', 'HTML::Prototype' );
998 $c->prototype->define_javascript_functions;
1000 B<Note:> This method of adding plugins is deprecated. The ability
1001 to add plugins like this B<will be removed> in a Catalyst 5.81.
1002 Please do not use this functionality in new code.
1007 my ( $class, $name, $plugin, @args ) = @_;
1009 # See block comment in t/unit_core_plugin.t
1010 $class->log->warn(qq/Adding plugin using the ->plugin method is deprecated, and will be removed in Catalyst 5.81/);
1012 $class->_register_plugin( $plugin, 1 );
1014 eval { $plugin->import };
1015 $class->mk_classdata($name);
1017 eval { $obj = $plugin->new(@args) };
1020 Catalyst::Exception->throw( message =>
1021 qq/Couldn't instantiate instant plugin "$plugin", "$@"/ );
1024 $class->$name($obj);
1025 $class->log->debug(qq/Initialized instant plugin "$plugin" as "$name"/)
1031 Initializes the dispatcher and engine, loads any plugins, and loads the
1032 model, view, and controller components. You may also specify an array
1033 of plugins to load here, if you choose to not load them in the C<use
1037 MyApp->setup( qw/-Debug/ );
1042 my ( $class, @arguments ) = @_;
1043 croak('Running setup more than once')
1044 if ( $class->setup_finished );
1046 unless ( $class->isa('Catalyst') ) {
1048 Catalyst::Exception->throw(
1049 message => qq/'$class' does not inherit from Catalyst/ );
1052 if ( $class->arguments ) {
1053 @arguments = ( @arguments, @{ $class->arguments } );
1059 foreach (@arguments) {
1063 ( $flags->{log} ) ? 'debug,' . $flags->{log} : 'debug';
1065 elsif (/^-(\w+)=?(.*)$/) {
1066 $flags->{ lc $1 } = $2;
1069 push @{ $flags->{plugins} }, $_;
1073 $class->setup_home( delete $flags->{home} );
1075 $class->setup_log( delete $flags->{log} );
1076 $class->setup_plugins( delete $flags->{plugins} );
1077 $class->setup_dispatcher( delete $flags->{dispatcher} );
1078 $class->setup_engine( delete $flags->{engine} );
1079 $class->setup_stats( delete $flags->{stats} );
1081 for my $flag ( sort keys %{$flags} ) {
1083 if ( my $code = $class->can( 'setup_' . $flag ) ) {
1084 &$code( $class, delete $flags->{$flag} );
1087 $class->log->warn(qq/Unknown flag "$flag"/);
1091 eval { require Catalyst::Devel; };
1092 if( !$@ && $ENV{CATALYST_SCRIPT_GEN} && ( $ENV{CATALYST_SCRIPT_GEN} < $Catalyst::Devel::CATALYST_SCRIPT_GEN ) ) {
1093 $class->log->warn(<<"EOF");
1094 You are running an old script!
1096 Please update by running (this will overwrite existing files):
1097 catalyst.pl -force -scripts $class
1099 or (this will not overwrite existing files):
1100 catalyst.pl -scripts $class
1105 if ( $class->debug ) {
1106 my @plugins = map { "$_ " . ( $_->VERSION || '' ) } $class->registered_plugins;
1109 my $column_width = Catalyst::Utils::term_width() - 6;
1110 my $t = Text::SimpleTable->new($column_width);
1111 $t->row($_) for @plugins;
1112 $class->log->debug( "Loaded plugins:\n" . $t->draw . "\n" );
1115 my $dispatcher = $class->dispatcher;
1116 my $engine = $class->engine;
1117 my $home = $class->config->{home};
1119 $class->log->debug(sprintf(q/Loaded dispatcher "%s"/, blessed($dispatcher)));
1120 $class->log->debug(sprintf(q/Loaded engine "%s"/, blessed($engine)));
1124 ? $class->log->debug(qq/Found home "$home"/)
1125 : $class->log->debug(qq/Home "$home" doesn't exist/)
1126 : $class->log->debug(q/Couldn't find home/);
1129 # Call plugins setup, this is stupid and evil.
1130 # Also screws C3 badly on 5.10, hack to avoid.
1132 no warnings qw/redefine/;
1133 local *setup = sub { };
1134 $class->setup unless $Catalyst::__AM_RESTARTING;
1137 # Initialize our data structure
1138 $class->components( {} );
1140 $class->setup_components;
1142 if ( $class->debug ) {
1143 my $column_width = Catalyst::Utils::term_width() - 8 - 9;
1144 my $t = Text::SimpleTable->new( [ $column_width, 'Class' ], [ 8, 'Type' ] );
1145 for my $comp ( sort keys %{ $class->components } ) {
1146 my $type = ref $class->components->{$comp} ? 'instance' : 'class';
1147 $t->row( $comp, $type );
1149 $class->log->debug( "Loaded components:\n" . $t->draw . "\n" )
1150 if ( keys %{ $class->components } );
1153 # Add our self to components, since we are also a component
1154 if( $class->isa('Catalyst::Controller') ){
1155 $class->components->{$class} = $class;
1158 $class->setup_actions;
1160 if ( $class->debug ) {
1161 my $name = $class->config->{name} || 'Application';
1162 $class->log->info("$name powered by Catalyst $Catalyst::VERSION");
1165 # Make sure that the application class becomes immutable at this point,
1166 B::Hooks::EndOfScope::on_scope_end {
1168 my $meta = Class::MOP::get_metaclass_by_name($class);
1171 && ! { $meta->immutable_options }->{replace_constructor}
1173 $class->isa('Class::Accessor::Fast')
1174 || $class->isa('Class::Accessor')
1177 warn "You made your application class ($class) immutable, "
1178 . "but did not inline the\nconstructor. "
1179 . "This will break catalyst, as your app \@ISA "
1180 . "Class::Accessor(::Fast)?\nPlease pass "
1181 . "(replace_constructor => 1)\nwhen making your class immutable.\n";
1183 $meta->make_immutable(
1184 replace_constructor => 1,
1185 ) unless $meta->is_immutable;
1188 if ($class->config->{case_sensitive}) {
1189 $class->log->warn($class . "->config->{case_sensitive} is set.");
1190 $class->log->warn("This setting is deprecated and planned to be removed in Catalyst 5.81.");
1193 $class->setup_finalize;
1194 # Should be the last thing we do so that user things hooking
1195 # setup_finalize can log..
1196 $class->log->_flush() if $class->log->can('_flush');
1197 return 1; # Explicit return true as people have __PACKAGE__->setup as the last thing in their class. HATE.
1200 =head2 $app->setup_finalize
1202 A hook to attach modifiers to. This method does not do anything except set the
1203 C<setup_finished> accessor.
1205 Applying method modifiers to the C<setup> method doesn't work, because of quirky thingsdone for plugin setup.
1209 after setup_finalize => sub {
1217 sub setup_finalize {
1219 $class->setup_finished(1);
1222 =head2 $c->uri_for( $path?, @args?, \%query_values? )
1224 =head2 $c->uri_for( $action, \@captures?, @args?, \%query_values? )
1226 Constructs an absolute L<URI> object based on the application root, the
1227 provided path, and the additional arguments and query parameters provided.
1228 When used as a string, provides a textual URI.
1230 If no arguments are provided, the URI for the current action is returned.
1231 To return the current action and also provide @args, use
1232 C<< $c->uri_for( $c->action, @args ) >>.
1234 If the first argument is a string, it is taken as a public URI path relative
1235 to C<< $c->namespace >> (if it doesn't begin with a forward slash) or
1236 relative to the application root (if it does). It is then merged with
1237 C<< $c->request->base >>; any C<@args> are appended as additional path
1238 components; and any C<%query_values> are appended as C<?foo=bar> parameters.
1240 If the first argument is a L<Catalyst::Action> it represents an action which
1241 will have its path resolved using C<< $c->dispatcher->uri_for_action >>. The
1242 optional C<\@captures> argument (an arrayref) allows passing the captured
1243 variables that are needed to fill in the paths of Chained and Regex actions;
1244 once the path is resolved, C<uri_for> continues as though a path was
1245 provided, appending any arguments or parameters and creating an absolute
1248 The captures for the current request can be found in
1249 C<< $c->request->captures >>, and actions can be resolved using
1250 C<< Catalyst::Controller->action_for($name) >>. If you have a private action
1251 path, use C<< $c->uri_for_action >> instead.
1253 # Equivalent to $c->req->uri
1254 $c->uri_for($c->action, $c->req->captures,
1255 @{ $c->req->args }, $c->req->params);
1257 # For the Foo action in the Bar controller
1258 $c->uri_for($c->controller('Bar')->action_for('Foo'));
1260 # Path to a static resource
1261 $c->uri_for('/static/images/logo.png');
1266 my ( $c, $path, @args ) = @_;
1268 if (blessed($path) && $path->isa('Catalyst::Controller')) {
1269 $path = $path->path_prefix;
1274 undef($path) if (defined $path && $path eq '');
1277 ( scalar @args && ref $args[$#args] eq 'HASH' ? pop @args : {} );
1279 carp "uri_for called with undef argument" if grep { ! defined $_ } @args;
1280 foreach my $arg (@args) {
1281 utf8::encode($arg) if utf8::is_utf8($arg);
1283 s/([^$URI::uric])/$URI::Escape::escapes{$1}/go for @args;
1284 if (blessed $path) { # Action object only.
1285 s|/|%2F|g for @args;
1288 if ( blessed($path) ) { # action object
1289 my $captures = [ map { s|/|%2F|g; $_; }
1290 ( scalar @args && ref $args[0] eq 'ARRAY'
1294 foreach my $capture (@$captures) {
1295 utf8::encode($capture) if utf8::is_utf8($capture);
1296 $capture =~ s/([^$URI::uric])/$URI::Escape::escapes{$1}/go;
1300 # ->uri_for( $action, \@captures_and_args, \%query_values? )
1301 if( !@args && $action->number_of_args ) {
1302 my $expanded_action = $c->dispatcher->expand_action( $action );
1304 my $num_captures = $expanded_action->number_of_captures;
1305 unshift @args, splice @$captures, $num_captures;
1308 $path = $c->dispatcher->uri_for_action($action, $captures);
1309 if (not defined $path) {
1310 $c->log->debug(qq/Can't find uri_for action '$action' @$captures/)
1314 $path = '/' if $path eq '';
1317 undef($path) if (defined $path && $path eq '');
1319 unshift(@args, $path);
1321 unless (defined $path && $path =~ s!^/!!) { # in-place strip
1322 my $namespace = $c->namespace;
1323 if (defined $path) { # cheesy hack to handle path '../foo'
1324 $namespace =~ s{(?:^|/)[^/]+$}{} while $args[0] =~ s{^\.\./}{};
1326 unshift(@args, $namespace || '');
1329 # join args with '/', or a blank string
1330 my $args = join('/', grep { defined($_) } @args);
1331 $args =~ s/\?/%3F/g; # STUPID STUPID SPECIAL CASE
1333 my $base = $c->req->base;
1334 my $class = ref($base);
1335 $base =~ s{(?<!/)$}{/};
1339 if (my @keys = keys %$params) {
1340 # somewhat lifted from URI::_query's query_form
1341 $query = '?'.join('&', map {
1342 my $val = $params->{$_};
1343 s/([;\/?:@&=+,\$\[\]%])/$URI::Escape::escapes{$1}/go;
1346 $val = '' unless defined $val;
1349 utf8::encode( $param ) if utf8::is_utf8($param);
1350 # using the URI::Escape pattern here so utf8 chars survive
1351 $param =~ s/([^A-Za-z0-9\-_.!~*'() ])/$URI::Escape::escapes{$1}/go;
1353 "${key}=$param"; } ( ref $val eq 'ARRAY' ? @$val : $val ));
1357 my $res = bless(\"${base}${args}${query}", $class);
1361 =head2 $c->uri_for_action( $path, \@captures?, @args?, \%query_values? )
1363 =head2 $c->uri_for_action( $action, \@captures?, @args?, \%query_values? )
1369 A private path to the Catalyst action you want to create a URI for.
1371 This is a shortcut for calling C<< $c->dispatcher->get_action_by_path($path)
1372 >> and passing the resulting C<$action> and the remaining arguments to C<<
1375 You can also pass in a Catalyst::Action object, in which case it is passed to
1378 Note that although the path looks like a URI that dispatches to the wanted action, it is not a URI, but an internal path to that action.
1380 For example, if the action looks like:
1382 package MyApp::Controller::Users;
1384 sub lst : Path('the-list') {}
1388 $c->uri_for_action('/users/lst')
1390 and it will create the URI /users/the-list.
1396 sub uri_for_action {
1397 my ( $c, $path, @args ) = @_;
1398 my $action = blessed($path)
1400 : $c->dispatcher->get_action_by_path($path);
1401 unless (defined $action) {
1402 croak "Can't find action for path '$path'";
1404 return $c->uri_for( $action, @args );
1407 =head2 $c->welcome_message
1409 Returns the Catalyst welcome HTML page.
1413 sub welcome_message {
1415 my $name = $c->config->{name};
1416 my $logo = $c->uri_for('/static/images/catalyst_logo.png');
1417 my $prefix = Catalyst::Utils::appprefix( ref $c );
1418 $c->response->content_type('text/html; charset=utf-8');
1420 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1421 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1422 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
1424 <meta http-equiv="Content-Language" content="en" />
1425 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
1426 <title>$name on Catalyst $VERSION</title>
1427 <style type="text/css">
1430 background-color: #eee;
1437 margin-bottom: 10px;
1439 background-color: #ccc;
1440 border: 1px solid #aaa;
1445 font-family: verdana, tahoma, sans-serif;
1448 font-family: verdana, tahoma, sans-serif;
1451 text-decoration: none;
1453 border-bottom: 1px dotted #bbb;
1455 :link:hover, :visited:hover {
1468 background-color: #fff;
1469 border: 1px solid #aaa;
1473 font-weight: normal;
1495 <h1><span id="appname">$name</span> on <a href="http://catalyst.perl.org">Catalyst</a>
1500 <img src="$logo" alt="Catalyst Logo" />
1502 <p>Welcome to the world of Catalyst.
1503 This <a href="http://en.wikipedia.org/wiki/MVC">MVC</a>
1504 framework will make web development something you had
1505 never expected it to be: Fun, rewarding, and quick.</p>
1506 <h2>What to do now?</h2>
1507 <p>That really depends on what <b>you</b> want to do.
1508 We do, however, provide you with a few starting points.</p>
1509 <p>If you want to jump right into web development with Catalyst
1510 you might want to start with a tutorial.</p>
1511 <pre>perldoc <a href="http://cpansearch.perl.org/dist/Catalyst-Manual/lib/Catalyst/Manual/Tutorial.pod">Catalyst::Manual::Tutorial</a></code>
1513 <p>Afterwards you can go on to check out a more complete look at our features.</p>
1515 <code>perldoc <a href="http://cpansearch.perl.org/dist/Catalyst-Manual/lib/Catalyst/Manual/Intro.pod">Catalyst::Manual::Intro</a>
1516 <!-- Something else should go here, but the Catalyst::Manual link seems unhelpful -->
1518 <h2>What to do next?</h2>
1519 <p>Next it's time to write an actual application. Use the
1520 helper scripts to generate <a href="http://cpansearch.perl.org/search?query=Catalyst%3A%3AController%3A%3A&mode=all">controllers</a>,
1521 <a href="http://cpansearch.perl.org/search?query=Catalyst%3A%3AModel%3A%3A&mode=all">models</a>, and
1522 <a href="http://cpansearch.perl.org/search?query=Catalyst%3A%3AView%3A%3A&mode=all">views</a>;
1523 they can save you a lot of work.</p>
1524 <pre><code>script/${prefix}_create.pl --help</code></pre>
1525 <p>Also, be sure to check out the vast and growing
1526 collection of <a href="http://search.cpan.org/search?query=Catalyst">plugins for Catalyst on CPAN</a>;
1527 you are likely to find what you need there.
1531 <p>Catalyst has a very active community. Here are the main places to
1532 get in touch with us.</p>
1535 <a href="http://dev.catalyst.perl.org">Wiki</a>
1538 <a href="http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst">Mailing-List</a>
1541 <a href="irc://irc.perl.org/catalyst">IRC channel #catalyst on irc.perl.org</a>
1544 <h2>In conclusion</h2>
1545 <p>The Catalyst team hopes you will enjoy using Catalyst as much
1546 as we enjoyed making it. Please contact us if you have ideas
1547 for improvement or other feedback.</p>
1555 =head1 INTERNAL METHODS
1557 These methods are not meant to be used by end users.
1559 =head2 $c->components
1561 Returns a hash of components.
1563 =head2 $c->context_class
1565 Returns or sets the context class.
1569 Returns a hashref containing coderefs and execution counts (needed for
1570 deep recursion detection).
1574 Returns the number of actions on the current internal execution stack.
1578 Dispatches a request to actions.
1582 sub dispatch { my $c = shift; $c->dispatcher->dispatch( $c, @_ ) }
1584 =head2 $c->dispatcher_class
1586 Returns or sets the dispatcher class.
1588 =head2 $c->dump_these
1590 Returns a list of 2-element array references (name, structure) pairs
1591 that will be dumped on the error page in debug mode.
1597 [ Request => $c->req ],
1598 [ Response => $c->res ],
1599 [ Stash => $c->stash ],
1600 [ Config => $c->config ];
1603 =head2 $c->engine_class
1605 Returns or sets the engine class.
1607 =head2 $c->execute( $class, $coderef )
1609 Execute a coderef in given class and catch exceptions. Errors are available
1615 my ( $c, $class, $code ) = @_;
1616 $class = $c->component($class) || $class;
1619 if ( $c->depth >= $RECURSION ) {
1620 my $action = $code->reverse();
1621 $action = "/$action" unless $action =~ /->/;
1622 my $error = qq/Deep recursion detected calling "${action}"/;
1623 $c->log->error($error);
1629 my $stats_info = $c->_stats_start_execute( $code ) if $c->use_stats;
1631 push( @{ $c->stack }, $code );
1633 no warnings 'recursion';
1634 eval { $c->state( $code->execute( $class, $c, @{ $c->req->args } ) || 0 ) };
1636 $c->_stats_finish_execute( $stats_info ) if $c->use_stats and $stats_info;
1638 my $last = pop( @{ $c->stack } );
1640 if ( my $error = $@ ) {
1641 if ( blessed($error) and $error->isa('Catalyst::Exception::Detach') ) {
1642 $error->rethrow if $c->depth > 1;
1644 elsif ( blessed($error) and $error->isa('Catalyst::Exception::Go') ) {
1645 $error->rethrow if $c->depth > 0;
1648 unless ( ref $error ) {
1649 no warnings 'uninitialized';
1651 my $class = $last->class;
1652 my $name = $last->name;
1653 $error = qq/Caught exception in $class->$name "$error"/;
1662 sub _stats_start_execute {
1663 my ( $c, $code ) = @_;
1664 my $appclass = ref($c) || $c;
1665 return if ( ( $code->name =~ /^_.*/ )
1666 && ( !$appclass->config->{show_internal_actions} ) );
1668 my $action_name = $code->reverse();
1669 $c->counter->{$action_name}++;
1671 my $action = $action_name;
1672 $action = "/$action" unless $action =~ /->/;
1674 # determine if the call was the result of a forward
1675 # this is done by walking up the call stack and looking for a calling
1676 # sub of Catalyst::forward before the eval
1678 for my $index ( 2 .. 11 ) {
1680 if ( ( caller($index) )[0] eq 'Catalyst'
1681 && ( caller($index) )[3] eq '(eval)' );
1683 if ( ( caller($index) )[3] =~ /forward$/ ) {
1684 $callsub = ( caller($index) )[3];
1685 $action = "-> $action";
1690 my $uid = $action_name . $c->counter->{$action_name};
1692 # is this a root-level call or a forwarded call?
1693 if ( $callsub =~ /forward$/ ) {
1694 my $parent = $c->stack->[-1];
1696 # forward, locate the caller
1697 if ( exists $c->counter->{"$parent"} ) {
1700 parent => "$parent" . $c->counter->{"$parent"},
1706 # forward with no caller may come from a plugin
1725 sub _stats_finish_execute {
1726 my ( $c, $info ) = @_;
1727 $c->stats->profile( end => $info );
1732 Finalizes the request.
1739 for my $error ( @{ $c->error } ) {
1740 $c->log->error($error);
1743 # Allow engine to handle finalize flow (for POE)
1744 my $engine = $c->engine;
1745 if ( my $code = $engine->can('finalize') ) {
1750 $c->finalize_uploads;
1753 if ( $#{ $c->error } >= 0 ) {
1757 $c->finalize_headers;
1760 if ( $c->request->method eq 'HEAD' ) {
1761 $c->response->body('');
1769 if ($c->use_stats) {
1770 my $elapsed = sprintf '%f', $c->stats->elapsed;
1771 my $av = $elapsed == 0 ? '??' : sprintf '%.3f', 1 / $elapsed;
1773 "Request took ${elapsed}s ($av/s)\n" . $c->stats->report . "\n" );
1776 return $c->response->status;
1779 =head2 $c->finalize_body
1785 sub finalize_body { my $c = shift; $c->engine->finalize_body( $c, @_ ) }
1787 =head2 $c->finalize_cookies
1793 sub finalize_cookies { my $c = shift; $c->engine->finalize_cookies( $c, @_ ) }
1795 =head2 $c->finalize_error
1801 sub finalize_error { my $c = shift; $c->engine->finalize_error( $c, @_ ) }
1803 =head2 $c->finalize_headers
1809 sub finalize_headers {
1812 my $response = $c->response; #accessor calls can add up?
1814 # Check if we already finalized headers
1815 return if $response->finalized_headers;
1818 if ( my $location = $response->redirect ) {
1819 $c->log->debug(qq/Redirecting to "$location"/) if $c->debug;
1820 $response->header( Location => $location );
1822 if ( !$response->has_body ) {
1823 # Add a default body if none is already present
1825 qq{<html><body><p>This item has moved <a href="$location">here</a>.</p></body></html>}
1831 if ( $response->body && !$response->content_length ) {
1833 # get the length from a filehandle
1834 if ( blessed( $response->body ) && $response->body->can('read') )
1836 my $stat = stat $response->body;
1837 if ( $stat && $stat->size > 0 ) {
1838 $response->content_length( $stat->size );
1841 $c->log->warn('Serving filehandle without a content-length');
1845 # everything should be bytes at this point, but just in case
1846 $response->content_length( length( $response->body ) );
1851 if ( $response->status =~ /^(1\d\d|[23]04)$/ ) {
1852 $response->headers->remove_header("Content-Length");
1853 $response->body('');
1856 $c->finalize_cookies;
1858 $c->engine->finalize_headers( $c, @_ );
1861 $response->finalized_headers(1);
1864 =head2 $c->finalize_output
1866 An alias for finalize_body.
1868 =head2 $c->finalize_read
1870 Finalizes the input after reading is complete.
1874 sub finalize_read { my $c = shift; $c->engine->finalize_read( $c, @_ ) }
1876 =head2 $c->finalize_uploads
1878 Finalizes uploads. Cleans up any temporary files.
1882 sub finalize_uploads { my $c = shift; $c->engine->finalize_uploads( $c, @_ ) }
1884 =head2 $c->get_action( $action, $namespace )
1886 Gets an action in a given namespace.
1890 sub get_action { my $c = shift; $c->dispatcher->get_action(@_) }
1892 =head2 $c->get_actions( $action, $namespace )
1894 Gets all actions of a given name in a namespace and all parent
1899 sub get_actions { my $c = shift; $c->dispatcher->get_actions( $c, @_ ) }
1901 =head2 $c->handle_request( $class, @arguments )
1903 Called to handle each HTTP request.
1907 sub handle_request {
1908 my ( $class, @arguments ) = @_;
1910 # Always expect worst case!
1913 if ($class->debug) {
1914 my $secs = time - $START || 1;
1915 my $av = sprintf '%.3f', $COUNT / $secs;
1916 my $time = localtime time;
1917 $class->log->info("*** Request $COUNT ($av/s) [$$] [$time] ***");
1920 my $c = $class->prepare(@arguments);
1922 $status = $c->finalize;
1925 if ( my $error = $@ ) {
1927 $class->log->error(qq/Caught exception in engine "$error"/);
1932 if(my $coderef = $class->log->can('_flush')){
1933 $class->log->$coderef();
1938 =head2 $c->prepare( @arguments )
1940 Creates a Catalyst context from an engine-specific request (Apache, CGI,
1946 my ( $class, @arguments ) = @_;
1949 # After the app/ctxt split, this should become an attribute based on something passed
1950 # into the application.
1951 $class->context_class( ref $class || $class ) unless $class->context_class;
1953 my $c = $class->context_class->new({});
1955 # For on-demand data
1956 $c->request->_context($c);
1957 $c->response->_context($c);
1959 #surely this is not the most efficient way to do things...
1960 $c->stats($class->stats_class->new)->enable($c->use_stats);
1961 if ( $c->debug || $c->config->{enable_catalyst_header} ) {
1962 $c->res->headers->header( 'X-Catalyst' => $Catalyst::VERSION );
1965 #XXX reuse coderef from can
1966 # Allow engine to direct the prepare flow (for POE)
1967 if ( $c->engine->can('prepare') ) {
1968 $c->engine->prepare( $c, @arguments );
1971 $c->prepare_request(@arguments);
1972 $c->prepare_connection;
1973 $c->prepare_query_parameters;
1974 $c->prepare_headers;
1975 $c->prepare_cookies;
1978 # Prepare the body for reading, either by prepare_body
1979 # or the user, if they are using $c->read
1982 # Parse the body unless the user wants it on-demand
1983 unless ( ref($c)->config->{parse_on_demand} ) {
1988 my $method = $c->req->method || '';
1989 my $path = $c->req->path;
1990 $path = '/' unless length $path;
1991 my $address = $c->req->address || '';
2000 =head2 $c->prepare_action
2002 Prepares action. See L<Catalyst::Dispatcher>.
2006 sub prepare_action { my $c = shift; $c->dispatcher->prepare_action( $c, @_ ) }
2008 =head2 $c->prepare_body
2010 Prepares message body.
2017 return if $c->request->_has_body;
2019 # Initialize on-demand data
2020 $c->engine->prepare_body( $c, @_ );
2021 $c->prepare_parameters;
2022 $c->prepare_uploads;
2025 =head2 $c->prepare_body_chunk( $chunk )
2027 Prepares a chunk of data before sending it to L<HTTP::Body>.
2029 See L<Catalyst::Engine>.
2033 sub prepare_body_chunk {
2035 $c->engine->prepare_body_chunk( $c, @_ );
2038 =head2 $c->prepare_body_parameters
2040 Prepares body parameters.
2044 sub prepare_body_parameters {
2046 $c->engine->prepare_body_parameters( $c, @_ );
2049 =head2 $c->prepare_connection
2051 Prepares connection.
2055 sub prepare_connection {
2057 $c->engine->prepare_connection( $c, @_ );
2060 =head2 $c->prepare_cookies
2066 sub prepare_cookies { my $c = shift; $c->engine->prepare_cookies( $c, @_ ) }
2068 =head2 $c->prepare_headers
2074 sub prepare_headers { my $c = shift; $c->engine->prepare_headers( $c, @_ ) }
2076 =head2 $c->prepare_parameters
2078 Prepares parameters.
2082 sub prepare_parameters {
2084 $c->prepare_body_parameters;
2085 $c->engine->prepare_parameters( $c, @_ );
2088 =head2 $c->prepare_path
2090 Prepares path and base.
2094 sub prepare_path { my $c = shift; $c->engine->prepare_path( $c, @_ ) }
2096 =head2 $c->prepare_query_parameters
2098 Prepares query parameters.
2102 sub prepare_query_parameters {
2105 $c->engine->prepare_query_parameters( $c, @_ );
2108 =head2 $c->log_request
2110 Writes information about the request to the debug logs. This includes:
2114 =item * Request method, path, and remote IP address
2116 =item * Query keywords (see L<Catalyst::Request/query_keywords>)
2118 =item * Request parameters
2120 =item * File uploads
2129 return unless $c->debug;
2131 my($dump) = grep {$_->[0] eq 'Request' } $c->dump_these;
2132 my $request = $dump->[1];
2134 my ( $method, $path, $address ) = ( $request->method, $request->path, $request->address );
2136 $path = '/' unless length $path;
2138 $c->log->debug(qq/"$method" request for "$path" from "$address"/);
2140 $c->log_request_headers($request->headers);
2142 if ( my $keywords = $request->query_keywords ) {
2143 $c->log->debug("Query keywords are: $keywords");
2146 $c->log_request_parameters( query => $request->query_parameters, body => $request->body_parameters );
2148 $c->log_request_uploads($request);
2151 =head2 $c->log_response
2153 Writes information about the response to the debug logs by calling
2154 C<< $c->log_response_status_line >> and C<< $c->log_response_headers >>.
2161 return unless $c->debug;
2163 my($dump) = grep {$_->[0] eq 'Response' } $c->dump_these;
2164 my $response = $dump->[1];
2166 $c->log_response_status_line($response);
2167 $c->log_response_headers($response->headers);
2170 =head2 $c->log_response_status_line($response)
2172 Writes one line of information about the response to the debug logs. This includes:
2176 =item * Response status code
2178 =item * Content-Type header (if present)
2180 =item * Content-Length header (if present)
2186 sub log_response_status_line {
2187 my ($c, $response) = @_;
2191 'Response Code: %s; Content-Type: %s; Content-Length: %s',
2192 $response->status || 'unknown',
2193 $response->headers->header('Content-Type') || 'unknown',
2194 $response->headers->header('Content-Length') || 'unknown'
2199 =head2 $c->log_response_headers($headers);
2201 Hook method which can be wrapped by plugins to log the responseheaders.
2202 No-op in the default implementation.
2206 sub log_response_headers {}
2208 =head2 $c->log_request_parameters( query => {}, body => {} )
2210 Logs request parameters to debug logs
2214 sub log_request_parameters {
2216 my %all_params = @_;
2218 return unless $c->debug;
2220 my $column_width = Catalyst::Utils::term_width() - 44;
2221 foreach my $type (qw(query body)) {
2222 my $params = $all_params{$type};
2223 next if ! keys %$params;
2224 my $t = Text::SimpleTable->new( [ 35, 'Parameter' ], [ $column_width, 'Value' ] );
2225 for my $key ( sort keys %$params ) {
2226 my $param = $params->{$key};
2227 my $value = defined($param) ? $param : '';
2228 $t->row( $key, ref $value eq 'ARRAY' ? ( join ', ', @$value ) : $value );
2230 $c->log->debug( ucfirst($type) . " Parameters are:\n" . $t->draw );
2234 =head2 $c->log_request_uploads
2236 Logs file uploads included in the request to the debug logs.
2237 The parameter name, filename, file type, and file size are all included in
2242 sub log_request_uploads {
2244 my $request = shift;
2245 return unless $c->debug;
2246 my $uploads = $request->uploads;
2247 if ( keys %$uploads ) {
2248 my $t = Text::SimpleTable->new(
2249 [ 12, 'Parameter' ],
2254 for my $key ( sort keys %$uploads ) {
2255 my $upload = $uploads->{$key};
2256 for my $u ( ref $upload eq 'ARRAY' ? @{$upload} : ($upload) ) {
2257 $t->row( $key, $u->filename, $u->type, $u->size );
2260 $c->log->debug( "File Uploads are:\n" . $t->draw );
2264 =head2 $c->log_request_headers($headers);
2266 Hook method which can be wrapped by plugins to log the request headers.
2267 No-op in the default implementation.
2271 sub log_request_headers {}
2273 =head2 $c->log_headers($type => $headers)
2275 Logs L<HTTP::Headers> (either request or response) to the debug logs.
2282 my $headers = shift; # an HTTP::Headers instance
2284 return unless $c->debug;
2286 my $column_width = Catalyst::Utils::term_width() - 28;
2287 my $t = Text::SimpleTable->new( [ 15, 'Header Name' ], [ $column_width, 'Value' ] );
2290 my ( $name, $value ) = @_;
2291 $t->row( $name, $value );
2294 $c->log->debug( ucfirst($type) . " Headers:\n" . $t->draw );
2298 =head2 $c->prepare_read
2300 Prepares the input for reading.
2304 sub prepare_read { my $c = shift; $c->engine->prepare_read( $c, @_ ) }
2306 =head2 $c->prepare_request
2308 Prepares the engine request.
2312 sub prepare_request { my $c = shift; $c->engine->prepare_request( $c, @_ ) }
2314 =head2 $c->prepare_uploads
2320 sub prepare_uploads {
2323 $c->engine->prepare_uploads( $c, @_ );
2326 =head2 $c->prepare_write
2328 Prepares the output for writing.
2332 sub prepare_write { my $c = shift; $c->engine->prepare_write( $c, @_ ) }
2334 =head2 $c->request_class
2336 Returns or sets the request class.
2338 =head2 $c->response_class
2340 Returns or sets the response class.
2342 =head2 $c->read( [$maxlength] )
2344 Reads a chunk of data from the request body. This method is designed to
2345 be used in a while loop, reading C<$maxlength> bytes on every call.
2346 C<$maxlength> defaults to the size of the request if not specified.
2348 You have to set C<< MyApp->config(parse_on_demand => 1) >> to use this
2351 Warning: If you use read(), Catalyst will not process the body,
2352 so you will not be able to access POST parameters or file uploads via
2353 $c->request. You must handle all body parsing yourself.
2357 sub read { my $c = shift; return $c->engine->read( $c, @_ ) }
2365 sub run { my $c = shift; return $c->engine->run( $c, @_ ) }
2367 =head2 $c->set_action( $action, $code, $namespace, $attrs )
2369 Sets an action in a given namespace.
2373 sub set_action { my $c = shift; $c->dispatcher->set_action( $c, @_ ) }
2375 =head2 $c->setup_actions($component)
2377 Sets up actions for a component.
2381 sub setup_actions { my $c = shift; $c->dispatcher->setup_actions( $c, @_ ) }
2383 =head2 $c->setup_components
2385 This method is called internally to set up the application's components.
2387 It finds modules by calling the L<locate_components> method, expands them to
2388 package names with the L<expand_component_module> method, and then installs
2389 each component into the application.
2391 The C<setup_components> config option is passed to both of the above methods.
2393 Installation of each component is performed by the L<setup_component> method,
2398 sub setup_components {
2401 my $config = $class->config->{ setup_components };
2403 my @comps = sort { length $a <=> length $b }
2404 $class->locate_components($config);
2405 my %comps = map { $_ => 1 } @comps;
2407 my $deprecatedcatalyst_component_names = grep { /::[CMV]::/ } @comps;
2408 $class->log->warn(qq{Your application is using the deprecated ::[MVC]:: type naming scheme.\n}.
2409 qq{Please switch your class names to ::Model::, ::View:: and ::Controller: as appropriate.\n}
2410 ) if $deprecatedcatalyst_component_names;
2412 for my $component ( @comps ) {
2414 # We pass ignore_loaded here so that overlay files for (e.g.)
2415 # Model::DBI::Schema sub-classes are loaded - if it's in @comps
2416 # we know M::P::O found a file on disk so this is safe
2418 Catalyst::Utils::ensure_class_loaded( $component, { ignore_loaded => 1 } );
2420 # Needs to be done as soon as the component is loaded, as loading a sub-component
2421 # (next time round the loop) can cause us to get the wrong metaclass..
2422 $class->_controller_init_base_classes($component);
2425 for my $component (@comps) {
2426 my $instance = $class->components->{ $component } = $class->setup_component($component);
2427 my @expanded_components = $instance->can('expand_modules')
2428 ? $instance->expand_modules( $component, $config )
2429 : $class->expand_component_module( $component, $config );
2430 for my $component (@expanded_components) {
2431 next if $comps{$component};
2432 $class->_controller_init_base_classes($component); # Also cover inner packages
2433 $class->components->{ $component } = $class->setup_component($component);
2438 =head2 $c->locate_components( $setup_component_config )
2440 This method is meant to provide a list of component modules that should be
2441 setup for the application. By default, it will use L<Module::Pluggable>.
2443 Specify a C<setup_components> config option to pass additional options directly
2444 to L<Module::Pluggable>. To add additional search paths, specify a key named
2445 C<search_extra> as an array reference. Items in the array beginning with C<::>
2446 will have the application class name prepended to them.
2450 sub locate_components {
2454 my @paths = qw( ::Controller ::C ::Model ::M ::View ::V );
2455 my $extra = delete $config->{ search_extra } || [];
2457 push @paths, @$extra;
2459 my $locator = Module::Pluggable::Object->new(
2460 search_path => [ map { s/^(?=::)/$class/; $_; } @paths ],
2464 my @comps = $locator->plugins;
2469 =head2 $c->expand_component_module( $component, $setup_component_config )
2471 Components found by C<locate_components> will be passed to this method, which
2472 is expected to return a list of component (package) names to be set up.
2476 sub expand_component_module {
2477 my ($class, $module) = @_;
2478 return Devel::InnerPackage::list_packages( $module );
2481 =head2 $c->setup_component
2485 # FIXME - Ugly, ugly hack to ensure the we force initialize non-moose base classes
2486 # nearest to Catalyst::Controller first, no matter what order stuff happens
2487 # to be loaded. There are TODO tests in Moose for this, see
2488 # f2391d17574eff81d911b97be15ea51080500003
2489 sub _controller_init_base_classes {
2490 my ($app_class, $component) = @_;
2491 return unless $component->isa('Catalyst::Controller');
2492 foreach my $class ( reverse @{ mro::get_linear_isa($component) } ) {
2493 Moose::Meta::Class->initialize( $class )
2494 unless find_meta($class);
2498 sub setup_component {
2499 my( $class, $component ) = @_;
2501 unless ( $component->can( 'COMPONENT' ) ) {
2505 my $suffix = Catalyst::Utils::class2classsuffix( $component );
2506 my $config = $class->config->{ $suffix } || {};
2507 # Stash catalyst_component_name in the config here, so that custom COMPONENT
2508 # methods also pass it. local to avoid pointlessly shitting in config
2509 # for the debug screen, as $component is already the key name.
2510 local $config->{catalyst_component_name} = $component;
2512 my $instance = eval { $component->COMPONENT( $class, $config ); };
2514 if ( my $error = $@ ) {
2516 Catalyst::Exception->throw(
2517 message => qq/Couldn't instantiate component "$component", "$error"/
2521 unless (blessed $instance) {
2522 my $metaclass = Moose::Util::find_meta($component);
2523 my $method_meta = $metaclass->find_method_by_name('COMPONENT');
2524 my $component_method_from = $method_meta->associated_metaclass->name;
2525 my $value = defined($instance) ? $instance : 'undef';
2526 Catalyst::Exception->throw(
2528 qq/Couldn't instantiate component "$component", COMPONENT() method (from $component_method_from) didn't return an object-like value (value was $value)./
2534 =head2 $c->setup_dispatcher
2540 sub setup_dispatcher {
2541 my ( $class, $dispatcher ) = @_;
2544 $dispatcher = 'Catalyst::Dispatcher::' . $dispatcher;
2547 if ( my $env = Catalyst::Utils::env_value( $class, 'DISPATCHER' ) ) {
2548 $dispatcher = 'Catalyst::Dispatcher::' . $env;
2551 unless ($dispatcher) {
2552 $dispatcher = $class->dispatcher_class;
2555 Class::MOP::load_class($dispatcher);
2557 # dispatcher instance
2558 $class->dispatcher( $dispatcher->new );
2561 =head2 $c->setup_engine
2568 my ( $class, $engine ) = @_;
2571 $engine = 'Catalyst::Engine::' . $engine;
2574 if ( my $env = Catalyst::Utils::env_value( $class, 'ENGINE' ) ) {
2575 $engine = 'Catalyst::Engine::' . $env;
2578 if ( $ENV{MOD_PERL} ) {
2579 my $meta = Class::MOP::get_metaclass_by_name($class);
2581 # create the apache method
2582 $meta->add_method('apache' => sub { shift->engine->apache });
2584 my ( $software, $version ) =
2585 $ENV{MOD_PERL} =~ /^(\S+)\/(\d+(?:[\.\_]\d+)+)/;
2588 $version =~ s/(\.[^.]+)\./$1/g;
2590 if ( $software eq 'mod_perl' ) {
2594 if ( $version >= 1.99922 ) {
2595 $engine = 'Catalyst::Engine::Apache2::MP20';
2598 elsif ( $version >= 1.9901 ) {
2599 $engine = 'Catalyst::Engine::Apache2::MP19';
2602 elsif ( $version >= 1.24 ) {
2603 $engine = 'Catalyst::Engine::Apache::MP13';
2607 Catalyst::Exception->throw( message =>
2608 qq/Unsupported mod_perl version: $ENV{MOD_PERL}/ );
2613 # install the correct mod_perl handler
2614 if ( $version >= 1.9901 ) {
2615 *handler = sub : method {
2616 shift->handle_request(@_);
2620 *handler = sub ($$) { shift->handle_request(@_) };
2625 elsif ( $software eq 'Zeus-Perl' ) {
2626 $engine = 'Catalyst::Engine::Zeus';
2630 Catalyst::Exception->throw(
2631 message => qq/Unsupported mod_perl: $ENV{MOD_PERL}/ );
2636 $engine = $class->engine_class;
2639 Class::MOP::load_class($engine);
2641 # check for old engines that are no longer compatible
2643 if ( $engine->isa('Catalyst::Engine::Apache')
2644 && !Catalyst::Engine::Apache->VERSION )
2649 elsif ( $engine->isa('Catalyst::Engine::Server::Base')
2650 && Catalyst::Engine::Server->VERSION le '0.02' )
2655 elsif ($engine->isa('Catalyst::Engine::HTTP::POE')
2656 && $engine->VERSION eq '0.01' )
2661 elsif ($engine->isa('Catalyst::Engine::Zeus')
2662 && $engine->VERSION eq '0.01' )
2668 Catalyst::Exception->throw( message =>
2669 qq/Engine "$engine" is not supported by this version of Catalyst/
2674 $class->engine( $engine->new );
2677 =head2 $c->setup_home
2679 Sets up the home directory.
2684 my ( $class, $home ) = @_;
2686 if ( my $env = Catalyst::Utils::env_value( $class, 'HOME' ) ) {
2690 $home ||= Catalyst::Utils::home($class);
2693 #I remember recently being scolded for assigning config values like this
2694 $class->config->{home} ||= $home;
2695 $class->config->{root} ||= Path::Class::Dir->new($home)->subdir('root');
2699 =head2 $c->setup_log
2701 Sets up log by instantiating a L<Catalyst::Log|Catalyst::Log> object and
2702 passing it to C<log()>. Pass in a comma-delimited list of levels to set the
2705 This method also installs a C<debug> method that returns a true value into the
2706 catalyst subclass if the "debug" level is passed in the comma-delimited list,
2707 or if the C<$CATALYST_DEBUG> environment variable is set to a true value.
2709 Note that if the log has already been setup, by either a previous call to
2710 C<setup_log> or by a call such as C<< __PACKAGE__->log( MyLogger->new ) >>,
2711 that this method won't actually set up the log object.
2716 my ( $class, $levels ) = @_;
2719 $levels =~ s/^\s+//;
2720 $levels =~ s/\s+$//;
2721 my %levels = map { $_ => 1 } split /\s*,\s*/, $levels;
2723 my $env_debug = Catalyst::Utils::env_value( $class, 'DEBUG' );
2724 if ( defined $env_debug ) {
2725 $levels{debug} = 1 if $env_debug; # Ugly!
2726 delete($levels{debug}) unless $env_debug;
2729 unless ( $class->log ) {
2730 $class->log( Catalyst::Log->new(keys %levels) );
2733 if ( $levels{debug} ) {
2734 Class::MOP::get_metaclass_by_name($class)->add_method('debug' => sub { 1 });
2735 $class->log->debug('Debug messages enabled');
2739 =head2 $c->setup_plugins
2745 =head2 $c->setup_stats
2747 Sets up timing statistics class.
2752 my ( $class, $stats ) = @_;
2754 Catalyst::Utils::ensure_class_loaded($class->stats_class);
2756 my $env = Catalyst::Utils::env_value( $class, 'STATS' );
2757 if ( defined($env) ? $env : ($stats || $class->debug ) ) {
2758 Class::MOP::get_metaclass_by_name($class)->add_method('use_stats' => sub { 1 });
2759 $class->log->debug('Statistics enabled');
2764 =head2 $c->registered_plugins
2766 Returns a sorted list of the plugins which have either been stated in the
2767 import list or which have been added via C<< MyApp->plugin(@args); >>.
2769 If passed a given plugin name, it will report a boolean value indicating
2770 whether or not that plugin is loaded. A fully qualified name is required if
2771 the plugin name does not begin with C<Catalyst::Plugin::>.
2773 if ($c->registered_plugins('Some::Plugin')) {
2781 sub registered_plugins {
2783 return sort keys %{ $proto->_plugins } unless @_;
2785 return 1 if exists $proto->_plugins->{$plugin};
2786 return exists $proto->_plugins->{"Catalyst::Plugin::$plugin"};
2789 sub _register_plugin {
2790 my ( $proto, $plugin, $instant ) = @_;
2791 my $class = ref $proto || $proto;
2793 Class::MOP::load_class( $plugin );
2794 $class->log->warn( "$plugin inherits from 'Catalyst::Component' - this is decated and will not work in 5.81" )
2795 if $plugin->isa( 'Catalyst::Component' );
2796 $proto->_plugins->{$plugin} = 1;
2798 my $meta = Class::MOP::get_metaclass_by_name($class);
2799 $meta->superclasses($plugin, $meta->superclasses);
2805 my ( $class, $plugins ) = @_;
2807 $class->_plugins( {} ) unless $class->_plugins;
2810 my @plugins = Catalyst::Utils::resolve_namespace($class . '::Plugin', 'Catalyst::Plugin', @$plugins);
2812 for my $plugin ( reverse @plugins ) {
2813 Class::MOP::load_class($plugin);
2814 my $meta = find_meta($plugin);
2815 next if $meta && $meta->isa('Moose::Meta::Role');
2817 $class->_register_plugin($plugin);
2822 grep { $_ && blessed($_) && $_->isa('Moose::Meta::Role') }
2823 map { find_meta($_) }
2826 Moose::Util::apply_all_roles(
2834 Returns an arrayref of the internal execution stack (actions that are
2835 currently executing).
2837 =head2 $c->stats_class
2839 Returns or sets the stats (timing statistics) class.
2841 =head2 $c->use_stats
2843 Returns 1 when stats collection is enabled. Stats collection is enabled
2844 when the -Stats options is set, debug is on or when the <MYAPP>_STATS
2845 environment variable is set.
2847 Note that this is a static method, not an accessor and should be overridden
2848 by declaring C<sub use_stats { 1 }> in your MyApp.pm, not by calling C<< $c->use_stats(1) >>.
2855 =head2 $c->write( $data )
2857 Writes $data to the output stream. When using this method directly, you
2858 will need to manually set the C<Content-Length> header to the length of
2859 your output data, if known.
2866 # Finalize headers if someone manually writes output
2867 $c->finalize_headers;
2869 return $c->engine->write( $c, @_ );
2874 Returns the Catalyst version number. Mostly useful for "powered by"
2875 messages in template systems.
2879 sub version { return $Catalyst::VERSION }
2881 =head1 CONFIGURATION
2883 There are a number of 'base' config variables which can be set:
2889 C<default_model> - The default model picked if you say C<< $c->model >>. See L<< /$c->model($name) >>.
2893 C<default_view> - The default view to be rendered or returned when C<< $c->view >> is called. See L<< /$c->view($name) >>.
2897 C<disable_component_resolution_regex_fallback> - Turns
2898 off the deprecated component resolution functionality so
2899 that if any of the component methods (e.g. C<< $c->controller('Foo') >>)
2900 are called then regex search will not be attempted on string values and
2901 instead C<undef> will be returned.
2905 C<home> - The application home directory. In an uninstalled application,
2906 this is the top level application directory. In an installed application,
2907 this will be the directory containing C<< MyApp.pm >>.
2911 C<ignore_frontend_proxy> - See L</PROXY SUPPORT>
2915 C<name> - The name of the application in debug messages and the debug and
2920 C<parse_on_demand> - The request body (for example file uploads) will not be parsed
2921 until it is accessed. This allows you to (for example) check authentication (and reject
2922 the upload) before actually recieving all the data. See L</ON-DEMAND PARSER>
2926 C<root> - The root directory for templates. Usually this is just a
2927 subdirectory of the home directory, but you can set it to change the
2928 templates to a different directory.
2932 C<search_extra> - Array reference passed to Module::Pluggable to for additional
2933 namespaces from which components will be loaded (and constructed and stored in
2934 C<< $c->components >>).
2938 C<show_internal_actions> - If true, causes internal actions such as C<< _DISPATCH >>
2939 to be shown in hit debug tables in the test server.
2943 C<using_frontend_proxy> - See L</PROXY SUPPORT>.
2947 =head1 INTERNAL ACTIONS
2949 Catalyst uses internal actions like C<_DISPATCH>, C<_BEGIN>, C<_AUTO>,
2950 C<_ACTION>, and C<_END>. These are by default not shown in the private
2951 action table, but you can make them visible with a config parameter.
2953 MyApp->config(show_internal_actions => 1);
2955 =head1 ON-DEMAND PARSER
2957 The request body is usually parsed at the beginning of a request,
2958 but if you want to handle input yourself, you can enable on-demand
2959 parsing with a config parameter.
2961 MyApp->config(parse_on_demand => 1);
2963 =head1 PROXY SUPPORT
2965 Many production servers operate using the common double-server approach,
2966 with a lightweight frontend web server passing requests to a larger
2967 backend server. An application running on the backend server must deal
2968 with two problems: the remote user always appears to be C<127.0.0.1> and
2969 the server's hostname will appear to be C<localhost> regardless of the
2970 virtual host that the user connected through.
2972 Catalyst will automatically detect this situation when you are running
2973 the frontend and backend servers on the same machine. The following
2974 changes are made to the request.
2976 $c->req->address is set to the user's real IP address, as read from
2977 the HTTP X-Forwarded-For header.
2979 The host value for $c->req->base and $c->req->uri is set to the real
2980 host, as read from the HTTP X-Forwarded-Host header.
2982 Additionally, you may be running your backend application on an insecure
2983 connection (port 80) while your frontend proxy is running under SSL. If there
2984 is a discrepancy in the ports, use the HTTP header C<X-Forwarded-Port> to
2985 tell Catalyst what port the frontend listens on. This will allow all URIs to
2986 be created properly.
2988 In the case of passing in:
2990 X-Forwarded-Port: 443
2992 All calls to C<uri_for> will result in an https link, as is expected.
2994 Obviously, your web server must support these headers for this to work.
2996 In a more complex server farm environment where you may have your
2997 frontend proxy server(s) on different machines, you will need to set a
2998 configuration option to tell Catalyst to read the proxied data from the
3001 MyApp->config(using_frontend_proxy => 1);
3003 If you do not wish to use the proxy support at all, you may set:
3005 MyApp->config(ignore_frontend_proxy => 1);
3007 =head1 THREAD SAFETY
3009 Catalyst has been tested under Apache 2's threading C<mpm_worker>,
3010 C<mpm_winnt>, and the standalone forking HTTP server on Windows. We
3011 believe the Catalyst core to be thread-safe.
3013 If you plan to operate in a threaded environment, remember that all other
3014 modules you are using must also be thread-safe. Some modules, most notably
3015 L<DBD::SQLite>, are not thread-safe.
3021 Join #catalyst on irc.perl.org.
3025 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
3026 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev
3030 http://catalyst.perl.org
3034 http://dev.catalyst.perl.org
3038 =head2 L<Task::Catalyst> - All you need to start with Catalyst
3040 =head2 L<Catalyst::Manual> - The Catalyst Manual
3042 =head2 L<Catalyst::Component>, L<Catalyst::Controller> - Base classes for components
3044 =head2 L<Catalyst::Engine> - Core engine
3046 =head2 L<Catalyst::Log> - Log class.
3048 =head2 L<Catalyst::Request> - Request object
3050 =head2 L<Catalyst::Response> - Response object
3052 =head2 L<Catalyst::Test> - The test suite.
3054 =head1 PROJECT FOUNDER
3056 sri: Sebastian Riedel <sri@cpan.org>
3062 acme: Leon Brocard <leon@astray.com>
3064 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
3068 Andrew Ford E<lt>A.Ford@ford-mason.co.ukE<gt>
3072 andyg: Andy Grundman <andy@hybridized.org>
3074 audreyt: Audrey Tang
3076 bricas: Brian Cassidy <bricas@cpan.org>
3078 Caelum: Rafael Kitover <rkitover@io.com>
3080 chansen: Christian Hansen
3082 chicks: Christopher Hicks
3084 Chisel Wright C<pause@herlpacker.co.uk>
3086 Danijel Milicevic C<me@danijel.de>
3088 David Kamholz E<lt>dkamholz@cpan.orgE<gt>
3090 David Naughton, C<naughton@umn.edu>
3094 dhoss: Devin Austin <dhoss@cpan.org>
3096 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
3100 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
3102 esskar: Sascha Kiefer
3104 fireartist: Carl Franks <cfranks@cpan.org>
3106 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
3108 gabb: Danijel Milicevic
3112 Gavin Henry C<ghenry@perl.me.uk>
3116 groditi: Guillermo Roditi <groditi@gmail.com>
3118 hobbs: Andrew Rodland <andrew@cleverdomain.org>
3120 ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
3122 jcamacho: Juan Camacho
3124 jester: Jesse Sheidlower C<jester@panix.com>
3126 jhannah: Jay Hannah <jay@jays.net>
3132 jon: Jon Schutz <jjschutz@cpan.org>
3134 Jonathan Rockway C<< <jrockway@cpan.org> >>
3136 Kieren Diment C<kd@totaldatasolution.com>
3138 konobi: Scott McWhirter <konobi@cpan.org>
3140 marcus: Marcus Ramberg <mramberg@cpan.org>
3142 miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>
3144 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
3148 naughton: David Naughton
3150 ningu: David Kamholz <dkamholz@cpan.org>
3152 nothingmuch: Yuval Kogman <nothingmuch@woobling.org>
3154 numa: Dan Sully <daniel@cpan.org>
3160 omega: Andreas Marienborg
3162 Oleg Kostyuk <cub.uanic@gmail.com>
3164 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
3166 rafl: Florian Ragwitz <rafl@debian.org>
3168 random: Roland Lammel <lammel@cpan.org>
3170 Robert Sedlacek C<< <rs@474.at> >>
3174 szbalint: Balint Szilakszi <szbalint@cpan.org>
3176 t0m: Tomas Doran <bobtfish@bobtfish.net>
3180 Viljo Marrandi C<vilts@yahoo.com>
3182 Will Hawes C<info@whawes.co.uk>
3184 willert: Sebastian Willert <willert@cpan.org>
3186 Yuval Kogman, C<nothingmuch@woobling.org>
3190 This library is free software. You can redistribute it and/or modify it under
3191 the same terms as Perl itself.
3197 __PACKAGE__->meta->make_immutable;