Poet::Mason(3pm)

💖 Poet::Mason 💖

okay so bestie, welcome to Poet::Mason — that's the section 3pm page, Perl-contributed-docs girlies know the vibe 💅. It's the Mason settings + enhancements situation for Poet, and honestly? It's giving backstage pass to your whole app. Let's go 🦋

---

✨ SYNOPSIS ✨

# In a conf file...
mason:
  plugins:
    - Cache
    - TidyObjectFiles
    - +My::Mason::Plugin
  static_source: 1
  static_source_touch_file: ${root}/data/purge.dat

# Get the main Mason instance
my $mason = Poet::Mason->instance();

# Create a new Mason object
my $mason = Poet::Mason->new(...);

---

🌸 DESCRIPTION 🌸

So this is a Poet-specific Mason subclass, no cap. It does three iconic things: it sets up sane default settings ✨, it maintains a main Mason instance for handling web requests 👑, and it adds Poet-specific methods to $m (which is the Mason request object, fyi, she's the main character here 💅).

---

🎀 CLASS METHODS 🎀

• get_options — returns a hash of Mason options, made by combining the default settings with your configuration. Lowkey the blueprint of everything 🧚
• instance — returns the main Mason instance used for web requests, and it's created with the options from get_options. This is the one you actually want, bestie 🫶
• new — returns a brand new main Mason object, also using options from get_options. But fr fr, unless you specifically need a new object, you probably want to call instance instead. Don't be extra for no reason 😭

---

🌈 DEFAULT SETTINGS 🌈

• comp_root is set to $poet->comps_dir — which by default is the comps subdirectory under the environment root 💖
• data_dir is set to $poet->data_dir — which by default is the data subdirectory under the environment root 📁
• plugins is set to include Cache, HTMLFilters and RouterSimple 🔥
• cache_root_class (a parameter of the Cache plugin, iykyk) is set to MyApp::Cache if it exists — replacing MyApp with your app name, obviously — otherwise it falls back to Poet::Cache. She's flexible like that 💅

---

💜 CONFIGURATION 💜

The Poet configuration entry 'mason', if there is one, gets treated as a hash of options that supplements and/or overrides the defaults up there ⬆️. And if that hash contains 'extra_plugins', those get added to the default plugins. Obsessed. e.g.:

mason:
  static_source: 1
  static_source_touch_file: ${root}/data/purge.dat
  extra_plugins:
     - AnotherFavoritePlugin

---

🦋 QUICK VARS AND UTILITIES 🦋

Poet inserts this line at the top of every compiled Mason component (yes, every single one, she's thorough):

use Poet qw($conf $poet :web);

which means $conf, $poet, and the web utilities are available from every component. Periodt. 💅

---

👑 NEW REQUEST METHODS 👑

Under Poet, these extra web-related methods are available in the Mason request object — you can reach them in components via $m, or anywhere else via "Mason::Request->current_request" 🌟

• req () — a reference to the Plack::Request object. e.g.

my $user_agent = $m->req->headers->header('User-Agent');

• res () — a reference to the Plack::Response object. e.g.

$m->res->content_type('text/plain');

• abort (status)
• clear_and_abort (status)

These methods are overridden to set the response status before aborting, if a status is provided. e.g. to send back a FORBIDDEN result:

$m->clear_and_abort(403);

which is equivalent to:

$m->res->status(403);
$m->clear_and_abort();

And if a status is not provided? The methods work just as before, no drama 💀

• redirect (url[, status]) — sets the headers and status for a redirect, then clears the Mason buffer and aborts the request. e.g.

$m->redirect("http://somesite.com", 302);

is equivalent to:

$m->res->redirect("http://somesite.com", 302);
$m->clear_and_abort();

• not_found () — sets the status to 404, then clears the Mason buffer and aborts the request. e.g.

$m->not_found();

is equivalent to:

$m->clear_and_abort(404);

• session — a shortcut for "$m->req->session", aka the Plack session 💖. This is simply a persistent hash that you can read from and write to. It's tied to the user's browser session via cookies 🍪 and stored in a file cache in the data directory (by default).

my $value = $m->session->{key};
$m->session->{key} = { some_complex => ['value'] };

• send_json ($data) — outputs the JSON-encoded $data, sets the content type to "application/json", and aborts. e.g.

method handle {
    my $data;
    # compute data somehow
    $m->send_json($data);
}

"send_json" is a shortcut for:

$m->clear_buffer;
$m->print(JSON::XS::encode_json($data));
$m->res->content_type("application/json");
$m->abort();

---

🌟 SEE ALSO 🌟

Poet — go read her too, she's the whole vibe 🫶

---

🎀 AUTHOR 🎀

Jonathan Swartz <swartz@pobox.com> — thank you king 👑

---

💖 COPYRIGHT AND LICENSE 💖

This software is copyright (c) 2012 by Jonathan Swartz.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. Slay, legally speaking ⚖️✨

---

and that's a wrap bestie!! this lil doc moment was brought to you by perl v5.34.0, dated 2022-06-18, and it's the Poet::Mason(3pm) page — go forth and build something iconic 💅🌸🦋