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 | |
25 | |
26 | =item 2 |
27 | |
c312468f |
28 | When C<< __PACKAGE__->setup >> is called, it evaluates any |
0e8eed8e |
29 | options stored (C<-Debug>), and makes the application |
b1a08fe1 |
30 | inherit from L<Catalyst> (if that hasn't already been done with an |
31 | explicit C<< use base 'Catalyst'; >> or C<< extends 'Catalyst'; >>. |
32 | Any specified plugins are then loaded, the application module is made to |
cb93c9d7 |
33 | inherit from the plugin classes. It also sets up a default log |
34 | object and ensures that the application module inherits from |
35 | C<Catalyst> and from the selected specialized Engine module. |
36 | |
b1a08fe1 |
37 | =item 3 |
cb93c9d7 |
38 | |
b1a08fe1 |
39 | Catalyst automatically loads all |
cb93c9d7 |
40 | components it finds in the C<$class::Controller>, C<$class::C>, |
41 | C<$class::Model>, C<$class::M>, C<$class::View> and C<$class::V> |
b1a08fe1 |
42 | namespaces (using C<Module::Pluggable>). As each is loaded, if it has a |
43 | L<Catalyst::Component/COMPONENT|COMPONENT> method then this method |
44 | will be called, and passed that component's configuration. It then returns |
45 | an instance of the component, which becomes the C<$self> when methods in |
46 | that component are called later. |
cb93c9d7 |
47 | |
b1a08fe1 |
48 | =item 4 |
49 | |
50 | Each controller has it's C<register_actions> method called. At this point, |
51 | the subroutine attributes are retrieved from the |
52 | L<MooseX::MethodAttributes::Role::Meta::Map|metaclass>, parsed, and used to |
53 | build instances of L<Catalyst::Action>, which are then registered with |
54 | the dispatcher. |
cb93c9d7 |
55 | |
b1a08fe1 |
56 | =back |
cb93c9d7 |
57 | |
58 | =head2 Request Lifecycle |
59 | |
60 | For each request Catalyst builds a I<context> object, which includes |
61 | information about the request, and then searches the action table for matching |
b1a08fe1 |
62 | actions. |
cb93c9d7 |
63 | |
64 | The handling of a request can be divided into three stages: preparation of the |
65 | context, processing of the request, and finalization of the response. These |
66 | are the steps of a Catalyst request in detail; every step can be overloaded to |
67 | extend Catalyst. |
68 | |
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 |
89 | |
90 | These steps are normally overloaded from engine classes, and may also be |
9a4214e1 |
91 | extended by plugins. For more on extending Catalyst, see L<Catalyst::Manual::ExtendingCatalyst>. |
cb93c9d7 |
92 | |
0e8eed8e |
93 | The engine class populate sthe Catalyst request object with |
94 | information from the underlying layer (L<PSGI>) |
cb93c9d7 |
95 | during the prepare phase, then push the generated response information down to |
96 | the underlying layer during the finalize phase. |
97 | |
bbddff00 |
98 | =head1 AUTHORS |
cb93c9d7 |
99 | |
bbddff00 |
100 | Catalyst Contributors, see Catalyst.pm |
cb93c9d7 |
101 | |
102 | =head1 COPYRIGHT |
103 | |
bbddff00 |
104 | This library is free software. You can redistribute it and/or modify it under |
cb93c9d7 |
105 | the same terms as Perl itself. |
b1a08fe1 |
106 | |
bbddff00 |
107 | =cut |