.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Catalyst::Manual::Internals 3pm"
.TH Catalyst::Manual::Internals 3pm 2024-03-30 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Catalyst::Manual::Internals \- Catalyst Internals
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This document provides a brief overview of the internals of
Catalyst.  As Catalyst is still developing rapidly, details
may become out of date: please treat this as a guide, and
look at the source for the last word.
.PP
The coverage is split into initialization and request lifecycle.
.SS Initialization
.IX Subsection "Initialization"
Catalyst initializes itself in two stages:
.IP 1. 4
When the Catalyst module is imported in the main application
module, it stores any options.
.IP 2. 4
When \f(CW\*(C`_\|_PACKAGE_\|_\->setup\*(C'\fR is called, it evaluates any
options stored (\f(CW\*(C`\-Debug\*(C'\fR), and makes the application
inherit from Catalyst (if that hasn't already been done with an
explicit \f(CW\*(C`use base \*(AqCatalyst\*(Aq;\*(C'\fR or \f(CW\*(C`extends \*(AqCatalyst\*(Aq;\*(C'\fR.
Any specified plugins are then loaded, the application module is made to
inherit from the plugin classes. It also sets up a default log
object and ensures that the application module inherits from
\&\f(CW\*(C`Catalyst\*(C'\fR and from the selected specialized Engine module.
.IP 3. 4
Catalyst automatically loads all
components it finds in the \f(CW$class::Controller\fR, \f(CW$class::C\fR,
\&\f(CW$class::Model\fR, \f(CW$class::M\fR, \f(CW$class::View\fR and \f(CW$class::V\fR
namespaces (using Module::Pluggable). As each is loaded, if it has a
COMPONENT method then this method
will be called, and passed that component's configuration. It then returns
an instance of the component, which becomes the \f(CW$self\fR when methods in
that component are called later.
.IP 4. 4
Each controller has it's \f(CW\*(C`register_actions\*(C'\fR method called. At this point,
the subroutine attributes are retrieved from the
metaclass, parsed, and used to
build instances of Catalyst::Action, which are then registered with
the dispatcher.
.SS "Request Lifecycle"
.IX Subsection "Request Lifecycle"
For each request Catalyst builds a \fIcontext\fR object, which includes
information about the request, and then searches the action table for matching
actions.
.PP
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.
.PP
.Vb 10
\&    handle_request
\&      prepare
\&        prepare_request
\&        prepare_connection
\&        prepare_query_parameters
\&        prepare_headers
\&        prepare_cookies
\&        prepare_path
\&        prepare_body (unless parse_on_demand)
\&          prepare_body_parameters
\&          prepare_parameters
\&          prepare_uploads
\&        prepare_action
\&      dispatch
\&      finalize
\&        finalize_uploads
\&        finalize_error (if one happened)
\&        finalize_headers
\&          finalize_cookies
\&        finalize_body
.Ve
.PP
These steps are normally overloaded from engine classes, and may also be
extended by plugins. For more on extending Catalyst, see Catalyst::Manual::ExtendingCatalyst.
.PP
The engine class populates the Catalyst request object with
information from the underlying layer (PSGI)
during the prepare phase, then push the generated response information down to
the underlying layer during the finalize phase.
.SH AUTHORS
.IX Header "AUTHORS"
Catalyst Contributors, see Catalyst.pm
.SH COPYRIGHT
.IX Header "COPYRIGHT"
This library is free software. You can redistribute it and/or modify it under
the same terms as Perl itself.