[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_cookies
        prepare_headers
        prepare_connection
        prepare_action
        prepare_parameters
        prepare_uploads
      process
      finalize
        finalize_headers
        finalize_output

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
	55	prepare_cookies
	56	prepare_headers
585893b9	57	prepare_connection
fc7ec1d9	58	prepare_action
	59	prepare_parameters
	60	prepare_uploads
	61	process
	62	finalize
	63	finalize_headers
	64	finalize_output
	65
5c57dc98	66	These steps are normally overloaded from engine classes, and may also be
	67	extended by plugins. Extending means using multiple inheritance with L<NEXT>.
	68
	69	The specialized engine classes populate the Catalyst request object with
	70	information from the underlying layer (C<Apache::Request> or C<CGI::Simple>)
	71	during the prepare phase, then push the generated response information down to
	72	the underlying layer during the finalize phase.
	73
fc7ec1d9	74
	75	=head1 AUTHOR
	76
	77	Sebastian Riedel, C<sri@oook.de>
	78
	79	=head1 COPYRIGHT
	80
	81	This program is free software, you can redistribute it and/or modify it under
	82	the same terms as Perl itself.