---
name: "Plack::Util"
section: "3pm"
platform: "linux"
package: "libplack-perl"
version: "1.0051-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Plack::Util"
---

# Plack::Util(3pm)

Utility subroutines for Plack server and framework developers

## NAME

Plack::Util - Utility subroutines for Plack server and framework developers

## FUNCTIONS

- TRUE, FALSE

  ```
    my $true  = Plack::Util::TRUE;
    my $false = Plack::Util::FALSE;
  ```

  Utility constants to include when you specify boolean variables in `$env` hash (e.g. `"psgi.multithread"`).

- load\_class

  ```
    my $class = Plack::Util::load_class($class [, $prefix ]);
  ```

  Constructs a class name and `"require"` the class. Throws an exception if the .pm file for the class is not found, just with the built-in `"require"`.

  If `$prefix` is set, the class name is prepended to the `$class` unless `$class` begins with `"+"` sign, which means the class name is already fully qualified.

  ```
    my $class = Plack::Util::load_class("Foo");                   # Foo
    my $class = Plack::Util::load_class("Baz", "Foo::Bar");       # Foo::Bar::Baz
    my $class = Plack::Util::load_class("+XYZ::ZZZ", "Foo::Bar"); # XYZ::ZZZ
  ```

  Note that this function doesn't validate (or "sanitize") the passed string, hence if you pass a user input to this function (which is an insecure thing to do in the first place) it might lead to unexpected behavior of loading files outside your `@INC` path. If you want a generic module loading function, you should check out CPAN modules such as Module::Runtime.

- is\_real\_fh

  ```
    if ( Plack::Util::is_real_fh($fh) ) { }
  ```

  returns true if a given `$fh` is a real file handle that has a file descriptor. It returns false if `$fh` is PerlIO handle that is not really related to the underlying file etc.

- content\_length

  ```
    my $cl = Plack::Util::content_length($body);
  ```

  Returns the length of content from body if it can be calculated. If `$body` is an array ref it's a sum of length of each chunk, if `$body` is a real filehandle it's a remaining size of the filehandle, otherwise returns undef.

- set\_io\_path

  ```
    Plack::Util::set_io_path($fh, "/path/to/foobar.txt");
  ```

  Sets the (absolute) file path to `$fh` filehandle object, so you can call `"$fh->path"` on it. As a side effect `$fh` is blessed to an internal package but it can still be treated as a normal file handle.

  This module doesn't normalize or absolutize the given path, and is intended to be used from Server or Middleware implementations. See also IO::File::WithPath.

- foreach

  ```
    Plack::Util::foreach($body, $cb);
  ```

  Iterate through *$body* which is an array reference or IO::Handle-like object and pass each line (which is NOT really guaranteed to be a *line*) to the callback function.

  It internally sets the buffer length `$/` to 65536 in case it reads the binary file, unless otherwise set in the caller's code.

- load\_psgi

  ```
    my $app = Plack::Util::load_psgi $psgi_file_or_class;
  ```

  Load `"app.psgi"` file or a class name (like `"MyApp::PSGI"`) and require the file to get PSGI application handler. If the file can't be loaded (e.g. file doesn't exist or has a perl syntax error), it will throw an exception.

  Since version 1.0006, this function would not load PSGI files from include paths (`@INC`) unless it looks like a class name that only consists of `"[A-Za-z0-9_:]"`. For example:

  ```
    Plack::Util::load_psgi("app.psgi");          # ./app.psgi
    Plack::Util::load_psgi("/path/to/app.psgi"); # /path/to/app.psgi
    Plack::Util::load_psgi("MyApp::PSGI");       # MyApp/PSGI.pm from @INC
  ```

  **Security**: If you give this function a class name or module name that is loadable from your system, it will load the module. This could lead to a security hole:

  ```
    my $psgi = ...; # user-input: consider "Moose"
    $app = Plack::Util::load_psgi($psgi); # this would lead to 'require "Moose.pm"'!
  ```

  Generally speaking, passing an external input to this function is considered very insecure. If you really want to do that, validate that a given file name contains dots (like `"foo.psgi"`) and also turn it into a full path in your caller's code.

- run\_app

  ```
    my $res = Plack::Util::run_app $app, $env;
  ```

  Runs the *$app* by wrapping errors with *eval* and if an error is found, logs it to `"$env->{'psgi.errors'}"` and returns the template 500 Error response.

- header\_get, header\_exists, header\_set, header\_push, header\_remove

  ```
    my $hdrs = [ 'Content-Type' => 'text/plain' ];
    my $v = Plack::Util::header_get($hdrs, $key); # First found only
    my @v = Plack::Util::header_get($hdrs, $key);
    my $bool = Plack::Util::header_exists($hdrs, $key);
    Plack::Util::header_set($hdrs, $key, $val);   # overwrites existent header
    Plack::Util::header_push($hdrs, $key, $val);
    Plack::Util::header_remove($hdrs, $key);
  ```

  Utility functions to manipulate PSGI response headers array reference. The methods that read existent header value handles header name as case insensitive.

  ```
    my $hdrs = [ 'Content-Type' => 'text/plain' ];
    my $v = Plack::Util::header_get($hdrs, 'content-type'); # 'text/plain'
  ```

- headers

  ```
    my $headers = [ 'Content-Type' => 'text/plain' ];
    my $h = Plack::Util::headers($headers);
    $h->get($key);
    if ($h->exists($key)) { ... }
    $h->set($key => $val);
    $h->push($key => $val);
    $h->remove($key);
    $h->headers; # same reference as $headers
  ```

  Given a header array reference, returns a convenient object that has an instance methods to access `"header_*"` functions with an OO interface. The object holds a reference to the original given `$headers` argument and updates the reference accordingly when called write methods like `"set"`, `"push"` or `"remove"`. It also has `"headers"` method that would return the same reference.

- status\_with\_no\_entity\_body

  ```
    if (status_with_no_entity_body($res->[0])) { }
  ```

  Returns true if the given status code doesn't have any Entity body in HTTP response, i.e. it's 100, 101, 204 or 304.

- inline\_object

  ```
    my $o = Plack::Util::inline_object(
        write => sub { $h->push_write(@_) },
        close => sub { $h->push_shutdown },
    );
    $o->write(@stuff);
    $o->close;
  ```

  Creates an instant object that can react to methods passed in the constructor. Handy to create when you need to create an IO stream object for input or errors.

- encode\_html

  ```
    my $encoded_string = Plack::Util::encode_html( $string );
  ```

  Entity encodes `"<"`, `">"`, `"&"`, `"""` and `"'"` in the input string and returns it.

- response\_cb

  See "RESPONSE CALLBACK" in Plack::Middleware for details.