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;
27 use Carp qw/croak carp/;
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.7008';
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 ) = @_;
918 if ( Scalar::Util::blessed($path) ) { # action object
919 my $captures = ( scalar @args && ref $args[0] eq 'ARRAY'
922 $path = $c->dispatcher->uri_for_action($path, $captures);
923 return undef unless defined($path);
924 $path = '/' if $path eq '';
927 undef($path) if (defined $path && $path eq '');
930 ( scalar @args && ref $args[$#args] eq 'HASH' ? pop @args : {} );
932 s/([^$URI::uric])/$URI::Escape::escapes{$1}/go for @args;
934 unshift(@args, $path);
936 unless (defined $path && $path =~ s!^/!!) { # in-place strip
937 my $namespace = $c->namespace;
938 if (defined $path) { # cheesy hack to handle path '../foo'
939 $namespace =~ s{(?:^|/)[^/]+$}{} while $args[0] =~ s{^\.\./}{};
941 unshift(@args, $namespace || '');
944 # join args with '/', or a blank string
945 my $args = join('/', grep { defined($_) } @args);
946 $args =~ s/\?/%3F/g; # STUPID STUPID SPECIAL CASE
948 my $base = $c->req->base;
949 my $class = ref($base);
950 $base =~ s{(?<!/)$}{/};
954 if (my @keys = keys %$params) {
955 # somewhat lifted from URI::_query's query_form
956 $query = '?'.join('&', map {
957 s/([;\/?:@&=+,\$\[\]%])/$URI::Escape::escapes{$1}/go;
960 my $val = $params->{$_};
961 $val = '' unless defined $val;
965 # using the URI::Escape pattern here so utf8 chars survive
966 s/([^A-Za-z0-9\-_.!~*'() ])/$URI::Escape::escapes{$1}/go;
968 "${key}=$_"; } ( ref $val eq 'ARRAY' ? @$val : $val ));
972 my $res = bless(\"${base}${args}${query}", $class);
976 =head2 $c->welcome_message
978 Returns the Catalyst welcome HTML page.
982 sub welcome_message {
984 my $name = $c->config->{name};
985 my $logo = $c->uri_for('/static/images/catalyst_logo.png');
986 my $prefix = Catalyst::Utils::appprefix( ref $c );
987 $c->response->content_type('text/html; charset=utf-8');
989 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
990 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
991 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
993 <meta http-equiv="Content-Language" content="en" />
994 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
995 <title>$name on Catalyst $VERSION</title>
996 <style type="text/css">
999 background-color: #eee;
1006 margin-bottom: 10px;
1008 background-color: #ccc;
1009 border: 1px solid #aaa;
1014 font-family: verdana, tahoma, sans-serif;
1017 font-family: verdana, tahoma, sans-serif;
1020 text-decoration: none;
1022 border-bottom: 1px dotted #bbb;
1024 :link:hover, :visited:hover {
1037 background-color: #fff;
1038 border: 1px solid #aaa;
1042 font-weight: normal;
1064 <h1><span id="appname">$name</span> on <a href="http://catalyst.perl.org">Catalyst</a>
1069 <img src="$logo" alt="Catalyst Logo" />
1071 <p>Welcome to the world of Catalyst.
1072 This <a href="http://en.wikipedia.org/wiki/MVC">MVC</a>
1073 framework will make web development something you had
1074 never expected it to be: Fun, rewarding, and quick.</p>
1075 <h2>What to do now?</h2>
1076 <p>That really depends on what <b>you</b> want to do.
1077 We do, however, provide you with a few starting points.</p>
1078 <p>If you want to jump right into web development with Catalyst
1079 you might want want to start with a tutorial.</p>
1080 <pre>perldoc <a href="http://cpansearch.perl.org/dist/Catalyst-Manual/lib/Catalyst/Manual/Tutorial.pod">Catalyst::Manual::Tutorial</a></code>
1082 <p>Afterwards you can go on to check out a more complete look at our features.</p>
1084 <code>perldoc <a href="http://cpansearch.perl.org/dist/Catalyst-Manual/lib/Catalyst/Manual/Intro.pod">Catalyst::Manual::Intro</a>
1085 <!-- Something else should go here, but the Catalyst::Manual link seems unhelpful -->
1087 <h2>What to do next?</h2>
1088 <p>Next it's time to write an actual application. Use the
1089 helper scripts to generate <a href="http://cpansearch.perl.org/search?query=Catalyst%3A%3AController%3A%3A&mode=all">controllers</a>,
1090 <a href="http://cpansearch.perl.org/search?query=Catalyst%3A%3AModel%3A%3A&mode=all">models</a>, and
1091 <a href="http://cpansearch.perl.org/search?query=Catalyst%3A%3AView%3A%3A&mode=all">views</a>;
1092 they can save you a lot of work.</p>
1093 <pre><code>script/${prefix}_create.pl -help</code></pre>
1094 <p>Also, be sure to check out the vast and growing
1095 collection of <a href="http://cpansearch.perl.org/search?query=Catalyst%3A%3APlugin%3A%3A&mode=all">plugins for Catalyst on CPAN</a>;
1096 you are likely to find what you need there.
1100 <p>Catalyst has a very active community. Here are the main places to
1101 get in touch with us.</p>
1104 <a href="http://dev.catalyst.perl.org">Wiki</a>
1107 <a href="http://lists.rawmode.org/mailman/listinfo/catalyst">Mailing-List</a>
1110 <a href="irc://irc.perl.org/catalyst">IRC channel #catalyst on irc.perl.org</a>
1113 <h2>In conclusion</h2>
1114 <p>The Catalyst team hopes you will enjoy using Catalyst as much
1115 as we enjoyed making it. Please contact us if you have ideas
1116 for improvement or other feedback.</p>
1124 =head1 INTERNAL METHODS
1126 These methods are not meant to be used by end users.
1128 =head2 $c->components
1130 Returns a hash of components.
1132 =head2 $c->context_class
1134 Returns or sets the context class.
1138 Returns a hashref containing coderefs and execution counts (needed for
1139 deep recursion detection).
1143 Returns the number of actions on the current internal execution stack.
1147 Dispatches a request to actions.
1151 sub dispatch { my $c = shift; $c->dispatcher->dispatch( $c, @_ ) }
1153 =head2 $c->dispatcher_class
1155 Returns or sets the dispatcher class.
1157 =head2 $c->dump_these
1159 Returns a list of 2-element array references (name, structure) pairs
1160 that will be dumped on the error page in debug mode.
1166 [ Request => $c->req ],
1167 [ Response => $c->res ],
1168 [ Stash => $c->stash ],
1169 [ Config => $c->config ];
1172 =head2 $c->engine_class
1174 Returns or sets the engine class.
1176 =head2 $c->execute( $class, $coderef )
1178 Execute a coderef in given class and catch exceptions. Errors are available
1184 my ( $c, $class, $code ) = @_;
1185 $class = $c->component($class) || $class;
1188 if ( $c->depth >= $RECURSION ) {
1189 my $action = "$code";
1190 $action = "/$action" unless $action =~ /->/;
1191 my $error = qq/Deep recursion detected calling "$action"/;
1192 $c->log->error($error);
1198 my $stats_info = $c->_stats_start_execute( $code ) if $c->debug;
1200 push( @{ $c->stack }, $code );
1202 eval { $c->state( &$code( $class, $c, @{ $c->req->args } ) || 0 ) };
1204 $c->_stats_finish_execute( $stats_info ) if $c->debug and $stats_info;
1206 my $last = pop( @{ $c->stack } );
1208 if ( my $error = $@ ) {
1209 if ( !ref($error) and $error eq $DETACH ) { die $DETACH if $c->depth > 1 }
1211 unless ( ref $error ) {
1212 no warnings 'uninitialized';
1214 my $class = $last->class;
1215 my $name = $last->name;
1216 $error = qq/Caught exception in $class->$name "$error"/;
1225 sub _stats_start_execute {
1226 my ( $c, $code ) = @_;
1228 return if ( ( $code->name =~ /^_.*/ )
1229 && ( !$c->config->{show_internal_actions} ) );
1231 $c->counter->{"$code"}++;
1233 my $action = "$code";
1234 $action = "/$action" unless $action =~ /->/;
1236 # determine if the call was the result of a forward
1237 # this is done by walking up the call stack and looking for a calling
1238 # sub of Catalyst::forward before the eval
1240 for my $index ( 2 .. 11 ) {
1242 if ( ( caller($index) )[0] eq 'Catalyst'
1243 && ( caller($index) )[3] eq '(eval)' );
1245 if ( ( caller($index) )[3] =~ /forward$/ ) {
1246 $callsub = ( caller($index) )[3];
1247 $action = "-> $action";
1252 my $node = Tree::Simple->new(
1255 elapsed => undef, # to be filled in later
1259 $node->setUID( "$code" . $c->counter->{"$code"} );
1261 # is this a root-level call or a forwarded call?
1262 if ( $callsub =~ /forward$/ ) {
1264 # forward, locate the caller
1265 if ( my $parent = $c->stack->[-1] ) {
1266 my $visitor = Tree::Simple::Visitor::FindByUID->new;
1267 $visitor->searchForUID(
1268 "$parent" . $c->counter->{"$parent"} );
1269 $c->stats->accept($visitor);
1270 if ( my $result = $visitor->getResult ) {
1271 $result->addChild($node);
1276 # forward with no caller may come from a plugin
1277 $c->stats->addChild($node);
1283 $c->stats->addChild($node);
1287 start => [gettimeofday],
1292 sub _stats_finish_execute {
1293 my ( $c, $info ) = @_;
1294 my $elapsed = tv_interval $info->{start};
1295 my $value = $info->{node}->getNodeValue;
1296 $value->{elapsed} = sprintf( '%fs', $elapsed );
1299 =head2 $c->_localize_fields( sub { }, \%keys );
1303 sub _localize_fields {
1304 my ( $c, $localized, $code ) = ( @_ );
1306 my $request = delete $localized->{request} || {};
1307 my $response = delete $localized->{response} || {};
1309 local @{ $c }{ keys %$localized } = values %$localized;
1310 local @{ $c->request }{ keys %$request } = values %$request;
1311 local @{ $c->response }{ keys %$response } = values %$response;
1318 Finalizes the request.
1325 for my $error ( @{ $c->error } ) {
1326 $c->log->error($error);
1329 # Allow engine to handle finalize flow (for POE)
1330 if ( $c->engine->can('finalize') ) {
1331 $c->engine->finalize($c);
1335 $c->finalize_uploads;
1338 if ( $#{ $c->error } >= 0 ) {
1342 $c->finalize_headers;
1345 if ( $c->request->method eq 'HEAD' ) {
1346 $c->response->body('');
1353 my $elapsed = sprintf '%f', tv_interval($c->stats->getNodeValue);
1354 my $av = sprintf '%.3f', ( $elapsed == 0 ? '??' : ( 1 / $elapsed ) );
1356 my $t = Text::SimpleTable->new( [ 62, 'Action' ], [ 9, 'Time' ] );
1357 $c->stats->traverse(
1360 my $stat = $action->getNodeValue;
1361 $t->row( ( q{ } x $action->getDepth ) . $stat->{action} . $stat->{comment},
1362 $stat->{elapsed} || '??' );
1367 "Request took ${elapsed}s ($av/s)\n" . $t->draw . "\n" );
1370 return $c->response->status;
1373 =head2 $c->finalize_body
1379 sub finalize_body { my $c = shift; $c->engine->finalize_body( $c, @_ ) }
1381 =head2 $c->finalize_cookies
1387 sub finalize_cookies { my $c = shift; $c->engine->finalize_cookies( $c, @_ ) }
1389 =head2 $c->finalize_error
1395 sub finalize_error { my $c = shift; $c->engine->finalize_error( $c, @_ ) }
1397 =head2 $c->finalize_headers
1403 sub finalize_headers {
1406 # Check if we already finalized headers
1407 return if $c->response->{_finalized_headers};
1410 if ( my $location = $c->response->redirect ) {
1411 $c->log->debug(qq/Redirecting to "$location"/) if $c->debug;
1412 $c->response->header( Location => $location );
1414 if ( !$c->response->body ) {
1415 # Add a default body if none is already present
1417 qq{<html><body><p>This item has moved <a href="$location">here</a>.</p></body></html>}
1423 if ( $c->response->body && !$c->response->content_length ) {
1425 # get the length from a filehandle
1426 if ( blessed( $c->response->body ) && $c->response->body->can('read') )
1428 if ( my $stat = stat $c->response->body ) {
1429 $c->response->content_length( $stat->size );
1432 $c->log->warn('Serving filehandle without a content-length');
1436 $c->response->content_length( bytes::length( $c->response->body ) );
1441 if ( $c->response->status =~ /^(1\d\d|[23]04)$/ ) {
1442 $c->response->headers->remove_header("Content-Length");
1443 $c->response->body('');
1446 $c->finalize_cookies;
1448 $c->engine->finalize_headers( $c, @_ );
1451 $c->response->{_finalized_headers} = 1;
1454 =head2 $c->finalize_output
1456 An alias for finalize_body.
1458 =head2 $c->finalize_read
1460 Finalizes the input after reading is complete.
1464 sub finalize_read { my $c = shift; $c->engine->finalize_read( $c, @_ ) }
1466 =head2 $c->finalize_uploads
1468 Finalizes uploads. Cleans up any temporary files.
1472 sub finalize_uploads { my $c = shift; $c->engine->finalize_uploads( $c, @_ ) }
1474 =head2 $c->get_action( $action, $namespace )
1476 Gets an action in a given namespace.
1480 sub get_action { my $c = shift; $c->dispatcher->get_action(@_) }
1482 =head2 $c->get_actions( $action, $namespace )
1484 Gets all actions of a given name in a namespace and all parent
1489 sub get_actions { my $c = shift; $c->dispatcher->get_actions( $c, @_ ) }
1491 =head2 $c->handle_request( $class, @arguments )
1493 Called to handle each HTTP request.
1497 sub handle_request {
1498 my ( $class, @arguments ) = @_;
1500 # Always expect worst case!
1503 if ($class->debug) {
1504 my $secs = time - $START || 1;
1505 my $av = sprintf '%.3f', $COUNT / $secs;
1506 my $time = localtime time;
1507 $class->log->info("*** Request $COUNT ($av/s) [$$] [$time] ***");
1510 my $c = $class->prepare(@arguments);
1512 $status = $c->finalize;
1515 if ( my $error = $@ ) {
1517 $class->log->error(qq/Caught exception in engine "$error"/);
1521 $class->log->_flush() if $class->log->can('_flush');
1525 =head2 $c->prepare( @arguments )
1527 Creates a Catalyst context from an engine-specific request (Apache, CGI,
1533 my ( $class, @arguments ) = @_;
1535 $class->context_class( ref $class || $class ) unless $class->context_class;
1536 my $c = $class->context_class->new(
1540 request => $class->request_class->new(
1543 body_parameters => {},
1545 headers => HTTP::Headers->new,
1547 query_parameters => {},
1553 response => $class->response_class->new(
1557 headers => HTTP::Headers->new(),
1567 $c->stats(Tree::Simple->new([gettimeofday]));
1568 $c->res->headers->header( 'X-Catalyst' => $Catalyst::VERSION );
1571 # For on-demand data
1572 $c->request->{_context} = $c;
1573 $c->response->{_context} = $c;
1574 weaken( $c->request->{_context} );
1575 weaken( $c->response->{_context} );
1577 # Allow engine to direct the prepare flow (for POE)
1578 if ( $c->engine->can('prepare') ) {
1579 $c->engine->prepare( $c, @arguments );
1582 $c->prepare_request(@arguments);
1583 $c->prepare_connection;
1584 $c->prepare_query_parameters;
1585 $c->prepare_headers;
1586 $c->prepare_cookies;
1590 $c->prepare_body unless $c->config->{parse_on_demand};
1593 my $method = $c->req->method || '';
1594 my $path = $c->req->path || '/';
1595 my $address = $c->req->address || '';
1597 $c->log->debug(qq/"$method" request for "$path" from "$address"/)
1605 =head2 $c->prepare_action
1607 Prepares action. See L<Catalyst::Dispatcher>.
1611 sub prepare_action { my $c = shift; $c->dispatcher->prepare_action( $c, @_ ) }
1613 =head2 $c->prepare_body
1615 Prepares message body.
1622 # Do we run for the first time?
1623 return if defined $c->request->{_body};
1625 # Initialize on-demand data
1626 $c->engine->prepare_body( $c, @_ );
1627 $c->prepare_parameters;
1628 $c->prepare_uploads;
1630 if ( $c->debug && keys %{ $c->req->body_parameters } ) {
1631 my $t = Text::SimpleTable->new( [ 35, 'Parameter' ], [ 36, 'Value' ] );
1632 for my $key ( sort keys %{ $c->req->body_parameters } ) {
1633 my $param = $c->req->body_parameters->{$key};
1634 my $value = defined($param) ? $param : '';
1636 ref $value eq 'ARRAY' ? ( join ', ', @$value ) : $value );
1638 $c->log->debug( "Body Parameters are:\n" . $t->draw );
1642 =head2 $c->prepare_body_chunk( $chunk )
1644 Prepares a chunk of data before sending it to L<HTTP::Body>.
1646 See L<Catalyst::Engine>.
1650 sub prepare_body_chunk {
1652 $c->engine->prepare_body_chunk( $c, @_ );
1655 =head2 $c->prepare_body_parameters
1657 Prepares body parameters.
1661 sub prepare_body_parameters {
1663 $c->engine->prepare_body_parameters( $c, @_ );
1666 =head2 $c->prepare_connection
1668 Prepares connection.
1672 sub prepare_connection {
1674 $c->engine->prepare_connection( $c, @_ );
1677 =head2 $c->prepare_cookies
1683 sub prepare_cookies { my $c = shift; $c->engine->prepare_cookies( $c, @_ ) }
1685 =head2 $c->prepare_headers
1691 sub prepare_headers { my $c = shift; $c->engine->prepare_headers( $c, @_ ) }
1693 =head2 $c->prepare_parameters
1695 Prepares parameters.
1699 sub prepare_parameters {
1701 $c->prepare_body_parameters;
1702 $c->engine->prepare_parameters( $c, @_ );
1705 =head2 $c->prepare_path
1707 Prepares path and base.
1711 sub prepare_path { my $c = shift; $c->engine->prepare_path( $c, @_ ) }
1713 =head2 $c->prepare_query_parameters
1715 Prepares query parameters.
1719 sub prepare_query_parameters {
1722 $c->engine->prepare_query_parameters( $c, @_ );
1724 if ( $c->debug && keys %{ $c->request->query_parameters } ) {
1725 my $t = Text::SimpleTable->new( [ 35, 'Parameter' ], [ 36, 'Value' ] );
1726 for my $key ( sort keys %{ $c->req->query_parameters } ) {
1727 my $param = $c->req->query_parameters->{$key};
1728 my $value = defined($param) ? $param : '';
1730 ref $value eq 'ARRAY' ? ( join ', ', @$value ) : $value );
1732 $c->log->debug( "Query Parameters are:\n" . $t->draw );
1736 =head2 $c->prepare_read
1738 Prepares the input for reading.
1742 sub prepare_read { my $c = shift; $c->engine->prepare_read( $c, @_ ) }
1744 =head2 $c->prepare_request
1746 Prepares the engine request.
1750 sub prepare_request { my $c = shift; $c->engine->prepare_request( $c, @_ ) }
1752 =head2 $c->prepare_uploads
1758 sub prepare_uploads {
1761 $c->engine->prepare_uploads( $c, @_ );
1763 if ( $c->debug && keys %{ $c->request->uploads } ) {
1764 my $t = Text::SimpleTable->new(
1765 [ 12, 'Parameter' ],
1770 for my $key ( sort keys %{ $c->request->uploads } ) {
1771 my $upload = $c->request->uploads->{$key};
1772 for my $u ( ref $upload eq 'ARRAY' ? @{$upload} : ($upload) ) {
1773 $t->row( $key, $u->filename, $u->type, $u->size );
1776 $c->log->debug( "File Uploads are:\n" . $t->draw );
1780 =head2 $c->prepare_write
1782 Prepares the output for writing.
1786 sub prepare_write { my $c = shift; $c->engine->prepare_write( $c, @_ ) }
1788 =head2 $c->request_class
1790 Returns or sets the request class.
1792 =head2 $c->response_class
1794 Returns or sets the response class.
1796 =head2 $c->read( [$maxlength] )
1798 Reads a chunk of data from the request body. This method is designed to
1799 be used in a while loop, reading C<$maxlength> bytes on every call.
1800 C<$maxlength> defaults to the size of the request if not specified.
1802 You have to set C<< MyApp->config->{parse_on_demand} >> to use this
1807 sub read { my $c = shift; return $c->engine->read( $c, @_ ) }
1815 sub run { my $c = shift; return $c->engine->run( $c, @_ ) }
1817 =head2 $c->set_action( $action, $code, $namespace, $attrs )
1819 Sets an action in a given namespace.
1823 sub set_action { my $c = shift; $c->dispatcher->set_action( $c, @_ ) }
1825 =head2 $c->setup_actions($component)
1827 Sets up actions for a component.
1831 sub setup_actions { my $c = shift; $c->dispatcher->setup_actions( $c, @_ ) }
1833 =head2 $c->setup_components
1835 Sets up components. Specify a C<setup_components> config option to pass
1836 additional options directly to L<Module::Pluggable>. To add additional
1837 search paths, specify a key named C<search_extra> as an array
1838 reference. Items in the array beginning with C<::> will have the
1839 application class name prepended to them.
1843 sub setup_components {
1846 my @paths = qw( ::Controller ::C ::Model ::M ::View ::V );
1847 my $config = $class->config->{ setup_components };
1848 my $extra = delete $config->{ search_extra } || [];
1850 push @paths, @$extra;
1852 my $locator = Module::Pluggable::Object->new(
1853 search_path => [ map { s/^(?=::)/$class/; $_; } @paths ],
1857 for my $component ( sort { length $a <=> length $b } $locator->plugins ) {
1858 Catalyst::Utils::ensure_class_loaded( $component, { ignore_loaded => 1 } );
1860 my $module = $class->setup_component( $component );
1862 $component => $module,
1864 $_ => $class->setup_component( $_ )
1865 } Devel::InnerPackage::list_packages( $component )
1868 for my $key ( keys %modules ) {
1869 $class->components->{ $key } = $modules{ $key };
1874 =head2 $c->setup_component
1878 sub setup_component {
1879 my( $class, $component ) = @_;
1881 unless ( $component->can( 'COMPONENT' ) ) {
1885 my $suffix = Catalyst::Utils::class2classsuffix( $component );
1886 my $config = $class->config->{ $suffix } || {};
1888 my $instance = eval { $component->COMPONENT( $class, $config ); };
1890 if ( my $error = $@ ) {
1892 Catalyst::Exception->throw(
1893 message => qq/Couldn't instantiate component "$component", "$error"/
1897 Catalyst::Exception->throw(
1899 qq/Couldn't instantiate component "$component", "COMPONENT() didn't return an object-like value"/
1900 ) unless eval { $instance->can( 'can' ) };
1905 =head2 $c->setup_dispatcher
1911 sub setup_dispatcher {
1912 my ( $class, $dispatcher ) = @_;
1915 $dispatcher = 'Catalyst::Dispatcher::' . $dispatcher;
1918 if ( $ENV{CATALYST_DISPATCHER} ) {
1919 $dispatcher = 'Catalyst::Dispatcher::' . $ENV{CATALYST_DISPATCHER};
1922 if ( $ENV{ uc($class) . '_DISPATCHER' } ) {
1924 'Catalyst::Dispatcher::' . $ENV{ uc($class) . '_DISPATCHER' };
1927 unless ($dispatcher) {
1928 $dispatcher = $class->dispatcher_class;
1931 unless (Class::Inspector->loaded($dispatcher)) {
1932 require Class::Inspector->filename($dispatcher);
1935 # dispatcher instance
1936 $class->dispatcher( $dispatcher->new );
1939 =head2 $c->setup_engine
1946 my ( $class, $engine ) = @_;
1949 $engine = 'Catalyst::Engine::' . $engine;
1952 if ( $ENV{CATALYST_ENGINE} ) {
1953 $engine = 'Catalyst::Engine::' . $ENV{CATALYST_ENGINE};
1956 if ( $ENV{ uc($class) . '_ENGINE' } ) {
1957 $engine = 'Catalyst::Engine::' . $ENV{ uc($class) . '_ENGINE' };
1960 if ( $ENV{MOD_PERL} ) {
1962 # create the apache method
1965 *{"$class\::apache"} = sub { shift->engine->apache };
1968 my ( $software, $version ) =
1969 $ENV{MOD_PERL} =~ /^(\S+)\/(\d+(?:[\.\_]\d+)+)/;
1972 $version =~ s/(\.[^.]+)\./$1/g;
1974 if ( $software eq 'mod_perl' ) {
1978 if ( $version >= 1.99922 ) {
1979 $engine = 'Catalyst::Engine::Apache2::MP20';
1982 elsif ( $version >= 1.9901 ) {
1983 $engine = 'Catalyst::Engine::Apache2::MP19';
1986 elsif ( $version >= 1.24 ) {
1987 $engine = 'Catalyst::Engine::Apache::MP13';
1991 Catalyst::Exception->throw( message =>
1992 qq/Unsupported mod_perl version: $ENV{MOD_PERL}/ );
1997 # install the correct mod_perl handler
1998 if ( $version >= 1.9901 ) {
1999 *handler = sub : method {
2000 shift->handle_request(@_);
2004 *handler = sub ($$) { shift->handle_request(@_) };
2009 elsif ( $software eq 'Zeus-Perl' ) {
2010 $engine = 'Catalyst::Engine::Zeus';
2014 Catalyst::Exception->throw(
2015 message => qq/Unsupported mod_perl: $ENV{MOD_PERL}/ );
2020 $engine = $class->engine_class;
2023 unless (Class::Inspector->loaded($engine)) {
2024 require Class::Inspector->filename($engine);
2027 # check for old engines that are no longer compatible
2029 if ( $engine->isa('Catalyst::Engine::Apache')
2030 && !Catalyst::Engine::Apache->VERSION )
2035 elsif ( $engine->isa('Catalyst::Engine::Server::Base')
2036 && Catalyst::Engine::Server->VERSION le '0.02' )
2041 elsif ($engine->isa('Catalyst::Engine::HTTP::POE')
2042 && $engine->VERSION eq '0.01' )
2047 elsif ($engine->isa('Catalyst::Engine::Zeus')
2048 && $engine->VERSION eq '0.01' )
2054 Catalyst::Exception->throw( message =>
2055 qq/Engine "$engine" is not supported by this version of Catalyst/
2060 $class->engine( $engine->new );
2063 =head2 $c->setup_home
2065 Sets up the home directory.
2070 my ( $class, $home ) = @_;
2072 if ( $ENV{CATALYST_HOME} ) {
2073 $home = $ENV{CATALYST_HOME};
2076 if ( $ENV{ uc($class) . '_HOME' } ) {
2078 $home = $ENV{ uc($class) . '_HOME' };
2082 $home = Catalyst::Utils::home($class);
2086 $class->config->{home} ||= $home;
2087 $class->config->{root} ||= Path::Class::Dir->new($home)->subdir('root');
2091 =head2 $c->setup_log
2098 my ( $class, $debug ) = @_;
2100 unless ( $class->log ) {
2101 $class->log( Catalyst::Log->new );
2104 my $app_flag = Catalyst::Utils::class2env($class) . '_DEBUG';
2107 ( defined( $ENV{CATALYST_DEBUG} ) || defined( $ENV{$app_flag} ) )
2108 ? ( $ENV{CATALYST_DEBUG} || $ENV{$app_flag} )
2113 *{"$class\::debug"} = sub { 1 };
2114 $class->log->debug('Debug messages enabled');
2118 =head2 $c->setup_plugins
2124 =head2 $c->registered_plugins
2126 Returns a sorted list of the plugins which have either been stated in the
2127 import list or which have been added via C<< MyApp->plugin(@args); >>.
2129 If passed a given plugin name, it will report a boolean value indicating
2130 whether or not that plugin is loaded. A fully qualified name is required if
2131 the plugin name does not begin with C<Catalyst::Plugin::>.
2133 if ($c->registered_plugins('Some::Plugin')) {
2141 sub registered_plugins {
2143 return sort keys %{ $proto->_plugins } unless @_;
2145 return 1 if exists $proto->_plugins->{$plugin};
2146 return exists $proto->_plugins->{"Catalyst::Plugin::$plugin"};
2149 sub _register_plugin {
2150 my ( $proto, $plugin, $instant ) = @_;
2151 my $class = ref $proto || $proto;
2153 unless (Class::Inspector->loaded($plugin)) {
2154 require Class::Inspector->filename($plugin);
2157 $proto->_plugins->{$plugin} = 1;
2160 unshift @{"$class\::ISA"}, $plugin;
2166 my ( $class, $plugins ) = @_;
2168 $class->_plugins( {} ) unless $class->_plugins;
2170 for my $plugin ( reverse @$plugins ) {
2172 unless ( $plugin =~ s/\A\+// ) {
2173 $plugin = "Catalyst::Plugin::$plugin";
2176 $class->_register_plugin($plugin);
2183 Returns an arrayref of the internal execution stack (actions that are
2184 currently executing).
2186 =head2 $c->write( $data )
2188 Writes $data to the output stream. When using this method directly, you
2189 will need to manually set the C<Content-Length> header to the length of
2190 your output data, if known.
2197 # Finalize headers if someone manually writes output
2198 $c->finalize_headers;
2200 return $c->engine->write( $c, @_ );
2205 Returns the Catalyst version number. Mostly useful for "powered by"
2206 messages in template systems.
2210 sub version { return $Catalyst::VERSION }
2212 =head1 INTERNAL ACTIONS
2214 Catalyst uses internal actions like C<_DISPATCH>, C<_BEGIN>, C<_AUTO>,
2215 C<_ACTION>, and C<_END>. These are by default not shown in the private
2216 action table, but you can make them visible with a config parameter.
2218 MyApp->config->{show_internal_actions} = 1;
2220 =head1 CASE SENSITIVITY
2222 By default Catalyst is not case sensitive, so C<MyApp::C::FOO::Bar> is
2223 mapped to C</foo/bar>. You can activate case sensitivity with a config
2226 MyApp->config->{case_sensitive} = 1;
2228 This causes C<MyApp::C::Foo::Bar> to map to C</Foo/Bar>.
2230 =head1 ON-DEMAND PARSER
2232 The request body is usually parsed at the beginning of a request,
2233 but if you want to handle input yourself or speed things up a bit,
2234 you can enable on-demand parsing with a config parameter.
2236 MyApp->config->{parse_on_demand} = 1;
2238 =head1 PROXY SUPPORT
2240 Many production servers operate using the common double-server approach,
2241 with a lightweight frontend web server passing requests to a larger
2242 backend server. An application running on the backend server must deal
2243 with two problems: the remote user always appears to be C<127.0.0.1> and
2244 the server's hostname will appear to be C<localhost> regardless of the
2245 virtual host that the user connected through.
2247 Catalyst will automatically detect this situation when you are running
2248 the frontend and backend servers on the same machine. The following
2249 changes are made to the request.
2251 $c->req->address is set to the user's real IP address, as read from
2252 the HTTP X-Forwarded-For header.
2254 The host value for $c->req->base and $c->req->uri is set to the real
2255 host, as read from the HTTP X-Forwarded-Host header.
2257 Obviously, your web server must support these headers for this to work.
2259 In a more complex server farm environment where you may have your
2260 frontend proxy server(s) on different machines, you will need to set a
2261 configuration option to tell Catalyst to read the proxied data from the
2264 MyApp->config->{using_frontend_proxy} = 1;
2266 If you do not wish to use the proxy support at all, you may set:
2268 MyApp->config->{ignore_frontend_proxy} = 1;
2270 =head1 THREAD SAFETY
2272 Catalyst has been tested under Apache 2's threading C<mpm_worker>,
2273 C<mpm_winnt>, and the standalone forking HTTP server on Windows. We
2274 believe the Catalyst core to be thread-safe.
2276 If you plan to operate in a threaded environment, remember that all other
2277 modules you are using must also be thread-safe. Some modules, most notably
2278 L<DBD::SQLite>, are not thread-safe.
2284 Join #catalyst on irc.perl.org.
2288 http://lists.rawmode.org/mailman/listinfo/catalyst
2289 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
2293 http://catalyst.perl.org
2297 http://dev.catalyst.perl.org
2301 =head2 L<Task::Catalyst> - All you need to start with Catalyst
2303 =head2 L<Catalyst::Manual> - The Catalyst Manual
2305 =head2 L<Catalyst::Component>, L<Catalyst::Base> - Base classes for components
2307 =head2 L<Catalyst::Engine> - Core engine
2309 =head2 L<Catalyst::Log> - Log class.
2311 =head2 L<Catalyst::Request> - Request object
2313 =head2 L<Catalyst::Response> - Response object
2315 =head2 L<Catalyst::Test> - The test suite.
2387 Sebastian Riedel, C<sri@oook.de>
2391 This library is free software, you can redistribute it and/or modify it under
2392 the same terms as Perl itself.