4 use base 'Catalyst::Base';
5 use UNIVERSAL::require;
10 our $CATALYST_SCRIPT_GEN = 4;
12 __PACKAGE__->mk_classdata($_) for qw/dispatcher engine log/;
14 our $VERSION = '5.24';
19 Catalyst - The Elegant MVC Web Application Framework
23 # use the helper to start a new application
27 # add models, views, controllers
28 script/myapp_create.pl model Something
29 script/myapp_create.pl view Stuff
30 script/myapp_create.pl controller Yada
33 script/myapp_server.pl
35 # command line interface
36 script/myapp_test.pl /yada
41 use Catalyst qw/My::Module My::OtherModule/;
43 use Catalyst '-Debug';
45 use Catalyst qw/-Debug -Engine=CGI/;
47 sub default : Private { $_[1]->res->output('Hello') } );
49 sub index : Path('/index.html') {
50 my ( $self, $c ) = @_;
51 $c->res->output('Hello');
55 sub product : Regex('^product[_]*(\d*).html$') {
56 my ( $self, $c ) = @_;
57 $c->stash->{template} = 'product.tt';
58 $c->stash->{product} = $c->req->snippets->[0];
61 See also L<Catalyst::Manual::Intro>
65 The key concept of Catalyst is DRY (Don't Repeat Yourself).
67 See L<Catalyst::Manual> for more documentation.
69 Catalyst plugins can be loaded by naming them as arguments to the "use Catalyst" statement.
70 Omit the C<Catalyst::Plugin::> prefix from the plugin name,
71 so C<Catalyst::Plugin::My::Module> becomes C<My::Module>.
73 use Catalyst 'My::Module';
75 Special flags like -Debug and -Engine can also be specifed as arguments when
78 use Catalyst qw/-Debug My::Module/;
80 The position of plugins and flags in the chain is important, because they are
81 loaded in exactly the order that they appear.
83 The following flags are supported:
89 enables debug output, i.e.:
91 use Catalyst '-Debug';
93 this is equivalent to:
100 Force Catalyst to use a specific engine.
101 Omit the C<Catalyst::Engine::> prefix of the engine name, i.e.:
103 use Catalyst '-Engine=CGI';
113 Overload to enable debug messages.
121 Returns a hashref containing your applications settings.
126 my ( $self, @options ) = @_;
127 my $caller = caller(0);
129 # Prepare inheritance
130 unless ( $caller->isa($self) ) {
132 push @{"$caller\::ISA"}, $self;
135 if ( $caller->engine ) {
136 return; # Catalyst is already initialized
139 unless ( $caller->log ) {
140 $caller->log( Catalyst::Log->new );
144 if ( $ENV{CATALYST_DEBUG} || $ENV{ uc($caller) . '_DEBUG' } ) {
146 *{"$caller\::debug"} = sub { 1 };
147 $caller->log->debug('Debug messages enabled');
150 my $engine = 'Catalyst::Engine::CGI';
151 my $dispatcher = 'Catalyst::Dispatcher';
153 if ( $ENV{MOD_PERL} ) {
155 my ( $software, $version ) = $ENV{MOD_PERL} =~ /^(\S+)\/(\d+(?:[\.\_]\d+)+)/;
158 $version =~ s/(\.[^.]+)\./$1/g;
160 if ( $software eq 'mod_perl') {
162 if ( $version >= 1.99922 ) {
164 $engine = 'Catalyst::Engine::Apache::MP20';
166 if ( Apache2::Request->require ) {
167 $engine = 'Catalyst::Engine::Apache::MP20::Apreq';
171 elsif ( $version >= 1.9901 ) {
173 $engine = 'Catalyst::Engine::Apache::MP19';
175 if ( Apache::Request->require ) {
176 $engine = 'Catalyst::Engine::Apache::MP19::Apreq';
180 elsif ( $version >= 1.24 ) {
182 $engine = 'Catalyst::Engine::Apache::MP13';
184 if ( Apache::Request->require ) {
185 $engine = 'Catalyst::Engine::Apache::MP13::Apreq';
190 die( qq/Unsupported mod_perl version: $ENV{MOD_PERL}/ );
194 elsif ( $software eq 'Zeus-Perl' ) {
195 $engine = 'Catalyst::Engine::Zeus';
199 die( qq/Unsupported mod_perl: $ENV{MOD_PERL}/ );
203 $caller->log->info( "You are running an old helper script! "
204 . "Please update your scripts by regenerating the "
205 . "application and copying over the new scripts." )
206 if ( $ENV{CATALYST_SCRIPT_GEN}
207 && ( $ENV{CATALYST_SCRIPT_GEN} < $CATALYST_SCRIPT_GEN ) );
214 next if $caller->debug;
216 *{"$caller\::debug"} = sub { 1 };
217 $caller->log->debug('Debug messages enabled');
220 elsif (/^-Dispatcher=(.*)$/) {
221 $dispatcher = "Catalyst::Dispatcher::$1";
224 elsif (/^-Engine=(.*)$/) { $engine = "Catalyst::Engine::$1" }
225 elsif (/^-.*$/) { $caller->log->error(qq/Unknown flag "$_"/) }
228 my $plugin = "Catalyst::Plugin::$_";
232 if ($@) { die qq/Couldn't load plugin "$plugin", "$@"/ }
234 push @plugins, $plugin;
236 push @{"$caller\::ISA"}, $plugin;
243 my $t = Text::ASCIITable->new( { hide_HeadRow => 1, hide_HeadLine => 1 } );
244 $t->setCols('Class');
245 $t->setColWidth( 'Class', 75, 1 );
246 $t->addRow($_) for @plugins;
247 $caller->log->debug( 'Loaded plugins', $t->draw )
248 if ( @plugins && $caller->debug );
251 $dispatcher = "Catalyst::Dispatcher::$ENV{CATALYST_DISPATCHER}"
252 if $ENV{CATALYST_DISPATCHER};
253 my $appdis = $ENV{ uc($caller) . '_DISPATCHER' };
254 $dispatcher = "Catalyst::Dispatcher::$appdis" if $appdis;
256 $dispatcher->require;
257 die qq/Couldn't load dispatcher "$dispatcher", "$@"/ if $@;
260 push @{"$caller\::ISA"}, $dispatcher;
262 $caller->dispatcher($dispatcher);
263 $caller->log->debug(qq/Loaded dispatcher "$dispatcher"/) if $caller->debug;
266 $engine = "Catalyst::Engine::$ENV{CATALYST_ENGINE}"
267 if $ENV{CATALYST_ENGINE};
268 my $appeng = $ENV{ uc($caller) . '_ENGINE' };
269 $engine = "Catalyst::Engine::$appeng" if $appeng;
272 die qq/Couldn't load engine "$engine", "$@"/ if $@;
276 push @{"$caller\::ISA"}, $engine;
279 $caller->engine($engine);
280 $caller->log->debug(qq/Loaded engine "$engine"/) if $caller->debug;
283 my $home = Catalyst::Utils::home($caller);
285 if ( my $h = $ENV{CATALYST_HOME} ) {
290 $caller->log->warn(qq/CATALYST_HOME does not exist "$h"/);
293 unless ( -e _ && -d _ ) {
294 $caller->log->warn(qq/CATALYST_HOME is not a directory "$h"/);
298 if ( my $h = $ENV{ uc($caller) . '_HOME' } ) {
303 my $e = uc($caller) . '_HOME';
304 $caller->log->warn(qq/$e does not exist "$h"/)
307 unless ( -e _ && -d _ ) {
308 my $e = uc($caller) . '_HOME';
309 $caller->log->warn(qq/$e is not a directory "$h"/);
313 if ( $caller->debug ) {
316 ? $caller->log->debug(qq/Found home "$home"/)
317 : $caller->log->debug(qq/Home "$home" doesn't exist/)
318 : $caller->log->debug(q/Couldn't find home/);
320 $caller->config->{home} = $home || '';
321 $caller->config->{root} = defined $home ? dir($home)->subdir('root') : '';
326 Contains the engine class.
330 Contains the logging object. Unless it is already set Catalyst sets this up with a
331 C<Catalyst::Log> object. To use your own log class:
333 $c->log( MyLogger->new );
334 $c->log->info("now logging with my own logger!");
336 Your log class should implement the methods described in the C<Catalyst::Log>
339 =item $c->plugin( $name, $class, @args )
341 Instant plugins for Catalyst.
342 Classdata accessor/mutator will be created, class loaded and instantiated.
344 MyApp->plugin( 'prototype', 'HTML::Prototype' );
346 $c->prototype->define_javascript_functions;
351 my ( $class, $name, $plugin, @args ) = @_;
353 my $error = $UNIVERSAL::require::ERROR;
354 die qq/Couldn't load instant plugin "$plugin", "$error"/ if $error;
355 eval { $plugin->import };
356 $class->mk_classdata($name);
358 eval { $obj = $plugin->new(@args) };
359 die qq/Couldn't instantiate instant plugin "$plugin", "$@"/ if $@;
361 $class->log->debug(qq/Initialized instant plugin "$plugin" as "$name"/)
369 mod_perl2 support is considered experimental and may contain bugs.
375 Join #catalyst on irc.perl.org.
379 http://lists.rawmode.org/mailman/listinfo/catalyst
380 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
384 http://catalyst.perl.org
390 =item L<Catalyst::Manual> - The Catalyst Manual
392 =item L<Catalyst::Engine> - Core Engine
394 =item L<Catalyst::Log> - The Log Class.
396 =item L<Catalyst::Request> - The Request Object
398 =item L<Catalyst::Response> - The Response Object
400 =item L<Catalyst::Test> - The test suite.
406 Sebastian Riedel, C<sri@oook.de>
410 Andy Grundman, Andrew Ford, Andrew Ruthven, Autrijus Tang, Christian Hansen,
411 Christopher Hicks, Dan Sully, Danijel Milicevic, David Naughton,
412 Gary Ashton Jones, Geoff Richards, Jesse Sheidlower, Jody Belka,
413 Johan Lindstrom, Juan Camacho, Leon Brocard, Marcus Ramberg,
414 Tatsuhiko Miyagawa and all the others who've helped.
418 This library is free software . You can redistribute it and/or modify it under
419 the same terms as perl itself.