#maybe we should just make them attributes with a default?
__PACKAGE__->mk_classdata($_)
for qw/components arguments dispatcher engine log dispatcher_class
- engine_class context_class request_class response_class stats_class
+ engine_class context_class request_class response_class stats_class
setup_finished/;
__PACKAGE__->dispatcher_class('Catalyst::Dispatcher');
# Remember to update this in Catalyst::Runtime as well!
-our $VERSION = '5.80002';
+our $VERSION = '5.80003';
{
my $dev_version = $VERSION =~ /_\d{2}$/;
### in lib/MyApp.pm
use Catalyst qw/-Debug/; # include plugins here as well
-
+
### In lib/MyApp/Controller/Root.pm (autocreated)
sub foo : Global { # called for /foo, /foo/1, /foo/1/2, etc.
my ( $self, $c, @args ) = @_; # args are qw/1 2/ for /foo/1/2
$c->stash->{template} = 'foo.tt'; # set the template
# lookup something from db -- stash vars are passed to TT
- $c->stash->{data} =
+ $c->stash->{data} =
$c->model('Database::Foo')->search( { country => $args[0] } );
if ( $c->req->params->{bar} ) { # access GET or POST parameters
$c->forward( 'bar' ); # process another action
- # do something else after forward returns
+ # do something else after forward returns
}
}
-
+
# The foo.tt TT template can use the stash data from the database
[% WHILE (item = data.next) %]
[% item.foo %]
[% END %]
-
+
# called for /bar/of/soap, /bar/of/soap/10, etc.
sub bar : Path('/bar/of/soap') { ... }
# called for all actions, from the top-most controller downwards
- sub auto : Private {
+ sub auto : Private {
my ( $self, $c ) = @_;
if ( !$c->user_exists ) { # Catalyst::Plugin::Authentication
$c->res->redirect( '/login' ); # require login
}
return 1; # success; carry on to next action
}
-
+
# called after all actions are finished
- sub end : Private {
+ sub end : Private {
my ( $self, $c ) = @_;
if ( scalar @{ $c->error } ) { ... } # handle errors
return if $c->res->body; # already have a response
### in MyApp/Controller/Foo.pm
# called for /foo/bar
sub bar : Local { ... }
-
+
# called for /blargle
sub blargle : Global { ... }
-
+
# an index action matches /foo, but not /foo/1, etc.
sub index : Private { ... }
-
+
### in MyApp/Controller/Foo/Bar.pm
# called for /foo/bar/baz
sub baz : Local { ... }
-
+
# first Root auto is called, then Foo auto, then this
sub auto : Private { ... }
-
+
# powerful regular expression paths are also possible
sub details : Regex('^product/(\w+)/details$') {
my ( $self, $c ) = @_;
=head2 -Log
use Catalyst '-Log=warn,fatal,error';
-
+
Specifies a comma-delimited list of log levels.
=head2 -Stats
environment settings override the application, with <MYAPP>_STATS having the
highest priority.
-e.g.
+e.g.
use Catalyst qw/-Stats=1/
=head2 $c->detach()
-The same as C<forward>, but doesn't return to the previous action when
-processing is finished.
+The same as C<forward>, but doesn't return to the previous action when
+processing is finished.
When called with no arguments it escapes the processing chain entirely.
$c->stash->{foo} = $bar;
$c->stash( { moose => 'majestic', qux => 0 } );
$c->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref
-
+
# stash is automatically passed to the view for use in a template
$c->forward( 'MyApp::View::TT' );
return @result;
}
-# Find possible names for a prefix
+# Find possible names for a prefix
sub _comp_names {
my ( $c, @prefixes ) = @_;
my $appclass = ref $c || $c;
if ( eval { $comp->can('ACCEPT_CONTEXT'); } ) {
return $comp->ACCEPT_CONTEXT( $c, @args );
}
-
+
return $comp;
}
Any extra arguments are directly passed to ACCEPT_CONTEXT.
-If the name is omitted, it will look for
+If the name is omitted, it will look for
- a model object in $c->stash->{current_model_instance}, then
- a model name in $c->stash->{current_model}, then
- a config setting 'default_model', or
}
if (ref $c) {
- return $c->stash->{current_model_instance}
+ return $c->stash->{current_model_instance}
if $c->stash->{current_model_instance};
return $c->model( $c->stash->{current_model} )
if $c->stash->{current_model};
Any extra arguments are directly passed to ACCEPT_CONTEXT.
-If the name is omitted, it will look for
+If the name is omitted, it will look for
- a view object in $c->stash->{current_view_instance}, then
- a view name in $c->stash->{current_view}, then
- a config setting 'default_view', or
}
if (ref $c) {
- return $c->stash->{current_view_instance}
+ return $c->stash->{current_view_instance}
if $c->stash->{current_view_instance};
return $c->view( $c->stash->{current_view} )
if $c->stash->{current_view};
The config method is present on all Catalyst components, and configuration
will be merged when an application is started. Configuration loaded with
L<Catalyst::Plugin::ConfigLoader> takes precedence over other configuration,
-followed by configuration in your top level C<MyApp> class. These two
-configurations are merged, and then configuration data whos hash key matches a
+followed by configuration in your top level C<MyApp> class. These two
+configurations are merged, and then configuration data whose hash key matches a
component name is merged with configuration for that component.
The configuration for a component is then passed to the C<new> method when a
MyApp->config({ 'Model::Foo' => { bar => 'baz', overrides => 'me' } });
MyApp::Model::Foo->config({ quux => 'frob', 'overrides => 'this' });
-
-will mean that C<MyApp::Model::Foo> receives the following data when
+
+will mean that C<MyApp::Model::Foo> receives the following data when
constructed:
MyApp::Model::Foo->new({
=over
+=item By calling myapp_server.pl with the -d flag
+
=item With the environment variables MYAPP_DEBUG, or CATALYST_DEBUG
=item The -Debug option in your MyApp.pm
-=item By declaring "sub debug { 1 }" in your MyApp.pm.
+=item By declaring C<sub debug { 1 }> in your MyApp.pm.
=back
-Calling $c->debug(1) has no effect.
+Calling C<< $c->debug(1) >> has no effect.
=cut
EOF
}
-
+
if ( $class->debug ) {
my @plugins = map { "$_ " . ( $_->VERSION || '' ) } $class->registered_plugins;
}
$class->log->_flush() if $class->log->can('_flush');
- # Make sure that the application class becomes immutable at this point,
- # which ensures that it gets an inlined constructor. This means that it
+ # Make sure that the application class becomes immutable at this point,
+ # which ensures that it gets an inlined constructor. This means that it
# works even if the user has added a plugin which contains a new method.
# Note however that we have to do the work on scope end, so that method
- # modifiers work correctly in MyApp (as you have to call setup _before_
+ # modifiers work correctly in MyApp (as you have to call setup _before_
# applying modifiers).
Scope::Upper::reap(sub {
my $meta = Class::MOP::get_metaclass_by_name($class);
+ if ( $meta->is_immutable && ! { $meta->immutable_options }->{inline_constructor} ) {
+ die "You made your application class ($class) immutable, "
+ . "but did not inline the constructor.\n"
+ . "This will break catalyst, please pass "
+ . "(replace_constructor => 1) when making your class immutable.\n";
+ }
$meta->make_immutable(replace_constructor => 1) unless $meta->is_immutable;
}, Scope::Upper::SCOPE(1));
call C<action_for> on it.
You can maintain the arguments captured by an action (e.g.: Regex, Chained)
-using C<< $c->req->captures >>.
+using C<< $c->req->captures >>.
# For the current action
$c->uri_for($c->action, $c->req->captures);
-
+
# For the Foo action in the Bar controller
$c->uri_for($c->controller->('Bar')->action_for('Foo'), $c->req->captures);
( scalar @args && ref $args[$#args] eq 'HASH' ? pop @args : {} );
carp "uri_for called with undef argument" if grep { ! defined $_ } @args;
- s/([^$URI::uric])/$URI::Escape::escapes{$1}/go for @args;
+ s/([^A-Za-z0-9\-_.!~*'()])/$URI::Escape::escapes{$1}/go for @args;
unshift(@args, $path);
}
unshift(@args, $namespace || '');
}
-
+
# join args with '/', or a blank string
my $args = join('/', grep { defined($_) } @args);
$args =~ s/\?/%3F/g; # STUPID STUPID SPECIAL CASE
$_ = "$_";
utf8::encode( $_ ) if utf8::is_utf8($_);
# using the URI::Escape pattern here so utf8 chars survive
- s/([^A-Za-z0-9\-_.!~*'() ])/$URI::Escape::escapes{$1}/go;
+ s/([^A-Za-z0-9\-_.!~*'()])/$URI::Escape::escapes{$1}/go;
s/ /+/g;
"${key}=$_"; } ( ref $val eq 'ARRAY' ? @$val : $val ));
} @keys);
sub uri_for_action {
my ( $c, $path, @args ) = @_;
- my $action = blessed($path)
- ? $path
+ my $action = blessed($path)
+ ? $path
: $c->dispatcher->get_action_by_path($path);
unless (defined $action) {
croak "Can't find action for path '$path'";
</li>
</ul>
<h2>In conclusion</h2>
- <p>The Catalyst team hopes you will enjoy using Catalyst as much
+ <p>The Catalyst team hopes you will enjoy using Catalyst as much
as we enjoyed making it. Please contact us if you have ideas
for improvement or other feedback.</p>
</div>
sub dump_these {
my $c = shift;
- [ Request => $c->req ],
- [ Response => $c->res ],
+ [ Request => $c->req ],
+ [ Response => $c->res ],
[ Stash => $c->stash ],
[ Config => $c->config ];
}
my $stats_info = $c->_stats_start_execute( $code ) if $c->use_stats;
push( @{ $c->stack }, $code );
-
+
no warnings 'recursion';
eval { $c->state( $code->execute( $class, $c, @{ $c->req->args } ) || 0 ) };
$c->_stats_finish_execute( $stats_info ) if $c->use_stats and $stats_info;
-
+
my $last = pop( @{ $c->stack } );
if ( my $error = $@ ) {
# forward, locate the caller
if ( my $parent = $c->stack->[-1] ) {
$c->stats->profile(
- begin => $action,
+ begin => $action,
parent => "$parent" . $c->counter->{"$parent"},
uid => $uid,
);
}
}
else {
-
+
# root-level call
$c->stats->profile(
begin => $action,
my $request = delete $localized->{request} || {};
my $response = delete $localized->{response} || {};
-
+
local @{ $c }{ keys %$localized } = values %$localized;
local @{ $c->request }{ keys %$request } = values %$request;
local @{ $c->response }{ keys %$response } = values %$response;
$c->finalize_body;
}
-
- if ($c->use_stats) {
+
+ if ($c->use_stats) {
my $elapsed = sprintf '%f', $c->stats->elapsed;
my $av = $elapsed == 0 ? '??' : sprintf '%.3f', 1 / $elapsed;
$c->log->info(
- "Request took ${elapsed}s ($av/s)\n" . $c->stats->report . "\n" );
+ "Request took ${elapsed}s ($av/s)\n" . $c->stats->report . "\n" );
}
return $c->response->status;
my $c = $class->prepare(@arguments);
$c->dispatch;
- $status = $c->finalize;
+ $status = $c->finalize;
};
if ( my $error = $@ ) {
}
$COUNT++;
-
+
if(my $coderef = $class->log->can('_flush')){
$class->log->$coderef();
}
# After the app/ctxt split, this should become an attribute based on something passed
# into the application.
$class->context_class( ref $class || $class ) unless $class->context_class;
-
+
my $c = $class->context_class->new({});
# For on-demand data
#surely this is not the most efficient way to do things...
$c->stats($class->stats_class->new)->enable($c->use_stats);
if ( $c->debug ) {
- $c->res->headers->header( 'X-Catalyst' => $Catalyst::VERSION );
+ $c->res->headers->header( 'X-Catalyst' => $Catalyst::VERSION );
}
#XXX reuse coderef from can
# Prepare the body for reading, either by prepare_body
# or the user, if they are using $c->read
$c->prepare_read;
-
+
# Parse the body unless the user wants it on-demand
unless ( $c->config->{parse_on_demand} ) {
$c->prepare_body;
reference. Items in the array beginning with C<::> will have the
application class name prepended to them.
-All components found will also have any
+All components found will also have any
L<Devel::InnerPackage|inner packages> loaded and set up as components.
Note, that modules which are B<not> an I<inner package> of the main
file namespace loaded will not be instantiated as components.
my @paths = qw( ::Controller ::C ::Model ::M ::View ::V );
my $config = $class->config->{ setup_components };
my $extra = delete $config->{ search_extra } || [];
-
+
push @paths, @$extra;
-
+
my $locator = Module::Pluggable::Object->new(
search_path => [ map { s/^(?=::)/$class/; $_; } @paths ],
%$config
$component => $module,
map {
$_ => $class->setup_component( $_ )
- } grep {
+ } grep {
not exists $comps{$_}
} Devel::InnerPackage::list_packages( $component )
);
-
+
for my $key ( keys %modules ) {
$class->components->{ $key } = $modules{ $key };
}
=cut
sub _controller_init_base_classes {
- my ($class, $component) = @_;
+ my ($app_class, $component) = @_;
foreach my $class ( reverse @{ mro::get_linear_isa($component) } ) {
Moose->init_meta( for_class => $class )
unless find_meta($class);
if ($component->isa('Catalyst::Controller')) {
$class->_controller_init_base_classes($component);
}
-
+
my $suffix = Catalyst::Utils::class2classsuffix( $component );
my $config = $class->config->{ $suffix } || {};
if ( $ENV{MOD_PERL} ) {
my $meta = Class::MOP::get_metaclass_by_name($class);
-
+
# create the apache method
$meta->add_method('apache' => sub { shift->engine->apache });
Sets up log by instantiating a L<Catalyst::Log|Catalyst::Log> object and
passing it to C<log()>. Pass in a comma-delimited list of levels to set the
log to.
-
+
This method also installs a C<debug> method that returns a true value into the
catalyst subclass if the "debug" level is passed in the comma-delimited list,
or if the C<$CATALYST_DEBUG> environment variable is set to a true value.
}
-=head2 $c->registered_plugins
+=head2 $c->registered_plugins
Returns a sorted list of the plugins which have either been stated in the
import list or which have been added via C<< MyApp->plugin(@args); >>.
when the -Stats options is set, debug is on or when the <MYAPP>_STATS
environment variable is set.
-Note that this is a static method, not an accessor and should be overloaded
-by declaring "sub use_stats { 1 }" in your MyApp.pm, not by calling $c->use_stats(1).
+Note that this is a static method, not an accessor and should be overridden
+by declaring C<sub use_stats { 1 }> in your MyApp.pm, not by calling C<< $c->use_stats(1) >>.
=cut
parsing with a config parameter.
MyApp->config->{parse_on_demand} = 1;
-
+
=head1 PROXY SUPPORT
Many production servers operate using the common double-server approach,
the frontend and backend servers on the same machine. The following
changes are made to the request.
- $c->req->address is set to the user's real IP address, as read from
+ $c->req->address is set to the user's real IP address, as read from
the HTTP X-Forwarded-For header.
-
+
The host value for $c->req->base and $c->req->uri is set to the real
host, as read from the HTTP X-Forwarded-Host header.
headers.
MyApp->config->{using_frontend_proxy} = 1;
-
+
If you do not wish to use the proxy support at all, you may set:
MyApp->config->{ignore_frontend_proxy} = 1;