fix backwards link
[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / Internals.pod
cb93c9d7 1=head1 NAME
3Catalyst::Manual::Internals - Catalyst Internals
9a4214e1 7This document provides a brief overview of the internals of
cb93c9d7 8Catalyst. As Catalyst is still developing rapidly, details
9may become out of date: please treat this as a guide, and
10look at the source for the last word.
12The coverage is split into initialization and request lifecycle.
14=head2 Initialization
9a4214e1 16Catalyst initializes itself in two stages:
cb93c9d7 17
18=over 4
20=item 1
22When the Catalyst module is imported in the main application
c312468f 23module, it stores any options.
b1a08fe1 24
26=item 2
c312468f 28When C<< __PACKAGE__->setup >> is called, it evaluates any
0e8eed8e 29options stored (C<-Debug>), and makes the application
b1a08fe1 30inherit from L<Catalyst> (if that hasn't already been done with an
31explicit C<< use base 'Catalyst'; >> or C<< extends 'Catalyst'; >>.
32Any specified plugins are then loaded, the application module is made to
cb93c9d7 33inherit from the plugin classes. It also sets up a default log
34object and ensures that the application module inherits from
35C<Catalyst> and from the selected specialized Engine module.
b1a08fe1 37=item 3
cb93c9d7 38
b1a08fe1 39Catalyst automatically loads all
cb93c9d7 40components it finds in the C<$class::Controller>, C<$class::C>,
41C<$class::Model>, C<$class::M>, C<$class::View> and C<$class::V>
b1a08fe1 42namespaces (using C<Module::Pluggable>). As each is loaded, if it has a
e0dfa383 43L<COMPONENT|Catalyst::Component/"COMPONENT"> method then this method
b1a08fe1 44will be called, and passed that component's configuration. It then returns
45an instance of the component, which becomes the C<$self> when methods in
46that component are called later.
cb93c9d7 47
b1a08fe1 48=item 4
50Each controller has it's C<register_actions> method called. At this point,
51the subroutine attributes are retrieved from the
52L<MooseX::MethodAttributes::Role::Meta::Map|metaclass>, parsed, and used to
53build instances of L<Catalyst::Action>, which are then registered with
54the dispatcher.
cb93c9d7 55
b1a08fe1 56=back
cb93c9d7 57
58=head2 Request Lifecycle
60For each request Catalyst builds a I<context> object, which includes
61information about the request, and then searches the action table for matching
b1a08fe1 62actions.
cb93c9d7 63
64The handling of a request can be divided into three stages: preparation of the
65context, processing of the request, and finalization of the response. These
66are the steps of a Catalyst request in detail; every step can be overloaded to
67extend Catalyst.
69 handle_request
70 prepare
71 prepare_request
72 prepare_connection
73 prepare_query_parameters
74 prepare_headers
75 prepare_cookies
76 prepare_path
77 prepare_body (unless parse_on_demand)
78 prepare_body_parameters
79 prepare_parameters
80 prepare_uploads
81 prepare_action
82 dispatch
83 finalize
84 finalize_uploads
85 finalize_error (if one happened)
86 finalize_headers
87 finalize_cookies
88 finalize_body
90These steps are normally overloaded from engine classes, and may also be
9a4214e1 91extended by plugins. For more on extending Catalyst, see L<Catalyst::Manual::ExtendingCatalyst>.
cb93c9d7 92
0e8eed8e 93The engine class populate sthe Catalyst request object with
94information from the underlying layer (L<PSGI>)
cb93c9d7 95during the prepare phase, then push the generated response information down to
96the underlying layer during the finalize phase.
bbddff00 98=head1 AUTHORS
cb93c9d7 99
bbddff00 100Catalyst Contributors, see
cb93c9d7 101
102=head1 COPYRIGHT
bbddff00 104This library is free software. You can redistribute it and/or modify it under
cb93c9d7 105the same terms as Perl itself.
b1a08fe1 106
bbddff00 107=cut