NAME

Plack::Middleware::Image::Scale - Resize jpeg and png images on the fly

VERSION

version 0.011

SYNOPSIS

## example1.psgi
use Plack::Builder;
use Plack::Middleware::Image::Scale;
my $app = sub { return [200,[],[]] };

builder {
    enable 'ConditionalGET';
    enable 'Image::Scale';
    enable 'Static', path => qr{^/images/};
    $app;
};

A request to /images/foo_40x40.png will use images/foo.(png|jpg|gif|jpeg) as original, scale it to 40x40 px size and convert to PNG format.

## example2.psgi
use Plack::Builder;
use Plack::App::File;
use Plack::Middleware::Image::Scale;
my $app = sub { return [200,['Content-Type'=>'text/plain'],['hello']] };

my $thumber = builder {
    enable 'ConditionalGET';
    enable 'Image::Scale',
        width => 200, height => 100,
        flags => { fill => 'ff00ff' };
    Plack::App::File->new( root => 'images' );
};

builder {
    mount '/thumbs' => $thumber;
    mount '/' => $app;
};

A request to /thumbs/foo.png will use images/foo.(png|jpg|gif|jpeg) as original, scale it small enough to fit 200x100 px size, fill extra borders (top/down or left/right, depending on the original image aspect ratio) with cyan background, and convert to PNG format. Also clipping is available, see "CONFIGURATION".

DESCRIPTION

Scale and convert images to the requested format on the fly. By default the size and other scaling parameters are extracted from the request URI. Scaling is done with Image::Scale.

The original image is not modified or even accessed directly by this module. The converted image is not cached, but the request can be validated (If-Modified-Since) against original image without doing the image processing. This middleware should be used together a cache proxy, that caches the converted images for all clients, and implements content validation.

The response headers (like Last-Modified or ETag) are from the original image, but body is replaced with a PSGI content filter to do the image processing. The original image is fetched from next middleware layer or application with a normal PSGI request. You can use Plack::Middleware::Static, or Catalyst::Plugin::Static::Simple for example.

See "CONFIGURATION" for various size/format specifications that can be used in the request URI, and "ATTRIBUTES" for common configuration options that you can use when constructing the middleware.

ATTRIBUTES

path

Must be a RegexpRef, CodeRef, Str or Undef.

The PATH_INFO is compared against this value to evaluate if the request should be processed. Undef (the default) will match always. PATH_INFO is topicalized by settings it to $_, and it may be rewritten during CodeRef matching. Rewriting can be used to relocate image paths, much like path parameter for Plack::Middleware::Static.

If path matches, next it will be compared against "name". If path doesn't match, the request will be delegated to the next middleware layer or application.

match

Must be a RegexpRef, or CodeRef.

The PATH_INFO, possibly rewritten during "path" matching, is compared against this value to extract name, size and ext. The default value is:

qr{^(.+)(?:_(.+?))?(?:\.(jpe?g|png|image))$}

The expression is evaluated in array context and may return three elements: name, size and ext. Returning an empty array means no match. Non-matching requests are delegated to the next middleware layer or application.

If the path matches, the original image is fetched from name."orig_ext", scaled with parameters extracted from size and converted to the content type defined by ext. See also "any_ext".

size

Must be a RegexpRef, CodeRef, HashRef, Undef.

The size extracted by "match" is compared against this value to evaluate if the request should be processed, and to map it into width, height and flags for image processing. Undef will match always and use default width, height and flags as defined by the "ATTRIBUTES". The default value is:

qr{^(\d+)?x(\d+)?(?:-(.+))?$}

The expression is evaluated in array context and may return three elements; width, height and flags. Returning an empty array means no match. Non-matching requests are delegated to the next middleware layer or application.

Optionally a hash reference can be returned. Keys width, height, and any remaining keys as an hash reference, will be unrolled from the hash reference.

any_ext

If defined and request ext is equal to this, the content type of the original image is used in the output. This means that the image format of the original image is preserved. Default is image.

orig_ext

ArrayRef of possible original image formats. See "fetch_orig".

memory_limit

Memory limit for the image scaling in bytes, as defined in Image::Scale.

jpeg_quality

JPEG quality, as defined in Image::Scale.

width

Use this to set and override image width.

height

Use this to set and override image height.

flags

Use this to set and override image processing flags.

METHODS

fetch_orig

Call parameters: PSGI request HashRef $env, Str $basename. Return value: PSGI response ArrayRef $res.

The original image is fetched from the next layer or application. All possible extensions defined in "orig_ext" are tried in order, to search for the original image. All other responses except a straight 404 (as returned by Plack::Middleware::Static for example) are considered matches.

body_scaler

Call parameters: @args. Return value: PSGI content filter CodeRef $cb.

Create the content filter callback and return a CodeRef to it. The filter will buffer the data and call "image_scale" with parameters @args when EOF is received, and finally return the converted data.

image_scale

Call parameters: ScalarRef $buffer, String $ct, Int $width, Int $height, HashRef|Str $flags. Return value: $imagedata

Read image from $buffer, scale it to $width x $height and return as content-type $ct. Optional $flags to specify image processing options like background fills or cropping.

CONFIGURATION

The default match pattern for URI is "..._widthxheight-flags.ext".

If URI doesn't match, the request is passed through. Any number of flags can be specified, separated with -. Flags can be boolean (exists or doesn't exist), or have a numerical value. Flag name and value are separated with a zero-width word to number boundary. For example z20 specifies flag z with value 20.

width

Width of the output image. If not defined, it can be anything (to preserve the image aspect ratio).

height

Height of the output image. If not defined, it can be anything (to preserve the image aspect ratio).

flags: fill

Image aspect ratio is preserved by scaling the image to fit within the specified size. This means scaling to the smaller or the two possible sizes that preserve aspect ratio. Extra borders of background color are added to fill the requested image size exactly.

/images/foo_400x200-fill.png

If fill has a value, it specifies the background color to use. Undefined color with png output means transparent background.

flags: crop

Image aspect ratio is preserved by scaling and cropping from middle of the image. This means scaling to the bigger of the two possible sizes that preserve the aspect ratio, and then cropping to the exact size.

flags: fit

Image aspect ratio is preserved by scaling the image to the smaller of the two possible sizes. This means that the resulting picture may have one dimension smaller than specified, but cropping or filling is avoided.

See documentation in distribution directory doc for a visual explanation.

flags: z

Zoom the original image N percent bigger. For example z20 to zoom 20%. Zooming applies only to explicitly defined width and/or height, and it does not change the crop size.

/images/foo_40x-z20.png

EXAMPLES

## see example4.psgi

my %imagesize = Config::General->new('imagesize.conf')->getall;

# ...

enable 'Image::Scale', size => \%imagesize;

A request to /images/foo_medium.png will use images/foo.(png|jpg|gif|jpeg) as original. The size and flags are taken from the configuration file as parsed by Config::General.

## imagesize.conf

<medium>
    width   200
    height  100
    crop
</medium>
<big>
    width   300
    height  100
    crop
</big>
<thumbred>
    width   50
    height  100
    fill    ff0000
</thumbred>

For more examples, browse into directory eg inside the distribution directory for this version.

CAVEATS

The cropping requires Imager. This is a run-time dependency, and fallback is not to crop the image to the expected size.

AUTHOR

Panu Ervamaa <pnu@cpan.org>

COPYRIGHT AND LICENSE

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

To install Plack::Middleware::Image::Scale, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Plack::Middleware::Image::Scale

CPAN shell

perl -MCPAN -e shell
install Plack::Middleware::Image::Scale

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

ATTRIBUTES

path

match

size

any_ext

orig_ext

memory_limit

jpeg_quality

width

height

flags

METHODS

fetch_orig

body_scaler

image_scale

CONFIGURATION

width

height

flags: fill

flags: crop

flags: fit

flags: z

EXAMPLES

CAVEATS

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions