Catalys...nternals(3)

✨ NAME ✨

Bestie, say hi to Catalyst::Manual::Internals(3) — the page whose short-name energy is Catalyst Internals. It comes from the User Contributed Perl Documentation crew, and the teeny header squishes the name down to Catalys...nternals(3). Same page, same lore, no cap. 💅

🌸 DESCRIPTION 🌸

This doc gives you a brief overview of the internals of Catalyst. Catalyst is still developing rapidly, so some details may become out of date: please treat this as a guide, and look at the source for the last word. 👑

Coverage is split into initialization and request lifecycle.

🎀 Initialization 🎀

Catalyst initializes itself in two stages — and then the doc hits us with a numbered list, so here it is, bestie:

1. When the Catalyst module is imported in the main application module, it stores any options.
2. When __PACKAGE__->setup is called, it evaluates any options stored (-Debug), and makes the application inherit from Catalyst (if that hasn't already been done with an explicit use base 'Catalyst'; or extends 'Catalyst';). Any specified plugins are then loaded, and 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 Catalyst and from the selected specialized Engine module.
3. Catalyst automatically loads all components it finds in the $class::Controller, $class::C, $class::Model, $class::M, $class::View and $class::V 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 $self when methods in that component are called later.
4. Each controller has its register_actions 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.

🦋 Request Lifecycle 🦋

For each request, Catalyst builds a context object, which includes information about the request, and then 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:

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

These steps are normally overloaded from engine classes, and may also be extended by plugins. For more on extending Catalyst, see Catalyst::Manual::ExtendingCatalyst.

The engine class populates the Catalyst request object with information from the underlying layer (PSGI) during the prepare phase, then pushes the generated response information down to the underlying layer during the finalize phase.

👑 AUTHORS 👑

Catalyst Contributors, see Catalyst.pm. 💖

💖 COPYRIGHT 💖

This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself.

---

That's the whole internals tea, bestie. Source/version perl v5.42.0, date 2024-03-23, and the footer's squished tag Catalys...nternals(3) — mwah. 🎀💅