/ 
WWW-Imgur-0.03
/ WWW::Imgur

NAME

WWW::Imgur - upload images to imgur.com

SYNOPSIS

my $imgur = WWW::Imgur->new ();
$imgur->key ('YoUrApIkEy');
# Put an image on to the web site
my $json = $imgur->upload ('fabulous.png')
    or die "Upload failed";
# Delete an image
$imgur->delete ('DelETEhasH')
    or die "Delete failed";

WWW::Imgur provides an interface to the image uploading and image deletion APIs of the http://imgur.com/ image sharing website.

This module uses the version 2 API with the JSON option. See http://api.imgur.com/ for details of the Imgur API.

METHODS

new

my $imgur = WWW::Imgur->new ();

my $imgur = WWW::Imgur->new ({key => 'YoUrApIkEy',
                              verbose => 1});

Create a new object. You can supply an argument of a hash reference containing the following keys:

key => 'YoUrApIkEy'

Set the API key. Equivalent to calling the "key" method with an argument.

verbose => 1

Turn on or off non-error messages from the module. Equivalent to calling the "verbosity" method with an argument.

agent => 'Incredible User Agent'.

This option sets the user agent string. It is equivalent to calling the "agent" method with an argument.

key

$imgur->key ('MyApiKEy');

This method sets the value of the API key to whatever you give as an argument. You can get an API key at http://imgur.com/register/api_anon for an anonymous application, or http://imgur.com/register/api_oauth for a registered application. However, WWW::Imgur doesn't handle the OAuth interface. See "No OAuth".

verbosity

# Turn on messages
$imgur->verbosity (1);
# Turn off messages
$imgur->verbosity ();

Give a true value to get messages from the object telling you what it is doing. Give a false or empty value to stop the messages.

upload

$json = $imgur->upload (\$image_data);
$json = $imgur->upload ('fabulous.png');
$json = $imgur->upload ('http://www.example.com/fabulous.png');

Upload an image to imgur.com. If it succeeds, it returns the JSON message from imgur.com as plain text (it does not parse this message into a Perl object). If it fails, it prints an error message on the standard error and returns an undefined value.

The argument can either be

actual image data,

in which case you should pass it as a scalar reference, as in \$image_data in the first line of the example above,

the file name of an image file,

as in 'fabulous.png' in the second line of the example above, or

the URL of an image,

as in 'http://www.example.com/fabulous.png' in the third line of the example above. Imgur's documentation refers to this as "Image Sideloading". See http://api.imgur.com/resources_anon#sideloading.

The URL is passed to imgur.com, so it needs to be one which is accessible to the imgur.com server, not a local or private one.

WWW::Imgur does not parse the JSON for you. See "No parsing of JSON". If you want to view the contents of $json, try, for example

use JSON;
use Data::Dumper;
my $json = $imgur->upload ('nuts.png');
print Dumper (json_decode ($json));

See the example in the file examples/upload.pl of the WWW::Imgur distribution for a full example.

There is an optional second argument to the upload method. You pass a hash reference containing options. Currently there are two options, "caption" and "title".

my $json = $imgur->upload ('sharon-stone.jpeg',
                       {
                           caption => 'Sharon Stone is a stone gas',
                           title => 'Sharon Stone gathers no moss',
                       });

However, although the values you send are sent back in the JSON response you get from the site, these don't seem to actually show up anywhere on the Imgur website itself.

delete

$imgur->delete ('ImageDeleteHASH');

This method deletes an image from imgur.com. It takes one argument, a key called the "deletehash", which is one of the parts of the JSON response from the "upload" method.

If it succeeds, it returns the message from Imgur. If it fails, it prints a message on STDERR and returns an undefined value.

If you try to delete an image which has already been deleted, Imgur seems to respond with a "400 Bad Request" error.

agent

$imgur->agent ('MyScript.pl');

Given an argument, this sets the user agent string of the agent which makes the request. The default value of the user agent string is "WWW::Imgur".

Without an argument, it returns what the user agent string is currently set to.

As far as I know, Imgur does not make any use of what you set the user agent string to. However I think it's wise to set it to something which they can recognize if need be.

DEPENDENCIES

This module uses MIME::Base64 to encode the image data to send to Imgur, JSON to decode the return message in the "delete" method, LWP to communicate with imgur.com, and Carp to report errors.

BUGS

Although the module basically does everything I need it to do (upload small 30,000 byte PNG files to Imgur and delete them), the following features are not implemented.

No OAuth

There is no support for the OAuth interface for registered applications. See http://api.imgur.com/resources_auth.

No tests

The test suite doesn't do anything except test this module for compilation. I'm not willing to apply to Imgur for an API key for testing this module which may then go on to be abused by someone, and I'm also not willing to write tests for the module which rely on being connected to the internet. Please get an API key and then use the example scripts to test the module to make sure it works correctly against the actual Imgur API.

No XML

There is no support for the XML API. It would be quite easy to add this to the module if you need it.

No image stats

The Imgur API contains a method to get information about an image, but this module doesn't have a way to access that. See http://api.imgur.com/resources_anon#image_hash.

No parsing of JSON

The successful return value of the "upload" method is the JSON text which Imgur sends back to you, unparsed. I did it this way so that the application I wrote this for could just send this JSON text to a JavaScript program, which then reloads the image. Thus there was no point in parsing the JSON output. However, it would be easy to add an option to WWW::Imgur to parse the JSON.

If you are using this module and are interested in adding some of the above features, please let me know. I haven't set up a repository or a mailing list for the module. Setting these up would depend on the level of user interest.

SEE ALSO

Image::Imgur is an alternative module for imgur.com. It uses the XML version of the API rather than the JSON one which WWW::Imgur uses, and it depends on the Moose module. It uses an older version of the Imgur API. The version on CPAN at the time of writing (22 March 2011) has a method to upload image files, but does not have one to delete images or to upload image data from memory.

AUTHOR

Ben Bullock, <bkb@cpan.org>

LICENCE

You can copy, modify and redistribute WWW::Imgur under the Perl Artistic Licence or the GNU General Public Licence.