4 use base 'Catalyst::Component';
6 use Catalyst::Exception;
9 use Catalyst::Request::Upload;
10 use Catalyst::Response;
12 use Catalyst::Controller;
13 use Devel::InnerPackage ();
15 use Module::Pluggable::Object ();
17 use Text::SimpleTable ();
18 use Path::Class::Dir ();
19 use Path::Class::File ();
20 use Time::HiRes qw/gettimeofday tv_interval/;
22 use Scalar::Util qw/weaken blessed/;
23 use Tree::Simple qw/use_weak_refs/;
24 use Tree::Simple::Visitor::FindByUID;
29 BEGIN { require 5.008001; }
31 __PACKAGE__->mk_accessors(
32 qw/counter request response state action stack namespace stats/
35 attributes->import( __PACKAGE__, \&namespace, 'lvalue' );
37 sub depth { scalar @{ shift->stack || [] }; }
44 # For backwards compatibility
45 *finalize_output = \&finalize_body;
50 our $RECURSION = 1000;
51 our $DETACH = "catalyst_detach\n";
53 __PACKAGE__->mk_classdata($_)
54 for qw/components arguments dispatcher engine log dispatcher_class
55 engine_class context_class request_class response_class setup_finished/;
57 __PACKAGE__->dispatcher_class('Catalyst::Dispatcher');
58 __PACKAGE__->engine_class('Catalyst::Engine::CGI');
59 __PACKAGE__->request_class('Catalyst::Request');
60 __PACKAGE__->response_class('Catalyst::Response');
62 # Remember to update this in Catalyst::Runtime as well!
64 our $VERSION = '5.7007';
67 my ( $class, @arguments ) = @_;
69 # We have to limit $class to Catalyst to avoid pushing Catalyst upon every
71 return unless $class eq 'Catalyst';
73 my $caller = caller(0);
75 unless ( $caller->isa('Catalyst') ) {
77 push @{"$caller\::ISA"}, $class, 'Catalyst::Controller';
80 $caller->arguments( [@arguments] );
86 Catalyst - The Elegant MVC Web Application Framework
90 See the L<Catalyst::Manual> distribution for comprehensive
91 documentation and tutorials.
93 # Install Catalyst::Devel for helpers and other development tools
94 # use the helper to create a new application
97 # add models, views, controllers
98 script/myapp_create.pl model MyDatabase DBIC::Schema create=dynamic dbi:SQLite:/path/to/db
99 script/myapp_create.pl view MyTemplate TT
100 script/myapp_create.pl controller Search
102 # built in testserver -- use -r to restart automatically on changes
103 # --help to see all available options
104 script/myapp_server.pl
106 # command line testing interface
107 script/myapp_test.pl /yada
110 use Catalyst qw/-Debug/; # include plugins here as well
112 ### In lib/MyApp/Controller/Root.pm (autocreated)
113 sub foo : Global { # called for /foo, /foo/1, /foo/1/2, etc.
114 my ( $self, $c, @args ) = @_; # args are qw/1 2/ for /foo/1/2
115 $c->stash->{template} = 'foo.tt'; # set the template
116 # lookup something from db -- stash vars are passed to TT
118 $c->model('Database::Foo')->search( { country => $args[0] } );
119 if ( $c->req->params->{bar} ) { # access GET or POST parameters
120 $c->forward( 'bar' ); # process another action
121 # do something else after forward returns
125 # The foo.tt TT template can use the stash data from the database
126 [% WHILE (item = data.next) %]
130 # called for /bar/of/soap, /bar/of/soap/10, etc.
131 sub bar : Path('/bar/of/soap') { ... }
133 # called for all actions, from the top-most controller downwards
135 my ( $self, $c ) = @_;
136 if ( !$c->user_exists ) { # Catalyst::Plugin::Authentication
137 $c->res->redirect( '/login' ); # require login
138 return 0; # abort request and go immediately to end()
140 return 1; # success; carry on to next action
143 # called after all actions are finished
145 my ( $self, $c ) = @_;
146 if ( scalar @{ $c->error } ) { ... } # handle errors
147 return if $c->res->body; # already have a response
148 $c->forward( 'MyApp::View::TT' ); # render template
151 ### in MyApp/Controller/Foo.pm
152 # called for /foo/bar
153 sub bar : Local { ... }
155 # called for /blargle
156 sub blargle : Global { ... }
158 # an index action matches /foo, but not /foo/1, etc.
159 sub index : Private { ... }
161 ### in MyApp/Controller/Foo/Bar.pm
162 # called for /foo/bar/baz
163 sub baz : Local { ... }
165 # first Root auto is called, then Foo auto, then this
166 sub auto : Private { ... }
168 # powerful regular expression paths are also possible
169 sub details : Regex('^product/(\w+)/details$') {
170 my ( $self, $c ) = @_;
171 # extract the (\w+) from the URI
172 my $product = $c->req->captures->[0];
175 See L<Catalyst::Manual::Intro> for additional information.
179 Catalyst is a modern framework for making web applications without the
180 pain usually associated with this process. This document is a reference
181 to the main Catalyst application. If you are a new user, we suggest you
182 start with L<Catalyst::Manual::Tutorial> or L<Catalyst::Manual::Intro>.
184 See L<Catalyst::Manual> for more documentation.
186 Catalyst plugins can be loaded by naming them as arguments to the "use
187 Catalyst" statement. Omit the C<Catalyst::Plugin::> prefix from the
188 plugin name, i.e., C<Catalyst::Plugin::My::Module> becomes
191 use Catalyst qw/My::Module/;
193 If your plugin starts with a name other than C<Catalyst::Plugin::>, you can
194 fully qualify the name by using a unary plus:
198 +Fully::Qualified::Plugin::Name
201 Special flags like C<-Debug> and C<-Engine> can also be specified as
202 arguments when Catalyst is loaded:
204 use Catalyst qw/-Debug My::Module/;
206 The position of plugins and flags in the chain is important, because
207 they are loaded in the order in which they appear.
209 The following flags are supported:
213 Enables debug output. You can also force this setting from the system
214 environment with CATALYST_DEBUG or <MYAPP>_DEBUG. The environment
215 settings override the application, with <MYAPP>_DEBUG having the highest
220 Forces Catalyst to use a specific engine. Omit the
221 C<Catalyst::Engine::> prefix of the engine name, i.e.:
223 use Catalyst qw/-Engine=CGI/;
227 Forces Catalyst to use a specific home directory, e.g.:
229 use Catalyst qw[-Home=/usr/mst];
231 This can also be done in the shell environment by setting either the
232 C<CATALYST_HOME> environment variable or C<MYAPP_HOME>; where C<MYAPP>
233 is replaced with the uppercased name of your application, any "::" in
234 the name will be replaced with underscores, e.g. MyApp::Web should use
235 MYAPP_WEB_HOME. If both variables are set, the MYAPP_HOME one will be used.
243 =head2 INFORMATION ABOUT THE CURRENT REQUEST
247 Returns a L<Catalyst::Action> object for the current action, which
248 stringifies to the action name. See L<Catalyst::Action>.
252 Returns the namespace of the current action, i.e., the URI prefix
253 corresponding to the controller of the current action. For example:
255 # in Controller::Foo::Bar
256 $c->namespace; # returns 'foo/bar';
262 Returns the current L<Catalyst::Request> object, giving access to
263 information about the current client request (including parameters,
264 cookies, HTTP headers, etc.). See L<Catalyst::Request>.
266 =head2 REQUEST FLOW HANDLING
268 =head2 $c->forward( $action [, \@arguments ] )
270 =head2 $c->forward( $class, $method, [, \@arguments ] )
272 Forwards processing to another action, by its private name. If you give a
273 class name but no method, C<process()> is called. You may also optionally
274 pass arguments in an arrayref. The action will receive the arguments in
275 C<@_> and C<< $c->req->args >>. Upon returning from the function,
276 C<< $c->req->args >> will be restored to the previous values.
278 Any data C<return>ed from the action forwarded to, will be returned by the
281 my $foodata = $c->forward('/foo');
282 $c->forward('index');
283 $c->forward(qw/MyApp::Model::DBIC::Foo do_stuff/);
284 $c->forward('MyApp::View::TT');
286 Note that forward implies an C<<eval { }>> around the call (actually
287 C<execute> does), thus de-fatalizing all 'dies' within the called
288 action. If you want C<die> to propagate you need to do something like:
291 die $c->error if $c->error;
293 Or make sure to always return true values from your actions and write
296 $c->forward('foo') || return;
300 sub forward { my $c = shift; $c->dispatcher->forward( $c, @_ ) }
302 =head2 $c->detach( $action [, \@arguments ] )
304 =head2 $c->detach( $class, $method, [, \@arguments ] )
308 The same as C<forward>, but doesn't return to the previous action when
309 processing is finished.
311 When called with no arguments it escapes the processing chain entirely.
315 sub detach { my $c = shift; $c->dispatcher->detach( $c, @_ ) }
321 Returns the current L<Catalyst::Response> object, see there for details.
325 Returns a hashref to the stash, which may be used to store data and pass
326 it between components during a request. You can also set hash keys by
327 passing arguments. The stash is automatically sent to the view. The
328 stash is cleared at the end of a request; it cannot be used for
329 persistent storage (for this you must use a session; see
330 L<Catalyst::Plugin::Session> for a complete system integrated with
333 $c->stash->{foo} = $bar;
334 $c->stash( { moose => 'majestic', qux => 0 } );
335 $c->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref
337 # stash is automatically passed to the view for use in a template
338 $c->forward( 'MyApp::View::TT' );
345 my $stash = @_ > 1 ? {@_} : $_[0];
346 croak('stash takes a hash or hashref') unless ref $stash;
347 foreach my $key ( keys %$stash ) {
348 $c->{stash}->{$key} = $stash->{$key};
356 =head2 $c->error($error, ...)
358 =head2 $c->error($arrayref)
360 Returns an arrayref containing error messages. If Catalyst encounters an
361 error while processing a request, it stores the error in $c->error. This
362 method should only be used to store fatal error messages.
364 my @error = @{ $c->error };
368 $c->error('Something bad happened');
375 my $error = ref $_[0] eq 'ARRAY' ? $_[0] : [@_];
376 croak @$error unless ref $c;
377 push @{ $c->{error} }, @$error;
379 elsif ( defined $_[0] ) { $c->{error} = undef }
380 return $c->{error} || [];
386 Contains the return value of the last executed action.
388 =head2 $c->clear_errors
390 Clear errors. You probably don't want to clear the errors unless you are
391 implementing a custom error screen.
393 This is equivalent to running
407 my ( $c, @names ) = @_;
409 foreach my $name (@names) {
410 foreach my $component ( keys %{ $c->components } ) {
411 return $c->components->{$component} if $component =~ /$name/i;
418 # try explicit component names
420 my ( $c, @names ) = @_;
422 foreach my $try (@names) {
423 return $c->components->{$try} if ( exists $c->components->{$try} );
429 # like component, but try just these prefixes before regex searching,
430 # and do not try to return "sort keys %{ $c->components }"
432 my ( $c, $name, @prefixes ) = @_;
434 my $appclass = ref $c || $c;
436 my @names = map { "${appclass}::${_}::${name}" } @prefixes;
438 my $comp = $c->_comp_explicit(@names);
439 return $comp if defined($comp);
440 $comp = $c->_comp_search($name);
444 # Find possible names for a prefix
447 my ( $c, @prefixes ) = @_;
449 my $appclass = ref $c || $c;
451 my @pre = map { "${appclass}::${_}::" } @prefixes;
455 COMPONENT: foreach my $comp ($c->component) {
456 foreach my $p (@pre) {
457 if ($comp =~ s/^$p//) {
467 # Return a component if only one matches.
469 my ( $c, @prefixes ) = @_;
471 my $appclass = ref $c || $c;
473 my ( $comp, $rest ) =
474 map { $c->_comp_search("^${appclass}::${_}::") } @prefixes;
475 return $comp unless $rest;
478 # Filter a component before returning by calling ACCEPT_CONTEXT if available
479 sub _filter_component {
480 my ( $c, $comp, @args ) = @_;
481 if ( eval { $comp->can('ACCEPT_CONTEXT'); } ) {
482 return $comp->ACCEPT_CONTEXT( $c, @args );
484 else { return $comp }
487 =head2 COMPONENT ACCESSORS
489 =head2 $c->controller($name)
491 Gets a L<Catalyst::Controller> instance by name.
493 $c->controller('Foo')->do_stuff;
495 If the name is omitted, will return the controller for the dispatched
501 my ( $c, $name, @args ) = @_;
502 return $c->_filter_component( $c->_comp_prefixes( $name, qw/Controller C/ ),
505 return $c->component( $c->action->class );
508 =head2 $c->model($name)
510 Gets a L<Catalyst::Model> instance by name.
512 $c->model('Foo')->do_stuff;
514 Any extra arguments are directly passed to ACCEPT_CONTEXT.
516 If the name is omitted, it will look for
517 - a model object in $c->stash{current_model_instance}, then
518 - a model name in $c->stash->{current_model}, then
519 - a config setting 'default_model', or
520 - check if there is only one model, and return it if that's the case.
525 my ( $c, $name, @args ) = @_;
526 return $c->_filter_component( $c->_comp_prefixes( $name, qw/Model M/ ),
530 return $c->stash->{current_model_instance}
531 if $c->stash->{current_model_instance};
532 return $c->model( $c->stash->{current_model} )
533 if $c->stash->{current_model};
535 return $c->model( $c->config->{default_model} )
536 if $c->config->{default_model};
537 return $c->_filter_component( $c->_comp_singular(qw/Model M/) );
541 =head2 $c->controllers
543 Returns the available names which can be passed to $c->controller
549 return $c->_comp_names(qw/Controller C/);
553 =head2 $c->view($name)
555 Gets a L<Catalyst::View> instance by name.
557 $c->view('Foo')->do_stuff;
559 Any extra arguments are directly passed to ACCEPT_CONTEXT.
561 If the name is omitted, it will look for
562 - a view object in $c->stash{current_view_instance}, then
563 - a view name in $c->stash->{current_view}, then
564 - a config setting 'default_view', or
565 - check if there is only one view, and return it if that's the case.
570 my ( $c, $name, @args ) = @_;
571 return $c->_filter_component( $c->_comp_prefixes( $name, qw/View V/ ),
575 return $c->stash->{current_view_instance}
576 if $c->stash->{current_view_instance};
577 return $c->view( $c->stash->{current_view} )
578 if $c->stash->{current_view};
580 return $c->view( $c->config->{default_view} )
581 if $c->config->{default_view};
582 return $c->_filter_component( $c->_comp_singular(qw/View V/) );
587 Returns the available names which can be passed to $c->model
593 return $c->_comp_names(qw/Model M/);
599 Returns the available names which can be passed to $c->view
605 return $c->_comp_names(qw/View V/);
608 =head2 $c->comp($name)
610 =head2 $c->component($name)
612 Gets a component object by name. This method is not recommended,
613 unless you want to get a specific component by full
614 class. C<< $c->controller >>, C<< $c->model >>, and C<< $c->view >>
615 should be used instead.
626 my $appclass = ref $c || $c;
629 $name, "${appclass}::${name}",
630 map { "${appclass}::${_}::${name}" }
631 qw/Model M Controller C View V/
634 my $comp = $c->_comp_explicit(@names);
635 return $c->_filter_component( $comp, @_ ) if defined($comp);
637 $comp = $c->_comp_search($name);
638 return $c->_filter_component( $comp, @_ ) if defined($comp);
641 return sort keys %{ $c->components };
646 =head2 CLASS DATA AND HELPER CLASSES
650 Returns or takes a hashref containing the application's configuration.
652 __PACKAGE__->config( { db => 'dsn:SQLite:foo.db' } );
654 You can also use a C<YAML>, C<XML> or C<Config::General> config file
655 like myapp.yml in your applications home directory. See
656 L<Catalyst::Plugin::ConfigLoader>.
659 db: dsn:SQLite:foo.db
667 $c->log->warn("Setting config after setup has been run is not a good idea.")
668 if ( @_ and $c->setup_finished );
670 $c->NEXT::config(@_);
675 Returns the logging object instance. Unless it is already set, Catalyst
676 sets this up with a L<Catalyst::Log> object. To use your own log class,
677 set the logger with the C<< __PACKAGE__->log >> method prior to calling
678 C<< __PACKAGE__->setup >>.
680 __PACKAGE__->log( MyLogger->new );
685 $c->log->info( 'Now logging with my own logger!' );
687 Your log class should implement the methods described in
693 Overload to enable debug messages (same as -Debug option).
695 Note that this is a static method, not an accessor and should be overloaded
696 by declaring "sub debug { 1 }" in your MyApp.pm, not by calling $c->debug(1).
702 =head2 $c->dispatcher
704 Returns the dispatcher instance. Stringifies to class name. See
705 L<Catalyst::Dispatcher>.
709 Returns the engine instance. Stringifies to the class name. See
713 =head2 UTILITY METHODS
715 =head2 $c->path_to(@path)
717 Merges C<@path> with C<< $c->config->{home} >> and returns a
718 L<Path::Class::Dir> object.
722 $c->path_to( 'db', 'sqlite.db' );
727 my ( $c, @path ) = @_;
728 my $path = Path::Class::Dir->new( $c->config->{home}, @path );
729 if ( -d $path ) { return $path }
730 else { return Path::Class::File->new( $c->config->{home}, @path ) }
733 =head2 $c->plugin( $name, $class, @args )
735 Helper method for plugins. It creates a classdata accessor/mutator and
736 loads and instantiates the given class.
738 MyApp->plugin( 'prototype', 'HTML::Prototype' );
740 $c->prototype->define_javascript_functions;
745 my ( $class, $name, $plugin, @args ) = @_;
746 $class->_register_plugin( $plugin, 1 );
748 eval { $plugin->import };
749 $class->mk_classdata($name);
751 eval { $obj = $plugin->new(@args) };
754 Catalyst::Exception->throw( message =>
755 qq/Couldn't instantiate instant plugin "$plugin", "$@"/ );
759 $class->log->debug(qq/Initialized instant plugin "$plugin" as "$name"/)
765 Initializes the dispatcher and engine, loads any plugins, and loads the
766 model, view, and controller components. You may also specify an array
767 of plugins to load here, if you choose to not load them in the C<use
771 MyApp->setup( qw/-Debug/ );
776 my ( $class, @arguments ) = @_;
778 $class->log->warn("Running setup twice is not a good idea.")
779 if ( $class->setup_finished );
781 unless ( $class->isa('Catalyst') ) {
783 Catalyst::Exception->throw(
784 message => qq/'$class' does not inherit from Catalyst/ );
787 if ( $class->arguments ) {
788 @arguments = ( @arguments, @{ $class->arguments } );
794 foreach (@arguments) {
798 ( $flags->{log} ) ? 'debug,' . $flags->{log} : 'debug';
800 elsif (/^-(\w+)=?(.*)$/) {
801 $flags->{ lc $1 } = $2;
804 push @{ $flags->{plugins} }, $_;
808 $class->setup_home( delete $flags->{home} );
810 $class->setup_log( delete $flags->{log} );
811 $class->setup_plugins( delete $flags->{plugins} );
812 $class->setup_dispatcher( delete $flags->{dispatcher} );
813 $class->setup_engine( delete $flags->{engine} );
815 for my $flag ( sort keys %{$flags} ) {
817 if ( my $code = $class->can( 'setup_' . $flag ) ) {
818 &$code( $class, delete $flags->{$flag} );
821 $class->log->warn(qq/Unknown flag "$flag"/);
825 eval { require Catalyst::Devel; };
826 if( !$@ && $ENV{CATALYST_SCRIPT_GEN} && ( $ENV{CATALYST_SCRIPT_GEN} < $Catalyst::Devel::CATALYST_SCRIPT_GEN ) ) {
827 $class->log->warn(<<"EOF");
828 You are running an old script!
830 Please update by running (this will overwrite existing files):
831 catalyst.pl -force -scripts $class
833 or (this will not overwrite existing files):
834 catalyst.pl -scripts $class
839 if ( $class->debug ) {
840 my @plugins = map { "$_ " . ( $_->VERSION || '' ) } $class->registered_plugins;
843 my $t = Text::SimpleTable->new(74);
844 $t->row($_) for @plugins;
845 $class->log->debug( "Loaded plugins:\n" . $t->draw . "\n" );
848 my $dispatcher = $class->dispatcher;
849 my $engine = $class->engine;
850 my $home = $class->config->{home};
852 $class->log->debug(qq/Loaded dispatcher "$dispatcher"/);
853 $class->log->debug(qq/Loaded engine "$engine"/);
857 ? $class->log->debug(qq/Found home "$home"/)
858 : $class->log->debug(qq/Home "$home" doesn't exist/)
859 : $class->log->debug(q/Couldn't find home/);
864 no warnings qw/redefine/;
865 local *setup = sub { };
869 # Initialize our data structure
870 $class->components( {} );
872 $class->setup_components;
874 if ( $class->debug ) {
875 my $t = Text::SimpleTable->new( [ 63, 'Class' ], [ 8, 'Type' ] );
876 for my $comp ( sort keys %{ $class->components } ) {
877 my $type = ref $class->components->{$comp} ? 'instance' : 'class';
878 $t->row( $comp, $type );
880 $class->log->debug( "Loaded components:\n" . $t->draw . "\n" )
881 if ( keys %{ $class->components } );
884 # Add our self to components, since we are also a component
885 $class->components->{$class} = $class;
887 $class->setup_actions;
889 if ( $class->debug ) {
890 my $name = $class->config->{name} || 'Application';
891 $class->log->info("$name powered by Catalyst $Catalyst::VERSION");
893 $class->log->_flush() if $class->log->can('_flush');
895 $class->setup_finished(1);
898 =head2 $c->uri_for( $path, @args?, \%query_values? )
900 Merges path with C<< $c->request->base >> for absolute URIs and with
901 C<< $c->namespace >> for relative URIs, then returns a normalized L<URI>
902 object. If any args are passed, they are added at the end of the path.
903 If the last argument to C<uri_for> is a hash reference, it is assumed to
904 contain GET parameter key/value pairs, which will be appended to the URI
907 Instead of C<$path>, you can also optionally pass a C<$action> object
908 which will be resolved to a path using
909 C<< $c->dispatcher->uri_for_action >>; if the first element of
910 C<@args> is an arrayref it is treated as a list of captures to be passed
911 to C<uri_for_action>.
916 my ( $c, $path, @args ) = @_;
917 my $base = $c->request->base->clone;
918 my $basepath = $base->path;
919 $basepath =~ s/\/$//;
921 my $namespace = $c->namespace || '';
923 if ( Scalar::Util::blessed($path) ) { # action object
924 my $captures = ( scalar @args && ref $args[0] eq 'ARRAY'
927 $path = $c->dispatcher->uri_for_action($path, $captures);
928 return undef unless defined($path);
929 $path = '/' if $path eq '';
932 # massage namespace, empty if absolute path
933 $namespace =~ s/^\/// if $namespace;
934 $namespace .= '/' if $namespace;
936 $namespace = '' if $path =~ /^\//;
941 ( scalar @args && ref $args[$#args] eq 'HASH' ? pop @args : {} );
943 for my $value ( values %$params ) {
944 next unless defined $value;
945 for ( ref $value eq 'ARRAY' ? @$value : $value ) {
951 # join args with '/', or a blank string
952 my $args = ( scalar @args ? '/' . join( '/', map {s/\?/%3F/g; $_} @args ) : '' );
953 $args =~ s/^\/// unless $path;
955 URI->new_abs( URI->new_abs( "$path$args", "$basepath$namespace" ), $base )
957 $res->query_form(%$params);
961 =head2 $c->welcome_message
963 Returns the Catalyst welcome HTML page.
967 sub welcome_message {
969 my $name = $c->config->{name};
970 my $logo = $c->uri_for('/static/images/catalyst_logo.png');
971 my $prefix = Catalyst::Utils::appprefix( ref $c );
972 $c->response->content_type('text/html; charset=utf-8');
974 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
975 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
976 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
978 <meta http-equiv="Content-Language" content="en" />
979 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
980 <title>$name on Catalyst $VERSION</title>
981 <style type="text/css">
984 background-color: #eee;
993 background-color: #ccc;
994 border: 1px solid #aaa;
999 font-family: verdana, tahoma, sans-serif;
1002 font-family: verdana, tahoma, sans-serif;
1005 text-decoration: none;
1007 border-bottom: 1px dotted #bbb;
1009 :link:hover, :visited:hover {
1022 background-color: #fff;
1023 border: 1px solid #aaa;
1027 font-weight: normal;
1049 <h1><span id="appname">$name</span> on <a href="http://catalyst.perl.org">Catalyst</a>
1054 <img src="$logo" alt="Catalyst Logo" />
1056 <p>Welcome to the world of Catalyst.
1057 This <a href="http://en.wikipedia.org/wiki/MVC">MVC</a>
1058 framework will make web development something you had
1059 never expected it to be: Fun, rewarding, and quick.</p>
1060 <h2>What to do now?</h2>
1061 <p>That really depends on what <b>you</b> want to do.
1062 We do, however, provide you with a few starting points.</p>
1063 <p>If you want to jump right into web development with Catalyst
1064 you might want want to start with a tutorial.</p>
1065 <pre>perldoc <a href="http://cpansearch.perl.org/dist/Catalyst-Manual/lib/Catalyst/Manual/Tutorial.pod">Catalyst::Manual::Tutorial</a></code>
1067 <p>Afterwards you can go on to check out a more complete look at our features.</p>
1069 <code>perldoc <a href="http://cpansearch.perl.org/dist/Catalyst-Manual/lib/Catalyst/Manual/Intro.pod">Catalyst::Manual::Intro</a>
1070 <!-- Something else should go here, but the Catalyst::Manual link seems unhelpful -->
1072 <h2>What to do next?</h2>
1073 <p>Next it's time to write an actual application. Use the
1074 helper scripts to generate <a href="http://cpansearch.perl.org/search?query=Catalyst%3A%3AController%3A%3A&mode=all">controllers</a>,
1075 <a href="http://cpansearch.perl.org/search?query=Catalyst%3A%3AModel%3A%3A&mode=all">models</a>, and
1076 <a href="http://cpansearch.perl.org/search?query=Catalyst%3A%3AView%3A%3A&mode=all">views</a>;
1077 they can save you a lot of work.</p>
1078 <pre><code>script/${prefix}_create.pl -help</code></pre>
1079 <p>Also, be sure to check out the vast and growing
1080 collection of <a href="http://cpansearch.perl.org/search?query=Catalyst%3A%3APlugin%3A%3A&mode=all">plugins for Catalyst on CPAN</a>;
1081 you are likely to find what you need there.
1085 <p>Catalyst has a very active community. Here are the main places to
1086 get in touch with us.</p>
1089 <a href="http://dev.catalyst.perl.org">Wiki</a>
1092 <a href="http://lists.rawmode.org/mailman/listinfo/catalyst">Mailing-List</a>
1095 <a href="irc://irc.perl.org/catalyst">IRC channel #catalyst on irc.perl.org</a>
1098 <h2>In conclusion</h2>
1099 <p>The Catalyst team hopes you will enjoy using Catalyst as much
1100 as we enjoyed making it. Please contact us if you have ideas
1101 for improvement or other feedback.</p>
1109 =head1 INTERNAL METHODS
1111 These methods are not meant to be used by end users.
1113 =head2 $c->components
1115 Returns a hash of components.
1117 =head2 $c->context_class
1119 Returns or sets the context class.
1123 Returns a hashref containing coderefs and execution counts (needed for
1124 deep recursion detection).
1128 Returns the number of actions on the current internal execution stack.
1132 Dispatches a request to actions.
1136 sub dispatch { my $c = shift; $c->dispatcher->dispatch( $c, @_ ) }
1138 =head2 $c->dispatcher_class
1140 Returns or sets the dispatcher class.
1142 =head2 $c->dump_these
1144 Returns a list of 2-element array references (name, structure) pairs
1145 that will be dumped on the error page in debug mode.
1151 [ Request => $c->req ],
1152 [ Response => $c->res ],
1153 [ Stash => $c->stash ],
1154 [ Config => $c->config ];
1157 =head2 $c->engine_class
1159 Returns or sets the engine class.
1161 =head2 $c->execute( $class, $coderef )
1163 Execute a coderef in given class and catch exceptions. Errors are available
1169 my ( $c, $class, $code ) = @_;
1170 $class = $c->component($class) || $class;
1173 if ( $c->depth >= $RECURSION ) {
1174 my $action = "$code";
1175 $action = "/$action" unless $action =~ /->/;
1176 my $error = qq/Deep recursion detected calling "$action"/;
1177 $c->log->error($error);
1183 my $stats_info = $c->_stats_start_execute( $code ) if $c->debug;
1185 push( @{ $c->stack }, $code );
1187 eval { $c->state( &$code( $class, $c, @{ $c->req->args } ) || 0 ) };
1189 $c->_stats_finish_execute( $stats_info ) if $c->debug and $stats_info;
1191 my $last = pop( @{ $c->stack } );
1193 if ( my $error = $@ ) {
1194 if ( !ref($error) and $error eq $DETACH ) { die $DETACH if $c->depth > 1 }
1196 unless ( ref $error ) {
1197 no warnings 'uninitialized';
1199 my $class = $last->class;
1200 my $name = $last->name;
1201 $error = qq/Caught exception in $class->$name "$error"/;
1210 sub _stats_start_execute {
1211 my ( $c, $code ) = @_;
1213 return if ( ( $code->name =~ /^_.*/ )
1214 && ( !$c->config->{show_internal_actions} ) );
1216 $c->counter->{"$code"}++;
1218 my $action = "$code";
1219 $action = "/$action" unless $action =~ /->/;
1221 # determine if the call was the result of a forward
1222 # this is done by walking up the call stack and looking for a calling
1223 # sub of Catalyst::forward before the eval
1225 for my $index ( 2 .. 11 ) {
1227 if ( ( caller($index) )[0] eq 'Catalyst'
1228 && ( caller($index) )[3] eq '(eval)' );
1230 if ( ( caller($index) )[3] =~ /forward$/ ) {
1231 $callsub = ( caller($index) )[3];
1232 $action = "-> $action";
1237 my $node = Tree::Simple->new(
1240 elapsed => undef, # to be filled in later
1244 $node->setUID( "$code" . $c->counter->{"$code"} );
1246 # is this a root-level call or a forwarded call?
1247 if ( $callsub =~ /forward$/ ) {
1249 # forward, locate the caller
1250 if ( my $parent = $c->stack->[-1] ) {
1251 my $visitor = Tree::Simple::Visitor::FindByUID->new;
1252 $visitor->searchForUID(
1253 "$parent" . $c->counter->{"$parent"} );
1254 $c->stats->accept($visitor);
1255 if ( my $result = $visitor->getResult ) {
1256 $result->addChild($node);
1261 # forward with no caller may come from a plugin
1262 $c->stats->addChild($node);
1268 $c->stats->addChild($node);
1272 start => [gettimeofday],
1277 sub _stats_finish_execute {
1278 my ( $c, $info ) = @_;
1279 my $elapsed = tv_interval $info->{start};
1280 my $value = $info->{node}->getNodeValue;
1281 $value->{elapsed} = sprintf( '%fs', $elapsed );
1284 =head2 $c->_localize_fields( sub { }, \%keys );
1288 sub _localize_fields {
1289 my ( $c, $localized, $code ) = ( @_ );
1291 my $request = delete $localized->{request} || {};
1292 my $response = delete $localized->{response} || {};
1294 local @{ $c }{ keys %$localized } = values %$localized;
1295 local @{ $c->request }{ keys %$request } = values %$request;
1296 local @{ $c->response }{ keys %$response } = values %$response;
1303 Finalizes the request.
1310 for my $error ( @{ $c->error } ) {
1311 $c->log->error($error);
1314 # Allow engine to handle finalize flow (for POE)
1315 if ( $c->engine->can('finalize') ) {
1316 $c->engine->finalize($c);
1320 $c->finalize_uploads;
1323 if ( $#{ $c->error } >= 0 ) {
1327 $c->finalize_headers;
1330 if ( $c->request->method eq 'HEAD' ) {
1331 $c->response->body('');
1338 my $elapsed = sprintf '%f', tv_interval($c->stats->getNodeValue);
1339 my $av = sprintf '%.3f', ( $elapsed == 0 ? '??' : ( 1 / $elapsed ) );
1341 my $t = Text::SimpleTable->new( [ 62, 'Action' ], [ 9, 'Time' ] );
1342 $c->stats->traverse(
1345 my $stat = $action->getNodeValue;
1346 $t->row( ( q{ } x $action->getDepth ) . $stat->{action} . $stat->{comment},
1347 $stat->{elapsed} || '??' );
1352 "Request took ${elapsed}s ($av/s)\n" . $t->draw . "\n" );
1355 return $c->response->status;
1358 =head2 $c->finalize_body
1364 sub finalize_body { my $c = shift; $c->engine->finalize_body( $c, @_ ) }
1366 =head2 $c->finalize_cookies
1372 sub finalize_cookies { my $c = shift; $c->engine->finalize_cookies( $c, @_ ) }
1374 =head2 $c->finalize_error
1380 sub finalize_error { my $c = shift; $c->engine->finalize_error( $c, @_ ) }
1382 =head2 $c->finalize_headers
1388 sub finalize_headers {
1391 # Check if we already finalized headers
1392 return if $c->response->{_finalized_headers};
1395 if ( my $location = $c->response->redirect ) {
1396 $c->log->debug(qq/Redirecting to "$location"/) if $c->debug;
1397 $c->response->header( Location => $location );
1399 if ( !$c->response->body ) {
1400 # Add a default body if none is already present
1402 "<p>This item has moved <a href=\"$location\">here</a>.</p>"
1408 if ( $c->response->body && !$c->response->content_length ) {
1410 # get the length from a filehandle
1411 if ( blessed( $c->response->body ) && $c->response->body->can('read') )
1413 if ( my $stat = stat $c->response->body ) {
1414 $c->response->content_length( $stat->size );
1417 $c->log->warn('Serving filehandle without a content-length');
1421 $c->response->content_length( bytes::length( $c->response->body ) );
1426 if ( $c->response->status =~ /^(1\d\d|[23]04)$/ ) {
1427 $c->response->headers->remove_header("Content-Length");
1428 $c->response->body('');
1431 $c->finalize_cookies;
1433 $c->engine->finalize_headers( $c, @_ );
1436 $c->response->{_finalized_headers} = 1;
1439 =head2 $c->finalize_output
1441 An alias for finalize_body.
1443 =head2 $c->finalize_read
1445 Finalizes the input after reading is complete.
1449 sub finalize_read { my $c = shift; $c->engine->finalize_read( $c, @_ ) }
1451 =head2 $c->finalize_uploads
1453 Finalizes uploads. Cleans up any temporary files.
1457 sub finalize_uploads { my $c = shift; $c->engine->finalize_uploads( $c, @_ ) }
1459 =head2 $c->get_action( $action, $namespace )
1461 Gets an action in a given namespace.
1465 sub get_action { my $c = shift; $c->dispatcher->get_action(@_) }
1467 =head2 $c->get_actions( $action, $namespace )
1469 Gets all actions of a given name in a namespace and all parent
1474 sub get_actions { my $c = shift; $c->dispatcher->get_actions( $c, @_ ) }
1476 =head2 $c->handle_request( $class, @arguments )
1478 Called to handle each HTTP request.
1482 sub handle_request {
1483 my ( $class, @arguments ) = @_;
1485 # Always expect worst case!
1488 if ($class->debug) {
1489 my $secs = time - $START || 1;
1490 my $av = sprintf '%.3f', $COUNT / $secs;
1491 my $time = localtime time;
1492 $class->log->info("*** Request $COUNT ($av/s) [$$] [$time] ***");
1495 my $c = $class->prepare(@arguments);
1497 $status = $c->finalize;
1500 if ( my $error = $@ ) {
1502 $class->log->error(qq/Caught exception in engine "$error"/);
1506 $class->log->_flush() if $class->log->can('_flush');
1510 =head2 $c->prepare( @arguments )
1512 Creates a Catalyst context from an engine-specific request (Apache, CGI,
1518 my ( $class, @arguments ) = @_;
1520 $class->context_class( ref $class || $class ) unless $class->context_class;
1521 my $c = $class->context_class->new(
1525 request => $class->request_class->new(
1528 body_parameters => {},
1530 headers => HTTP::Headers->new,
1532 query_parameters => {},
1538 response => $class->response_class->new(
1542 headers => HTTP::Headers->new(),
1552 $c->stats(Tree::Simple->new([gettimeofday]));
1553 $c->res->headers->header( 'X-Catalyst' => $Catalyst::VERSION );
1556 # For on-demand data
1557 $c->request->{_context} = $c;
1558 $c->response->{_context} = $c;
1559 weaken( $c->request->{_context} );
1560 weaken( $c->response->{_context} );
1562 # Allow engine to direct the prepare flow (for POE)
1563 if ( $c->engine->can('prepare') ) {
1564 $c->engine->prepare( $c, @arguments );
1567 $c->prepare_request(@arguments);
1568 $c->prepare_connection;
1569 $c->prepare_query_parameters;
1570 $c->prepare_headers;
1571 $c->prepare_cookies;
1575 $c->prepare_body unless $c->config->{parse_on_demand};
1578 my $method = $c->req->method || '';
1579 my $path = $c->req->path || '/';
1580 my $address = $c->req->address || '';
1582 $c->log->debug(qq/"$method" request for "$path" from "$address"/)
1590 =head2 $c->prepare_action
1592 Prepares action. See L<Catalyst::Dispatcher>.
1596 sub prepare_action { my $c = shift; $c->dispatcher->prepare_action( $c, @_ ) }
1598 =head2 $c->prepare_body
1600 Prepares message body.
1607 # Do we run for the first time?
1608 return if defined $c->request->{_body};
1610 # Initialize on-demand data
1611 $c->engine->prepare_body( $c, @_ );
1612 $c->prepare_parameters;
1613 $c->prepare_uploads;
1615 if ( $c->debug && keys %{ $c->req->body_parameters } ) {
1616 my $t = Text::SimpleTable->new( [ 35, 'Parameter' ], [ 36, 'Value' ] );
1617 for my $key ( sort keys %{ $c->req->body_parameters } ) {
1618 my $param = $c->req->body_parameters->{$key};
1619 my $value = defined($param) ? $param : '';
1621 ref $value eq 'ARRAY' ? ( join ', ', @$value ) : $value );
1623 $c->log->debug( "Body Parameters are:\n" . $t->draw );
1627 =head2 $c->prepare_body_chunk( $chunk )
1629 Prepares a chunk of data before sending it to L<HTTP::Body>.
1631 See L<Catalyst::Engine>.
1635 sub prepare_body_chunk {
1637 $c->engine->prepare_body_chunk( $c, @_ );
1640 =head2 $c->prepare_body_parameters
1642 Prepares body parameters.
1646 sub prepare_body_parameters {
1648 $c->engine->prepare_body_parameters( $c, @_ );
1651 =head2 $c->prepare_connection
1653 Prepares connection.
1657 sub prepare_connection {
1659 $c->engine->prepare_connection( $c, @_ );
1662 =head2 $c->prepare_cookies
1668 sub prepare_cookies { my $c = shift; $c->engine->prepare_cookies( $c, @_ ) }
1670 =head2 $c->prepare_headers
1676 sub prepare_headers { my $c = shift; $c->engine->prepare_headers( $c, @_ ) }
1678 =head2 $c->prepare_parameters
1680 Prepares parameters.
1684 sub prepare_parameters {
1686 $c->prepare_body_parameters;
1687 $c->engine->prepare_parameters( $c, @_ );
1690 =head2 $c->prepare_path
1692 Prepares path and base.
1696 sub prepare_path { my $c = shift; $c->engine->prepare_path( $c, @_ ) }
1698 =head2 $c->prepare_query_parameters
1700 Prepares query parameters.
1704 sub prepare_query_parameters {
1707 $c->engine->prepare_query_parameters( $c, @_ );
1709 if ( $c->debug && keys %{ $c->request->query_parameters } ) {
1710 my $t = Text::SimpleTable->new( [ 35, 'Parameter' ], [ 36, 'Value' ] );
1711 for my $key ( sort keys %{ $c->req->query_parameters } ) {
1712 my $param = $c->req->query_parameters->{$key};
1713 my $value = defined($param) ? $param : '';
1715 ref $value eq 'ARRAY' ? ( join ', ', @$value ) : $value );
1717 $c->log->debug( "Query Parameters are:\n" . $t->draw );
1721 =head2 $c->prepare_read
1723 Prepares the input for reading.
1727 sub prepare_read { my $c = shift; $c->engine->prepare_read( $c, @_ ) }
1729 =head2 $c->prepare_request
1731 Prepares the engine request.
1735 sub prepare_request { my $c = shift; $c->engine->prepare_request( $c, @_ ) }
1737 =head2 $c->prepare_uploads
1743 sub prepare_uploads {
1746 $c->engine->prepare_uploads( $c, @_ );
1748 if ( $c->debug && keys %{ $c->request->uploads } ) {
1749 my $t = Text::SimpleTable->new(
1750 [ 12, 'Parameter' ],
1755 for my $key ( sort keys %{ $c->request->uploads } ) {
1756 my $upload = $c->request->uploads->{$key};
1757 for my $u ( ref $upload eq 'ARRAY' ? @{$upload} : ($upload) ) {
1758 $t->row( $key, $u->filename, $u->type, $u->size );
1761 $c->log->debug( "File Uploads are:\n" . $t->draw );
1765 =head2 $c->prepare_write
1767 Prepares the output for writing.
1771 sub prepare_write { my $c = shift; $c->engine->prepare_write( $c, @_ ) }
1773 =head2 $c->request_class
1775 Returns or sets the request class.
1777 =head2 $c->response_class
1779 Returns or sets the response class.
1781 =head2 $c->read( [$maxlength] )
1783 Reads a chunk of data from the request body. This method is designed to
1784 be used in a while loop, reading C<$maxlength> bytes on every call.
1785 C<$maxlength> defaults to the size of the request if not specified.
1787 You have to set C<< MyApp->config->{parse_on_demand} >> to use this
1792 sub read { my $c = shift; return $c->engine->read( $c, @_ ) }
1800 sub run { my $c = shift; return $c->engine->run( $c, @_ ) }
1802 =head2 $c->set_action( $action, $code, $namespace, $attrs )
1804 Sets an action in a given namespace.
1808 sub set_action { my $c = shift; $c->dispatcher->set_action( $c, @_ ) }
1810 =head2 $c->setup_actions($component)
1812 Sets up actions for a component.
1816 sub setup_actions { my $c = shift; $c->dispatcher->setup_actions( $c, @_ ) }
1818 =head2 $c->setup_components
1820 Sets up components. Specify a C<setup_components> config option to pass
1821 additional options directly to L<Module::Pluggable>. To add additional
1822 search paths, specify a key named C<search_extra> as an array
1823 reference. Items in the array beginning with C<::> will have the
1824 application class name prepended to them.
1828 sub setup_components {
1831 my @paths = qw( ::Controller ::C ::Model ::M ::View ::V );
1832 my $config = $class->config->{ setup_components };
1833 my $extra = delete $config->{ search_extra } || [];
1835 push @paths, @$extra;
1837 my $locator = Module::Pluggable::Object->new(
1838 search_path => [ map { s/^(?=::)/$class/; $_; } @paths ],
1842 for my $component ( sort { length $a <=> length $b } $locator->plugins ) {
1843 Catalyst::Utils::ensure_class_loaded( $component, { ignore_loaded => 1 } );
1845 my $module = $class->setup_component( $component );
1847 $component => $module,
1849 $_ => $class->setup_component( $_ )
1850 } Devel::InnerPackage::list_packages( $component )
1853 for my $key ( keys %modules ) {
1854 $class->components->{ $key } = $modules{ $key };
1859 =head2 $c->setup_component
1863 sub setup_component {
1864 my( $class, $component ) = @_;
1866 unless ( $component->can( 'COMPONENT' ) ) {
1870 my $suffix = Catalyst::Utils::class2classsuffix( $component );
1871 my $config = $class->config->{ $suffix } || {};
1873 my $instance = eval { $component->COMPONENT( $class, $config ); };
1875 if ( my $error = $@ ) {
1877 Catalyst::Exception->throw(
1878 message => qq/Couldn't instantiate component "$component", "$error"/
1882 Catalyst::Exception->throw(
1884 qq/Couldn't instantiate component "$component", "COMPONENT() didn't return an object-like value"/
1885 ) unless eval { $instance->can( 'can' ) };
1890 =head2 $c->setup_dispatcher
1896 sub setup_dispatcher {
1897 my ( $class, $dispatcher ) = @_;
1900 $dispatcher = 'Catalyst::Dispatcher::' . $dispatcher;
1903 if ( $ENV{CATALYST_DISPATCHER} ) {
1904 $dispatcher = 'Catalyst::Dispatcher::' . $ENV{CATALYST_DISPATCHER};
1907 if ( $ENV{ uc($class) . '_DISPATCHER' } ) {
1909 'Catalyst::Dispatcher::' . $ENV{ uc($class) . '_DISPATCHER' };
1912 unless ($dispatcher) {
1913 $dispatcher = $class->dispatcher_class;
1916 unless (Class::Inspector->loaded($dispatcher)) {
1917 require Class::Inspector->filename($dispatcher);
1920 # dispatcher instance
1921 $class->dispatcher( $dispatcher->new );
1924 =head2 $c->setup_engine
1931 my ( $class, $engine ) = @_;
1934 $engine = 'Catalyst::Engine::' . $engine;
1937 if ( $ENV{CATALYST_ENGINE} ) {
1938 $engine = 'Catalyst::Engine::' . $ENV{CATALYST_ENGINE};
1941 if ( $ENV{ uc($class) . '_ENGINE' } ) {
1942 $engine = 'Catalyst::Engine::' . $ENV{ uc($class) . '_ENGINE' };
1945 if ( $ENV{MOD_PERL} ) {
1947 # create the apache method
1950 *{"$class\::apache"} = sub { shift->engine->apache };
1953 my ( $software, $version ) =
1954 $ENV{MOD_PERL} =~ /^(\S+)\/(\d+(?:[\.\_]\d+)+)/;
1957 $version =~ s/(\.[^.]+)\./$1/g;
1959 if ( $software eq 'mod_perl' ) {
1963 if ( $version >= 1.99922 ) {
1964 $engine = 'Catalyst::Engine::Apache2::MP20';
1967 elsif ( $version >= 1.9901 ) {
1968 $engine = 'Catalyst::Engine::Apache2::MP19';
1971 elsif ( $version >= 1.24 ) {
1972 $engine = 'Catalyst::Engine::Apache::MP13';
1976 Catalyst::Exception->throw( message =>
1977 qq/Unsupported mod_perl version: $ENV{MOD_PERL}/ );
1982 # install the correct mod_perl handler
1983 if ( $version >= 1.9901 ) {
1984 *handler = sub : method {
1985 shift->handle_request(@_);
1989 *handler = sub ($$) { shift->handle_request(@_) };
1994 elsif ( $software eq 'Zeus-Perl' ) {
1995 $engine = 'Catalyst::Engine::Zeus';
1999 Catalyst::Exception->throw(
2000 message => qq/Unsupported mod_perl: $ENV{MOD_PERL}/ );
2005 $engine = $class->engine_class;
2008 unless (Class::Inspector->loaded($engine)) {
2009 require Class::Inspector->filename($engine);
2012 # check for old engines that are no longer compatible
2014 if ( $engine->isa('Catalyst::Engine::Apache')
2015 && !Catalyst::Engine::Apache->VERSION )
2020 elsif ( $engine->isa('Catalyst::Engine::Server::Base')
2021 && Catalyst::Engine::Server->VERSION le '0.02' )
2026 elsif ($engine->isa('Catalyst::Engine::HTTP::POE')
2027 && $engine->VERSION eq '0.01' )
2032 elsif ($engine->isa('Catalyst::Engine::Zeus')
2033 && $engine->VERSION eq '0.01' )
2039 Catalyst::Exception->throw( message =>
2040 qq/Engine "$engine" is not supported by this version of Catalyst/
2045 $class->engine( $engine->new );
2048 =head2 $c->setup_home
2050 Sets up the home directory.
2055 my ( $class, $home ) = @_;
2057 if ( $ENV{CATALYST_HOME} ) {
2058 $home = $ENV{CATALYST_HOME};
2061 if ( $ENV{ uc($class) . '_HOME' } ) {
2063 $home = $ENV{ uc($class) . '_HOME' };
2067 $home = Catalyst::Utils::home($class);
2071 $class->config->{home} ||= $home;
2072 $class->config->{root} ||= Path::Class::Dir->new($home)->subdir('root');
2076 =head2 $c->setup_log
2083 my ( $class, $debug ) = @_;
2085 unless ( $class->log ) {
2086 $class->log( Catalyst::Log->new );
2089 my $app_flag = Catalyst::Utils::class2env($class) . '_DEBUG';
2092 ( defined( $ENV{CATALYST_DEBUG} ) || defined( $ENV{$app_flag} ) )
2093 ? ( $ENV{CATALYST_DEBUG} || $ENV{$app_flag} )
2098 *{"$class\::debug"} = sub { 1 };
2099 $class->log->debug('Debug messages enabled');
2103 =head2 $c->setup_plugins
2109 =head2 $c->registered_plugins
2111 Returns a sorted list of the plugins which have either been stated in the
2112 import list or which have been added via C<< MyApp->plugin(@args); >>.
2114 If passed a given plugin name, it will report a boolean value indicating
2115 whether or not that plugin is loaded. A fully qualified name is required if
2116 the plugin name does not begin with C<Catalyst::Plugin::>.
2118 if ($c->registered_plugins('Some::Plugin')) {
2126 sub registered_plugins {
2128 return sort keys %{ $proto->_plugins } unless @_;
2130 return 1 if exists $proto->_plugins->{$plugin};
2131 return exists $proto->_plugins->{"Catalyst::Plugin::$plugin"};
2134 sub _register_plugin {
2135 my ( $proto, $plugin, $instant ) = @_;
2136 my $class = ref $proto || $proto;
2138 unless (Class::Inspector->loaded($plugin)) {
2139 require Class::Inspector->filename($plugin);
2142 $proto->_plugins->{$plugin} = 1;
2145 unshift @{"$class\::ISA"}, $plugin;
2151 my ( $class, $plugins ) = @_;
2153 $class->_plugins( {} ) unless $class->_plugins;
2155 for my $plugin ( reverse @$plugins ) {
2157 unless ( $plugin =~ s/\A\+// ) {
2158 $plugin = "Catalyst::Plugin::$plugin";
2161 $class->_register_plugin($plugin);
2168 Returns an arrayref of the internal execution stack (actions that are
2169 currently executing).
2171 =head2 $c->write( $data )
2173 Writes $data to the output stream. When using this method directly, you
2174 will need to manually set the C<Content-Length> header to the length of
2175 your output data, if known.
2182 # Finalize headers if someone manually writes output
2183 $c->finalize_headers;
2185 return $c->engine->write( $c, @_ );
2190 Returns the Catalyst version number. Mostly useful for "powered by"
2191 messages in template systems.
2195 sub version { return $Catalyst::VERSION }
2197 =head1 INTERNAL ACTIONS
2199 Catalyst uses internal actions like C<_DISPATCH>, C<_BEGIN>, C<_AUTO>,
2200 C<_ACTION>, and C<_END>. These are by default not shown in the private
2201 action table, but you can make them visible with a config parameter.
2203 MyApp->config->{show_internal_actions} = 1;
2205 =head1 CASE SENSITIVITY
2207 By default Catalyst is not case sensitive, so C<MyApp::C::FOO::Bar> is
2208 mapped to C</foo/bar>. You can activate case sensitivity with a config
2211 MyApp->config->{case_sensitive} = 1;
2213 This causes C<MyApp::C::Foo::Bar> to map to C</Foo/Bar>.
2215 =head1 ON-DEMAND PARSER
2217 The request body is usually parsed at the beginning of a request,
2218 but if you want to handle input yourself or speed things up a bit,
2219 you can enable on-demand parsing with a config parameter.
2221 MyApp->config->{parse_on_demand} = 1;
2223 =head1 PROXY SUPPORT
2225 Many production servers operate using the common double-server approach,
2226 with a lightweight frontend web server passing requests to a larger
2227 backend server. An application running on the backend server must deal
2228 with two problems: the remote user always appears to be C<127.0.0.1> and
2229 the server's hostname will appear to be C<localhost> regardless of the
2230 virtual host that the user connected through.
2232 Catalyst will automatically detect this situation when you are running
2233 the frontend and backend servers on the same machine. The following
2234 changes are made to the request.
2236 $c->req->address is set to the user's real IP address, as read from
2237 the HTTP X-Forwarded-For header.
2239 The host value for $c->req->base and $c->req->uri is set to the real
2240 host, as read from the HTTP X-Forwarded-Host header.
2242 Obviously, your web server must support these headers for this to work.
2244 In a more complex server farm environment where you may have your
2245 frontend proxy server(s) on different machines, you will need to set a
2246 configuration option to tell Catalyst to read the proxied data from the
2249 MyApp->config->{using_frontend_proxy} = 1;
2251 If you do not wish to use the proxy support at all, you may set:
2253 MyApp->config->{ignore_frontend_proxy} = 1;
2255 =head1 THREAD SAFETY
2257 Catalyst has been tested under Apache 2's threading C<mpm_worker>,
2258 C<mpm_winnt>, and the standalone forking HTTP server on Windows. We
2259 believe the Catalyst core to be thread-safe.
2261 If you plan to operate in a threaded environment, remember that all other
2262 modules you are using must also be thread-safe. Some modules, most notably
2263 L<DBD::SQLite>, are not thread-safe.
2269 Join #catalyst on irc.perl.org.
2273 http://lists.rawmode.org/mailman/listinfo/catalyst
2274 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
2278 http://catalyst.perl.org
2282 http://dev.catalyst.perl.org
2286 =head2 L<Task::Catalyst> - All you need to start with Catalyst
2288 =head2 L<Catalyst::Manual> - The Catalyst Manual
2290 =head2 L<Catalyst::Component>, L<Catalyst::Base> - Base classes for components
2292 =head2 L<Catalyst::Engine> - Core engine
2294 =head2 L<Catalyst::Log> - Log class.
2296 =head2 L<Catalyst::Request> - Request object
2298 =head2 L<Catalyst::Response> - Response object
2300 =head2 L<Catalyst::Test> - The test suite.
2372 Sebastian Riedel, C<sri@oook.de>
2376 This library is free software, you can redistribute it and/or modify it under
2377 the same terms as Perl itself.