/ 
Minima-v0.5.0
River stage zero No dependents
/ Minima::App

NAME

Minima::App - Application class for Minima

SYNOPSIS

use Minima::App;

my $app = Minima::App->new(
    environment => $env,
    configuration => { },
);
$app->run;

DESCRIPTION

Minima::App is the core of a Minima web application. It handles starting the app, connecting to the router, and dispatching route matches. For more details on this process, refer to the run method.

Three key components of an app are the routes file, the configuration hash, and the environment hash.

  • The routes file describes the application's routes. Minima::App checks for its existence and passes it to the router, which handles reading and processing the routes. For details on configuring and specifying the location of the routes file, see the routes configuration key and Minima::Router.

  • The configuration hash is central to many operations. This hash is usually loaded from a file, though it can be passed directly to the new method. This is usually handled by Minima::Setup.

    A reference for the configuration keys used by Minima::App is provided below. Other modules may also utilize the configuration hash, so refer to their documentation for module-specific details.

  • Lastly, the environment hash is a reference to the PSGI environment. Since it's essential for route matching, it must be set before running the app.

Configuration

automatic_head

Automatically remove the response body for HEAD requests. Defaults to true. See also: "Routes File" in Minima::Router.

base_dir

The base directory of the application. If not specified, it defaults to the current directory (.). This is used to resolve relative paths to absolute paths when needed.

Note that in a typical case, Minima::Setup sets base_dir before Minima::App runs, defaulting to the directory of the main .psgi file unless it is explicitly set in the configuration.

controller_prefix

The default prefix prepended to controller names in the routes file when using the : shortcut. See also: "Controller" in Minima::Router.

routes

The location of the routes file. If not specified, it defaults to etc/routes.map relative to the base_dir. If no file is found at that location and this key isn't provided, the app will load a blank state, where it returns a 200 response for the root path and a 404 for any other route.

VERSION

The current application version. Instead of passing it directly, you can use the version_from key to auto-populate this. If neither VERSION not version_from are provided, it defaults to 'prototype'.

version_from

Name of a class from which to extract and set VERSION. Only used if VERSION wasn't given explicitly.

METHODS

new

method new (environment = undef, configuration = {})

Instantiates the app with the provided Plack environment and configuration hash. Both parameters are optional, but the environment is required to run the app. If not passed during construction, make sure to call set_env before run. Configuration keys used by Minima::App are described under "Configuration".

run

method run ()

Runs the application by querying the router for a match to PATH_INFO (the URL in the environment hash) and dispatching it. The enviroment must already be set.

If the controller-action call fails, Minima::App checks for the existence of an error route. If the app is not in development mode and the error route is set, it is called to handle the exception, with the error message passed as an argument.

If no error route is set, the app dies, passing the exception forward to be handled by any other middleware.

development

method development ()

Utility method that returns true if $ENV{PLACK_ENV} is set to development or if it is unset. Returns false otherwise.

path

method path ($path)

Utility method that resolves a relative path against the application's base directory. If the provided path is already absolute, it returns the path unchanged.

ATTRIBUTES

The attributes below are accessible via reader methods and can be set with methods of the same name prefixed by set_.

config, set_config

Returns or sets the configuration hash.

env, set_env

Returns or sets the environment hash.

SEE ALSO

Minima, Minima::Setup, Minima::Router, Minima::Controller, perlclass.

AUTHOR

Cesar Tessarin, <cesar@tessarin.com.br>.

Written in September 2024.