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/create.pl model Something
29 script/create.pl view Stuff
30 script/create.pl controller Yada
35 # command line interface
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 Catalyst is based upon L<Maypole>, which you should consider for smaller
68 The key concept of Catalyst is DRY (Don't Repeat Yourself).
70 See L<Catalyst::Manual> for more documentation.
72 Catalyst plugins can be loaded by naming them as arguments to the "use Catalyst" statement.
73 Omit the C<Catalyst::Plugin::> prefix from the plugin name,
74 so C<Catalyst::Plugin::My::Module> becomes C<My::Module>.
76 use Catalyst 'My::Module';
78 Special flags like -Debug and -Engine can also be specifed as arguments when
81 use Catalyst qw/-Debug My::Module/;
83 The position of plugins and flags in the chain is important, because they are
84 loaded in exactly the order that they appear.
86 The following flags are supported:
92 enables debug output, i.e.:
94 use Catalyst '-Debug';
96 this is equivalent to:
103 Force Catalyst to use a specific engine.
104 Omit the C<Catalyst::Engine::> prefix of the engine name, i.e.:
106 use Catalyst '-Engine=CGI';
116 Overload to enable debug messages.
124 Returns a hashref containing your applications settings.
129 my ( $self, @options ) = @_;
130 my $caller = caller(0);
132 # Prepare inheritance
133 unless ( $caller->isa($self) ) {
135 push @{"$caller\::ISA"}, $self;
138 if ( $caller->engine ) {
139 return; # Catalyst is already initialized
142 unless ( $caller->log ) {
143 $caller->log( Catalyst::Log->new );
147 if ( $ENV{CATALYST_DEBUG} || $ENV{ uc($caller) . '_DEBUG' } ) {
149 *{"$caller\::debug"} = sub { 1 };
150 $caller->log->debug('Debug messages enabled');
153 my $engine = 'Catalyst::Engine::CGI';
154 my $dispatcher = 'Catalyst::Dispatcher';
156 if ( $ENV{MOD_PERL} ) {
158 my ( $software, $version ) = $ENV{MOD_PERL} =~ /^(\S+)\/(\d+(?:[\.\_]\d+)+)/;
161 $version =~ s/(\.[^.]+)\./$1/g;
163 if ( $software eq 'mod_perl') {
165 if ( $version >= 1.99922 ) {
167 $engine = 'Catalyst::Engine::Apache::MP20';
169 if ( Apache2::Request->require ) {
170 $engine = 'Catalyst::Engine::Apache::MP20::Apreq';
174 elsif ( $version >= 1.9901 ) {
176 $engine = 'Catalyst::Engine::Apache::MP19';
178 if ( Apache::Request->require ) {
179 $engine = 'Catalyst::Engine::Apache::MP19::Apreq';
183 elsif ( $version >= 1.24 ) {
185 $engine = 'Catalyst::Engine::Apache::MP13';
187 if ( Apache::Request->require ) {
188 $engine = 'Catalyst::Engine::Apache::MP13::Apreq';
193 die( qq/Unsupported mod_perl version: $ENV{MOD_PERL}/ );
197 elsif ( $software eq 'Zeus-Perl' ) {
198 $engine = 'Catalyst::Engine::Zeus';
202 die( qq/Unsupported mod_perl: $ENV{MOD_PERL}/ );
206 $caller->log->info( "You are running an old helper script! "
207 . "Please update your scripts by regenerating the "
208 . "application and copying over the new scripts." )
209 if ( $ENV{CATALYST_SCRIPT_GEN}
210 && ( $ENV{CATALYST_SCRIPT_GEN} < $CATALYST_SCRIPT_GEN ) );
217 next if $caller->debug;
219 *{"$caller\::debug"} = sub { 1 };
220 $caller->log->debug('Debug messages enabled');
223 elsif (/^-Dispatcher=(.*)$/) {
224 $dispatcher = "Catalyst::Dispatcher::$1";
227 elsif (/^-Engine=(.*)$/) { $engine = "Catalyst::Engine::$1" }
228 elsif (/^-.*$/) { $caller->log->error(qq/Unknown flag "$_"/) }
231 my $plugin = "Catalyst::Plugin::$_";
235 if ($@) { die qq/Couldn't load plugin "$plugin", "$@"/ }
237 push @plugins, $plugin;
239 push @{"$caller\::ISA"}, $plugin;
246 my $t = Text::ASCIITable->new( { hide_HeadRow => 1, hide_HeadLine => 1 } );
247 $t->setCols('Class');
248 $t->setColWidth( 'Class', 75, 1 );
249 $t->addRow($_) for @plugins;
250 $caller->log->debug( 'Loaded plugins', $t->draw )
251 if ( @plugins && $caller->debug );
254 $dispatcher = "Catalyst::Dispatcher::$ENV{CATALYST_DISPATCHER}"
255 if $ENV{CATALYST_DISPATCHER};
256 my $appdis = $ENV{ uc($caller) . '_DISPATCHER' };
257 $dispatcher = "Catalyst::Dispatcher::$appdis" if $appdis;
259 $dispatcher->require;
260 die qq/Couldn't load dispatcher "$dispatcher", "$@"/ if $@;
263 push @{"$caller\::ISA"}, $dispatcher;
265 $caller->dispatcher($dispatcher);
266 $caller->log->debug(qq/Loaded dispatcher "$dispatcher"/) if $caller->debug;
269 $engine = "Catalyst::Engine::$ENV{CATALYST_ENGINE}"
270 if $ENV{CATALYST_ENGINE};
271 my $appeng = $ENV{ uc($caller) . '_ENGINE' };
272 $engine = "Catalyst::Engine::$appeng" if $appeng;
275 die qq/Couldn't load engine "$engine", "$@"/ if $@;
279 push @{"$caller\::ISA"}, $engine;
282 $caller->engine($engine);
283 $caller->log->debug(qq/Loaded engine "$engine"/) if $caller->debug;
286 my $home = Catalyst::Utils::home($caller);
288 if ( my $h = $ENV{CATALYST_HOME} ) {
293 $caller->log->warn(qq/CATALYST_HOME does not exist "$h"/);
296 unless ( -e _ && -d _ ) {
297 $caller->log->warn(qq/CATALYST_HOME is not a directory "$h"/);
301 if ( my $h = $ENV{ uc($caller) . '_HOME' } ) {
306 my $e = uc($caller) . '_HOME';
307 $caller->log->warn(qq/$e does not exist "$h"/)
310 unless ( -e _ && -d _ ) {
311 my $e = uc($caller) . '_HOME';
312 $caller->log->warn(qq/$e is not a directory "$h"/);
316 if ( $caller->debug ) {
319 ? $caller->log->debug(qq/Found home "$home"/)
320 : $caller->log->debug(qq/Home "$home" doesn't exist/)
321 : $caller->log->debug(q/Couldn't find home/);
323 $caller->config->{home} = $home || '';
324 $caller->config->{root} = defined $home ? dir($home)->subdir('root') : '';
329 Contains the engine class.
333 Contains the logging object. Unless it is already set Catalyst sets this up with a
334 C<Catalyst::Log> object. To use your own log class:
336 $c->log( MyLogger->new );
337 $c->log->info("now logging with my own logger!");
339 Your log class should implement the methods described in the C<Catalyst::Log>
342 =item $c->plugin( $name, $class, @args )
344 Instant plugins for Catalyst.
345 Classdata accessor/mutator will be created, class loaded and instantiated.
347 MyApp->plugin( 'prototype', 'HTML::Prototype' );
349 $c->prototype->define_javascript_functions;
354 my ( $class, $name, $plugin, @args ) = @_;
356 my $error = $UNIVERSAL::require::ERROR;
357 die qq/Couldn't load instant plugin "$plugin", "$error"/ if $error;
358 eval { $plugin->import };
359 $class->mk_classdata($name);
361 eval { $obj = $plugin->new(@args) };
362 die qq/Couldn't instantiate instant plugin "$plugin", "$@"/ if $@;
364 $class->log->debug(qq/Initialized instant plugin "$plugin" as "$name"/)
372 mod_perl2 support is considered experimental and may contain bugs.
378 Join #catalyst on irc.perl.org.
382 http://lists.rawmode.org/mailman/listinfo/catalyst
383 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
387 http://catalyst.perl.org
393 =item L<Catalyst::Manual> - The Catalyst Manual
395 =item L<Catalyst::Engine> - Core Engine
397 =item L<Catalyst::Log> - The Log Class.
399 =item L<Catalyst::Request> - The Request Object
401 =item L<Catalyst::Response> - The Response Object
403 =item L<Catalyst::Test> - The test suite.
409 Sebastian Riedel, C<sri@oook.de>
413 Andy Grundman, Andrew Ford, Andrew Ruthven, Autrijus Tang, Christian Hansen,
414 Christopher Hicks, Dan Sully, Danijel Milicevic, David Naughton,
415 Gary Ashton Jones, Geoff Richards, Jesse Sheidlower, Jody Belka,
416 Johan Lindstrom, Juan Camacho, Leon Brocard, Marcus Ramberg,
417 Tatsuhiko Miyagawa and all the others who've helped.
421 This library is free software . You can redistribute it and/or modify it under
422 the same terms as perl itself.