/ 
Plack-App-ImageMagick-1.110990
River stage zero No dependents
/ Plack::App::ImageMagick

NAME

Plack::App::ImageMagick - Create and manipulate images with Image::Magick

VERSION

version 1.110990

SYNOPSIS

# app.psgi
use Plack::App::ImageMagick;

my $thumbnailer_app = Plack::App::ImageMagick->new(
    root => '/path/to/images',
    apply => [
        Scale => { geometry => "%{width:-200}x%{height:-120}" },
        Set => { quality => 30 },
    ],
    with_query => 1,
);

my $captcha_app = Plack::App::ImageMagick-new(
    apply => [
        Set => { size => "100x20" },
        ReadImage => [
            'xc:%{bgcolor:-white}',
        ],
        Set => { magick => "png" },
    ],
    post_process => sub {
        my ($app, $env, $img) = @_;

        $img->Annotate(
            text => random_text( $env->{PATH_INFO} ),
            fill => 'black',
            pointsize => 16,
            gravity => 'Center',
        );
        return $img;
    }
);

# and map it later
use Plack::Builder;
builder {
    # /thumbs/photo_1.jpg?width=640&height=480
    mount "/thumbs/" => $thumbnailer_app;

    # /captcha/623b1c9b03d4033635a545b54ffc4775.png
    mount "/captcha/" => $captcha_app;
}

DESCRIPTION

Use Image::Magick to create and manipulate images for your web applications.

CONFIGURATION

You need to supply "apply" or "handler" configuration options. All other parameters are optional.

apply

my $app = Plack::App::ImageMagick->new(
    root => '/path/to/images',
    apply => [
        Scale => { geometry => "%{width:-200}x%{height:-120}" },
        Set => { quality => 30 },
    ],
    with_query => 1,
);

Array reference of ImageMagick's method_name and its arguments pairs.

The arguments element could be a hash or array reference - both will be flatten when passed as method_name parameters.

If used with "root" then attempt will be made to read image located there, check "root" for details.

If "with_query" is specified the apply block will be pre-processed to replace placeholders with values from query string, check "with_query" for more details.

Results of the following methods will be pushed to @$img:

  • Clone

  • EvaluateImages

  • Fx

  • Smush

  • Transform

Results of the following method will replace current $img object:

  • FlattenImage

Note: if the @$img object contains more then one layer FlattenImage() is called before rendering.

Note: "handler" and "apply" are mutually exclusive.

root

my $app = Plack::App::ImageMagick->new(
    root => '/path/to/images',
    apply => [ ... ],
);

Path to images used in conjunction with "apply" to allow modifications of existing images.

Attempt will be made to read image located there, based on $env->{PATH_INFO}, failure to read image will result in 500 Internal Server Error response.

In essence it is equal to calling Read() before "apply" methods:

$img->Read( $self->root . $env->{PATH_INFO} );

with_query

my $app = Plack::App::ImageMagick->new(
    apply => [
        '%{method:-Scale}' => { geometry => "%{width:-200}x%{height:-120}" },
        Set => { quality => '%{quality:-30}' },
    ],
    with_query => 1,
);

Used with "apply" allows to use placeholders which will be replaced with values found in query string.

For details about syntax please see String::Bash.

User supplied value (from query string) is validated with \A[\w ]+\z, if validation fails 403 Forbidden will be thrown.

Please note that providing default values is recommended.

cache_dir

my $app = Plack::App::ImageMagick->new(
    cache_dir => '/path/to/cache',
    apply => [ ... ],
);

If provided images created will be saved in this directory, with filenames based on $env->{REQUEST_URI} MD5 checksum.

However use of reverse proxy for even better performance gain is recommended.

handler

my $app = Plack::App::ImageMagick->new(
    handler => sub {
        my ($app, $env, $img) = @_;

        # process $img
        ...

        return $img;
    },
);

Sub reference called with following parameters:

$app

Reference to current Plack::App::ImageMagick object.

$env

Reference to current $env.

$img

Reference to Image::Magick object created with:

my $img = Image::Magick->new();

Note: if returned @$img object contains more then one layer FlattenImage() is called before rendering.

Note: "handler" and "apply" are mutually exclusive.

pre_process

my $app = Plack::App::ImageMagick->new(
    pre_process => sub {
        my ($app, $env, $img) = @_;

        # process $img
        ...

        return $img;
    },
    apply => [ ... ],
);

Sub reference called before "apply" methods are processed, with same parameters as "handler".

Returns $img which is processed later by methods defined in "apply".

post_process

my $app = Plack::App::ImageMagick->new(
    apply => [ ... ],
    post_process => sub {
        my ($app, $env, $img) = @_;

        # process $img
        ...

        return $img;
    },
);

Sub reference called after "apply" (with $img processed by its methods), with same parameters as "handler".

Note: if the @$img object contains more then one layer FlattenImage() is called before rendering.

SEE ALSO

AUTHOR

Alex J. G. Burzyński <ajgb@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Alex J. G. Burzyński <ajgb@cpan.org>.

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