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

• Image::Magick

• Plack

• String::Bash

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.

cpanm Plack::App::ImageMagick

perl -MCPAN -e shell
install Plack::App::ImageMagick