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

NAME

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

VERSION

version 1.110900

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.

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, see "root" for details.

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

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

  • Clone

  • EvaluateImages

  • Fx

  • Smush

  • Transform

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

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

  • FlattenImage

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:

$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}' },
    ],
    with_query => 1,
);

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

Syntax:

{param_name[:default_value]}

Default values are permitted (but not required), and will be used if parameter was not found in query string.

The param_name is matched with \w+.

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

The default_value can contain any characters until closing }.

If parameter is not supplied and there is no default value application will throw 500 Internal Server Error response.

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();

If needed $img returned will be flatten with FlattenImage 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".

If needed returned <$img> will be flatten with FlattenImage 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.