Getting Images Out

Putting your hands on those shiny new bits

Picnik can send freshly edited images back to your website. You turn on this functionality by passing an _export parameter as part of your API call. When Picnik sees this parameter, we'll add a shiny yellow "Export" button to the user interface:

As a quick aside, you can change the text on the export button by using the _export_title parameter.

The value you give for the _export parameter is the URL to which you'd like Picnik to send the data. This is probably going to be the address of a script running on your web server.

To Push or To Pull?

When the user clicks the "Export" button, Picnik is going to create the image and then make it available to you in one of two ways:

1. Picnik can post the actual image data to you as an HTTP POST (ie., "push").
2. Picnik can send you a temporary URL from which you can download the image data (ie., "pull").

Which of these you choose depends on your needs and the capabilities of your website platform. For example, it is usually more convenient to avoid an extra download step and receive the data directly from Picnik's servers, so #1 is often a good choice. On the other hand, all of the _export-related samples in the API reference use method #2 because they are written in Javascript, which is unable to handle HTTP POST'ed image data the way we need it to.

Use the _export_agent and _export_method parameters to choose which of these methods you'd like to use.

Handling a Push

If you've chosen method #1, the "push" method, then Picnik is going to send the image data to your server via an HTTP POST. At a minimum, you would call the Picnik API with the _export parameter set to the URL of a script on your web server. All the other export-related parameters will work fine with their default values.

Then, on your web server, you'll need to write some code to:

1. Receive the data.
2. Process it (eg., save it somewhere).
3. Display a result page.

Here's some sample PHP code which accomplishes all three:

<?php
	// PHP script to receive image data from Picnik via HTTP POST

	// Make sure we've been sent an image.  By default, the
	// image data goes into the "file" field, but we could
	// change that using the _export_field API parameter.
	if (!isset($_FILES['file'])) {
		echo "Sorry, no image data was sent.";
		exit();
	}
	
	// retrieve the image's attributes from the $_FILES array
	$image_tmp_filename = $_FILES['file']['tmp_name'];
	$image_filename = $_FILES['file']['name'];
	
	// Save the image to disk.  It'll go into the same directory as
	// this script.  You'd probably want to put it somewhere else in the
	// file system like a "/images" directory, or maybe even into a database.
	// Make sure your web server has write access to the destination dir,
	// or the call to file_put_contents isn't going to work.
	$image_data = file_get_contents( $image_tmp_filename );
	
	// Note: file_put_contents requires PHP 5. Use fopen/fwrite/fclose for earlier versions.
	file_put_contents( $image_filename, $image_data );		
	
	// Display a result to let the user know what happened.  You
	// might need to be smarter about how the $image_link variable is
	// built, depending on how your web server is set up.
	$image_link = dirname($_SERVER['PHP_SELF']) . "/" . $image_filename;
	echo "Your file was saved to $image_filename.<br/>"; 
	echo "You can find it at this URL: <a href='$image_link'>$image_link</a><br/>";
	echo "<img src='$image_link'>";
?>

When using the "push" method, you'll actually see two hits to your server with every export. This first is the POST to your _export URL from Picnik which contains the image data. The user's browser is then redirected to your _export URL and you'll receive a GET with no image data. If you want to send the user to a different URL after exporting, take a look at the _redirect parameter.

Handling a Pull

The second method is to pull the data down from Picnik yourself. In this case, you'll need to pass one additional parameter to change the way Picnik behaves: set _export_agent to "browser".

Back on your web server, you'll need to write some additional code to download the image data before you can save it. Here's an updated PHP script:

<?php
	// PHP script to download image data from Picnik after we're given
	// a temporary URL via HTTP GET.

	// Make sure we've been sent an image url
	if (!isset($_GET['file'])) {
		echo "Sorry, no image URL was sent.";
		exit();
	}	
	$image_url = $_GET['file'];
	
	// Make sure that the image came from picnik.  We don't want anyone
	// sending us data we didn't ask for!
	if (0 !== stripos( $image_url, "http://www.picnik.com")) {
		echo "Sorry, the image URL doesn't seem right.";
		exit();		
	}
	
	// Download the image data from Picnik's servers
	$image_data = file_get_contents( $image_url );
	if (FALSE === $image_data) {
		// Download failed ... this shouldn't happen very often,
		// but you might want to put some retry logic in your app
		echo "Sorry, the image download failed.";
		exit();		
	}	
	
	// Save the image to disk.  It'll go into the same directory as
	// this script.  You'd probably want to put it somewhere else in the
	// file system like a "/images" directory, or maybe even into a database.
	// Make sure your web server has write access to the destination dir,
	// or the call to file_put_contents isn't going to work.
	$image_filename = "picnik_exported_file" . time() . rand(10000,99999) . ".jpg";
	file_put_contents( $image_filename, $image_data );	
	
	// Display a result to let the user know what happened
	$image_link = dirname($_SERVER['PHP_SELF']) . "/" . $image_filename;
	echo "Your file was saved to $image_filename.<br/>"; 
	echo "You can find it at this URL: <a href='$image_link'>$image_link</a><br/>";
	echo "<img src='$image_link'>";
?>

Next Steps

You've got a handle on image exporting, but there's still a lot more you can do. And of course, you can always go back and take a look at all the tutorials.