Plack:...coding(3pm)

🌸 Plack::Request::WithEncoding — the manual page, bestie edition 🌸

okay so this is Plack:...coding(3pm), a User Contributed Perl Documentation page. yes the header is doing a little mystery with the truncation, we love that for it. anyway, sit down, hydrate, we're learning 💖

---

✨ NAME ✨

Plack::Request::WithEncoding — a subclass of Plack::Request that supports encoded requests. it's giving "I speak every language, actually" 💅

---

🎀 SYNOPSIS 🎀

use Plack::Request::WithEncoding;

my $app_or_middleware = sub {
    my $env = shift; # PSGI env

    # Example of $env
    #
    # $env = {
    #     QUERY_STRING   => 'query=%82%d9%82%b0', # <= encoded by 'cp932'
    #     REQUEST_METHOD => 'GET',
    #     HTTP_HOST      => 'example.com',
    #     PATH_INFO      => '/foo/bar',
    # };

    my $req = Plack::Request::WithEncoding->new($env);

    $req->env->{'plack.request.withencoding.encoding'} = 'cp932'; # <= specify the encoding method.

    my $query = $req->param('query'); # <= get parameters of 'query' that is decoded by 'cp932'.

    my $res = $req->new_response(200); # new Plack::Response
    $res->finalize;
};

look at that. $env gets built, the encoding gets set, the param comes back decoded. main character pipeline fr fr 🔥

---

🦋 DESCRIPTION 🦋

Plack::Request::WithEncoding is a subclass of Plack::Request that supports encoded requests. it overrides many Plack::Request attributes so they hand you back decoded values instead. the whole point? one single application can seamlessly handle a wide variety of different language code sets. no cap. apps that have to deal with tons of different translations all at once will find this extension able to quickly solve that problem. ate and left no crumbs 👑

the target attributes that get encoded are described down in "SPECIFICATION OF THE ENCODING METHOD". don't skip it, bestie, it's important.

---

💖 ATTRIBUTES of Plack::Request::WithEncoding 💖

• encoding — Returns an encoding method to decode parameters.
• query_parameters — Returns a reference of Hash::MultiValue instance that contains decoded query parameters.
• body_parameters — Returns a reference of Hash::MultiValue instance that contains decoded request body.
• parameters — Returns a reference of Hash::MultiValue instance that contains decoded parameters. The parameters are merged with query_parameters and body_parameters.
• param — Returns decoded parameters with a CGI.pm-compatible param method. This is an alternative method for accessing parameters in $req->parameters. Unlike CGI.pm, it does not allow setting or modifying query parameters.

$value  = $req->param('foo');
@values = $req->param('foo');
@params = $req->param;

• raw_query_parameters — This attribute is the same as query_parameters of Plack::Request.
• raw_body_parameters — This attribute is the same as body_parameters of Plack::Request.
• raw_parameters — This attribute is the same as parameters of Plack::Request.
• raw_param — This attribute is the same as param of Plack::Request.

so the raw_* squad is just the plain Plack::Request behaviour, untouched, unbothered, moisturised, in its lane 🌈

---

⭐ SPECIFICATION OF THE ENCODING METHOD ⭐

You can specify the character-encoding to decode, like so;

$req->env->{'plack.request.withencoding.encoding'} = 'utf-7'; # <= set utf-7

When this character-encoding wasn't given through $req->env->{'plack.request.withencoding.encoding'}, this module uses utf-8 as the default character-encoding to decode. ngl it would be better to specify this character-encoding explicitly, because the readability and understandability of the code behavior would be improved. like, future-you will thank present-you 🫶

Once this value was specified by falsy value (e.g. undef, 0 and ''), this module returns raw value (i.e. never decodes).

The example of a code is shown below.

print exists $req->env->{'plack.request.withencoding.encoding'} ? 'EXISTS'
                                                                : 'NOT EXISTS'; # <= NOT EXISTS
$query = $req->param('query'); # <= get parameters of 'query' that is decoded by 'utf-8' (*** YOU SHOULD NOT USE LIKE THIS ***)

$req->env->{'plack.request.withencoding.encoding'} = undef; # <= explicitly specify the `undef`
$query = $req->param('query'); # <= get parameters of 'query' that is not decoded (raw value)

$req->env->{'plack.request.withencoding.encoding'} = 'cp932'; # <= specify the 'cp932' as encoding method
$query = $req->param('query'); # <= get parameters of 'query' that is decoded by 'cp932'

⚠️ okay pay attention here bestie, the original is yelling at you in caps and honestly? valid. (*** YOU SHOULD NOT USE LIKE THIS ***) — do not rely on the default like that. be explicit. it's the difference between a clean vibe and a debugging spiral at 2am 😭

---

🔥 SEE ALSO 🔥

• Plack::Request

the origin story. the blueprint. go read it 💜

---

🎀 LICENSE 🎀

Copyright (C) moznion.

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

---

👑 AUTHOR 👑

moznion <moznion@gmail.com>

---

and that's the whole page, no notes. this one's perl v5.30.3, dated 2020-08-08, brought to you by User Contributed Perl Documentation — stay decoded, stay iconic, mwah 💅✨🍓