4 use base 'Catalyst::Base';
5 use UNIVERSAL::require;
6 use Catalyst::Exception;
11 our $CATALYST_SCRIPT_GEN = 4;
13 __PACKAGE__->mk_classdata($_) for qw/dispatcher engine log/;
15 our $VERSION = '5.24';
20 Catalyst - The Elegant MVC Web Application Framework
24 # use the helper to start a new application
28 # add models, views, controllers
29 script/myapp_create.pl model Something
30 script/myapp_create.pl view Stuff
31 script/myapp_create.pl controller Yada
34 script/myapp_server.pl
36 # command line interface
37 script/myapp_test.pl /yada
42 use Catalyst qw/My::Module My::OtherModule/;
44 use Catalyst '-Debug';
46 use Catalyst qw/-Debug -Engine=CGI/;
48 sub default : Private { $_[1]->res->output('Hello') } );
50 sub index : Path('/index.html') {
51 my ( $self, $c ) = @_;
52 $c->res->output('Hello');
56 sub product : Regex('^product[_]*(\d*).html$') {
57 my ( $self, $c ) = @_;
58 $c->stash->{template} = 'product.tt';
59 $c->stash->{product} = $c->req->snippets->[0];
62 See also L<Catalyst::Manual::Intro>
66 The key concept of Catalyst is DRY (Don't Repeat Yourself).
68 See L<Catalyst::Manual> for more documentation.
70 Catalyst plugins can be loaded by naming them as arguments to the "use Catalyst" statement.
71 Omit the C<Catalyst::Plugin::> prefix from the plugin name,
72 so C<Catalyst::Plugin::My::Module> becomes C<My::Module>.
74 use Catalyst 'My::Module';
76 Special flags like -Debug and -Engine can also be specifed as arguments when
79 use Catalyst qw/-Debug My::Module/;
81 The position of plugins and flags in the chain is important, because they are
82 loaded in exactly the order that they appear.
84 The following flags are supported:
90 enables debug output, i.e.:
92 use Catalyst '-Debug';
94 this is equivalent to:
101 Force Catalyst to use a specific engine.
102 Omit the C<Catalyst::Engine::> prefix of the engine name, i.e.:
104 use Catalyst '-Engine=CGI';
114 Overload to enable debug messages.
122 Returns a hashref containing your applications settings.
127 my ( $self, @options ) = @_;
128 my $caller = caller(0);
130 # Prepare inheritance
131 unless ( $caller->isa($self) ) {
133 push @{"$caller\::ISA"}, $self;
136 if ( $caller->engine ) {
137 return; # Catalyst is already initialized
140 unless ( $caller->log ) {
141 $caller->log( Catalyst::Log->new );
145 if ( $ENV{CATALYST_DEBUG} || $ENV{ uc($caller) . '_DEBUG' } ) {
147 *{"$caller\::debug"} = sub { 1 };
148 $caller->log->debug('Debug messages enabled');
151 my $engine = 'Catalyst::Engine::CGI';
152 my $dispatcher = 'Catalyst::Dispatcher';
154 if ( $ENV{MOD_PERL} ) {
156 my ( $software, $version ) = $ENV{MOD_PERL} =~ /^(\S+)\/(\d+(?:[\.\_]\d+)+)/;
159 $version =~ s/(\.[^.]+)\./$1/g;
161 if ( $software eq 'mod_perl') {
163 if ( $version >= 1.99922 ) {
165 $engine = 'Catalyst::Engine::Apache::MP20';
167 if ( Apache2::Request->require ) {
168 $engine = 'Catalyst::Engine::Apache::MP20::Apreq';
172 elsif ( $version >= 1.9901 ) {
174 $engine = 'Catalyst::Engine::Apache::MP19';
176 if ( Apache::Request->require ) {
177 $engine = 'Catalyst::Engine::Apache::MP19::Apreq';
181 elsif ( $version >= 1.24 ) {
183 $engine = 'Catalyst::Engine::Apache::MP13';
185 if ( Apache::Request->require ) {
186 $engine = 'Catalyst::Engine::Apache::MP13::Apreq';
191 Catalyst::Exception->throw(
192 message => qq/Unsupported mod_perl version: $ENV{MOD_PERL}/
197 elsif ( $software eq 'Zeus-Perl' ) {
198 $engine = 'Catalyst::Engine::Zeus';
202 Catalyst::Exception->throw(
203 message => qq/Unsupported mod_perl: $ENV{MOD_PERL}/
208 $caller->log->info( "You are running an old helper script! "
209 . "Please update your scripts by regenerating the "
210 . "application and copying over the new scripts." )
211 if ( $ENV{CATALYST_SCRIPT_GEN}
212 && ( $ENV{CATALYST_SCRIPT_GEN} < $CATALYST_SCRIPT_GEN ) );
219 next if $caller->debug;
221 *{"$caller\::debug"} = sub { 1 };
222 $caller->log->debug('Debug messages enabled');
225 elsif (/^-Dispatcher=(.*)$/) {
226 $dispatcher = "Catalyst::Dispatcher::$1";
229 elsif (/^-Engine=(.*)$/) { $engine = "Catalyst::Engine::$1" }
230 elsif (/^-.*$/) { $caller->log->error(qq/Unknown flag "$_"/) }
233 my $plugin = "Catalyst::Plugin::$_";
238 Catalyst::Exception->throw(
239 message => qq/Couldn't load plugin "$plugin", "$@"/
243 push @plugins, $plugin;
245 push @{"$caller\::ISA"}, $plugin;
252 my $t = Text::ASCIITable->new( { hide_HeadRow => 1, hide_HeadLine => 1 } );
253 $t->setCols('Class');
254 $t->setColWidth( 'Class', 75, 1 );
255 $t->addRow($_) for @plugins;
256 $caller->log->debug( 'Loaded plugins', $t->draw )
257 if ( @plugins && $caller->debug );
260 $dispatcher = "Catalyst::Dispatcher::$ENV{CATALYST_DISPATCHER}"
261 if $ENV{CATALYST_DISPATCHER};
262 my $appdis = $ENV{ uc($caller) . '_DISPATCHER' };
263 $dispatcher = "Catalyst::Dispatcher::$appdis" if $appdis;
265 $dispatcher->require;
268 Catalyst::Exception->throw(
269 message => qq/Couldn't load dispatcher "$dispatcher", "$@"/
275 push @{"$caller\::ISA"}, $dispatcher;
277 $caller->dispatcher($dispatcher);
278 $caller->log->debug(qq/Loaded dispatcher "$dispatcher"/) if $caller->debug;
281 $engine = "Catalyst::Engine::$ENV{CATALYST_ENGINE}"
282 if $ENV{CATALYST_ENGINE};
283 my $appeng = $ENV{ uc($caller) . '_ENGINE' };
284 $engine = "Catalyst::Engine::$appeng" if $appeng;
289 Catalyst::Exception->throw(
290 message => qq/Couldn't load engine "$engine", "$@"/
296 push @{"$caller\::ISA"}, $engine;
299 $caller->engine($engine);
300 $caller->log->debug(qq/Loaded engine "$engine"/) if $caller->debug;
303 my $home = Catalyst::Utils::home($caller);
305 if ( my $h = $ENV{CATALYST_HOME} ) {
310 $caller->log->warn(qq/CATALYST_HOME does not exist "$h"/);
313 unless ( -e _ && -d _ ) {
314 $caller->log->warn(qq/CATALYST_HOME is not a directory "$h"/);
318 if ( my $h = $ENV{ uc($caller) . '_HOME' } ) {
323 my $e = uc($caller) . '_HOME';
324 $caller->log->warn(qq/$e does not exist "$h"/)
327 unless ( -e _ && -d _ ) {
328 my $e = uc($caller) . '_HOME';
329 $caller->log->warn(qq/$e is not a directory "$h"/);
333 if ( $caller->debug ) {
336 ? $caller->log->debug(qq/Found home "$home"/)
337 : $caller->log->debug(qq/Home "$home" doesn't exist/)
338 : $caller->log->debug(q/Couldn't find home/);
340 $caller->config->{home} = $home || '';
341 $caller->config->{root} = defined $home ? dir($home)->subdir('root') : '';
346 Contains the engine class.
350 Contains the logging object. Unless it is already set Catalyst sets this up with a
351 C<Catalyst::Log> object. To use your own log class:
353 $c->log( MyLogger->new );
354 $c->log->info("now logging with my own logger!");
356 Your log class should implement the methods described in the C<Catalyst::Log>
359 =item $c->plugin( $name, $class, @args )
361 Instant plugins for Catalyst.
362 Classdata accessor/mutator will be created, class loaded and instantiated.
364 MyApp->plugin( 'prototype', 'HTML::Prototype' );
366 $c->prototype->define_javascript_functions;
371 my ( $class, $name, $plugin, @args ) = @_;
374 if ( my $error = $UNIVERSAL::require::ERROR ) {
375 Catalyst::Exception->throw(
376 message => qq/Couldn't load instant plugin "$plugin", "$error"/
380 eval { $plugin->import };
381 $class->mk_classdata($name);
383 eval { $obj = $plugin->new(@args) };
386 Catalyst::Exception->throw(
387 message => qq/Couldn't instantiate instant plugin "$plugin", "$@"/
392 $class->log->debug(qq/Initialized instant plugin "$plugin" as "$name"/)
400 mod_perl2 support is considered experimental and may contain bugs.
406 Join #catalyst on irc.perl.org.
410 http://lists.rawmode.org/mailman/listinfo/catalyst
411 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
415 http://catalyst.perl.org
421 =item L<Catalyst::Manual> - The Catalyst Manual
423 =item L<Catalyst::Engine> - Core Engine
425 =item L<Catalyst::Log> - The Log Class.
427 =item L<Catalyst::Request> - The Request Object
429 =item L<Catalyst::Response> - The Response Object
431 =item L<Catalyst::Test> - The test suite.
437 Sebastian Riedel, C<sri@oook.de>
441 Andy Grundman, Andrew Ford, Andrew Ruthven, Autrijus Tang, Christian Hansen,
442 Christopher Hicks, Dan Sully, Danijel Milicevic, David Naughton,
443 Gary Ashton Jones, Geoff Richards, Jesse Sheidlower, Jody Belka,
444 Johan Lindstrom, Juan Camacho, Leon Brocard, Marcus Ramberg,
445 Tatsuhiko Miyagawa and all the others who've helped.
449 This library is free software . You can redistribute it and/or modify it under
450 the same terms as perl itself.