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