view release on metacpan or  search on metacpan

lib/Plack/Middleware/Image/Scale.pm  view on Meta::CPAN

    ## 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
L</CONFIGURATION>.

=head1 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 L<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 L<content
filter|Plack::Middleware/RESPONSE_CALLBACK> to do the image processing.  The
original image is fetched from next middleware layer or application with a
normal PSGI request. You can use L<Plack::Middleware::Static>, or
L<Catalyst::Plugin::Static::Simple> for example.

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

=head1 ATTRIBUTES

=head2 path

Must be a L<RegexpRef|Moose::Util::TypeConstraints/Default_Type_Constraints>,
L<CodeRef|Moose::Util::TypeConstraints/Default_Type_Constraints>,
L<Str|Moose::Util::TypeConstraints/Default_Type_Constraints> or
L<Undef|Moose::Util::TypeConstraints/Default_Type_Constraints>.

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

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

=head2 match

Must be a L<RegexpRef|Moose::Util::TypeConstraints/Default_Type_Constraints>,
or L<CodeRef|Moose::Util::TypeConstraints/Default_Type_Constraints>.

The L<PATH_INFO|PSGI/The_Environment>, possibly rewritten during L</path>
matching, is compared against this value to extract C<name>, C<size>
and C<ext>. The default value is:

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

The expression is evaluated in array context and may return three elements:
C<name>, C<size> and C<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 C<name>.L</orig_ext>,
scaled with parameters extracted from C<size> and converted to the content type
defined by C<ext>. See also L</any_ext>.

=head2 size

Must be a L<RegexpRef|Moose::Util::TypeConstraints/Default_Type_Constraints>,
L<CodeRef|Moose::Util::TypeConstraints/Default_Type_Constraints>,
L<HashRef|Moose::Util::TypeConstraints/Default_Type_Constraints>,
L<Undef|Moose::Util::TypeConstraints/Default_Type_Constraints>.

The C<size> extracted by L</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 L</ATTRIBUTES>. The default value is:

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

The expression is evaluated in array context and may return three elements;
C<width>, C<height> and C<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 C<width>, C<height>, and any
remaining keys as an hash reference, will be unrolled from the hash reference.

=head2 any_ext

If defined and request C<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 C<image>.

=head2 orig_ext

L<ArrayRef|Moose::Util::TypeConstraints/Default_Type_Constraints>
of possible original image formats. See L</fetch_orig>.

=head2 memory_limit