[catagits/Catalyst-Runtime.git] / lib / Catalyst / Manual / Internals.pod

=head1 NAME

Catalyst::Manual::Internals - Catalyst Internals

=head1 DESCRIPTION

This document provides an overview of the internals of Catalyst.  As Catalyst
is still developing rapidly details may become out of date.

The coverage is split into initialization and request lifecycle.


=head2 Initialization

Catalyst initializes itself in two stages (I may be wrong in some of
the details here - AF):

=over 4

=item 1

When the Catalyst module is imported in the main application module it
evaluates any options (C<-Debug>, C<-Engine=XXX>) and loads any specified
plugins, making application module inherit from the plugin classes.  It also
sets up a default log object and ensures that the application module inherits
from C<Catalyst> and from the selected specialized Engine module.

=item 2

When the application module makes the first call to C<< __PACKAGE__->action() >>
(implemented in C<Catalyst::Engine>) Catalyst automatically loads all
components it finds in the C<$class\::Controller>, C<$class\::C>,
C<$class\::Model>, C<$class\::M>, C<$class\::View> and C<$class\::V>
namespaces (using C<Module::Pluggable::Fast>).  A table of actions is built up
and added to on subsequent calls to C<action()>.

=back


=head2 Request Lifecycle

For each request Catalyst builds a I<context> object, which includes
information about the request, and searches the action table for matching
actions.  

The handling of a request can be divided into three stages: preparation of the
context, processing of the request, and finalization of the response.  These
are the steps of a Catalyst request in detail; every step can be overloaded to
extend Catalyst.

    handler
      prepare
        prepare_request
        prepare_path
        prepare_headers
        prepare_cookies
        prepare_connection
        prepare_action
        prepare_body
        prepare_parameters
        prepare_uploads
      process
      finalize
        finalize_headers
        finalize_body

These steps are normally overloaded from engine classes, and may also be
extended by plugins.  Extending means using multiple inheritance with L<NEXT>.

The specialized engine classes populate the Catalyst request object with
information from the underlying layer (C<Apache::Request> or C<CGI::Simple>)
during the prepare phase, then push the generated response information down to
the underlying layer during the finalize phase.


=head1 AUTHOR

Sebastian Riedel, C<sri@oook.de>

=head1 COPYRIGHT

This program is free software, you can redistribute it and/or modify it under
the same terms as Perl itself.
Commit	Line	Data
fc7ec1d9	1	=head1 NAME
	2
	3	Catalyst::Manual::Internals - Catalyst Internals
	4
	5	=head1 DESCRIPTION
	6
5c57dc98	7	This document provides an overview of the internals of Catalyst. As Catalyst
5c57dc98	8	is still developing rapidly details may become out of date.
fc7ec1d9	9
5c57dc98	10	The coverage is split into initialization and request lifecycle.
	11
	12
	13	=head2 Initialization
	14
	15	Catalyst initializes itself in two stages (I may be wrong in some of
	16	the details here - AF):
	17
	18	=over 4
	19
	20	=item 1
	21
	22	When the Catalyst module is imported in the main application module it
	23	evaluates any options (C<-Debug>, C<-Engine=XXX>) and loads any specified
	24	plugins, making application module inherit from the plugin classes. It also
	25	sets up a default log object and ensures that the application module inherits
	26	from C<Catalyst> and from the selected specialized Engine module.
	27
	28	=item 2
	29
	30	When the application module makes the first call to C<< __PACKAGE__->action() >>
	31	(implemented in C<Catalyst::Engine>) Catalyst automatically loads all
	32	components it finds in the C<$class\::Controller>, C<$class\::C>,
	33	C<$class\::Model>, C<$class\::M>, C<$class\::View> and C<$class\::V>
	34	namespaces (using C<Module::Pluggable::Fast>). A table of actions is built up
	35	and added to on subsequent calls to C<action()>.
	36
	37	=back
	38
	39
	40	=head2 Request Lifecycle
	41
	42	For each request Catalyst builds a I<context> object, which includes
	43	information about the request, and searches the action table for matching
	44	actions.
	45
	46	The handling of a request can be divided into three stages: preparation of the
	47	context, processing of the request, and finalization of the response. These
	48	are the steps of a Catalyst request in detail; every step can be overloaded to
fc7ec1d9	49	extend Catalyst.
	50
	51	handler
	52	prepare
	53	prepare_request
	54	prepare_path
fc7ec1d9	55	prepare_headers
06e1b616	56	prepare_cookies
585893b9	57	prepare_connection
fc7ec1d9	58	prepare_action
06e1b616	59	prepare_body
fc7ec1d9	60	prepare_parameters
	61	prepare_uploads
	62	process
	63	finalize
	64	finalize_headers
06e1b616	65	finalize_body
fc7ec1d9	66
5c57dc98	67	These steps are normally overloaded from engine classes, and may also be
	68	extended by plugins. Extending means using multiple inheritance with L<NEXT>.
	69
	70	The specialized engine classes populate the Catalyst request object with
	71	information from the underlying layer (C<Apache::Request> or C<CGI::Simple>)
	72	during the prepare phase, then push the generated response information down to
	73	the underlying layer during the finalize phase.
	74
fc7ec1d9	75
	76	=head1 AUTHOR
	77
	78	Sebastian Riedel, C<sri@oook.de>
	79
	80	=head1 COPYRIGHT
	81
	82	This program is free software, you can redistribute it and/or modify it under
	83	the same terms as Perl itself.