Facebook Cookbook - Jay Goldman [141]
If you were previously running this code as individual calls:
$friends = $facebook->api_client->friends_get();
$notifications = $facebook->api_client->notifications_get();
you could do the same thing as a batch by doing this:
$facebook->api_client->begin_batch();
$friends = &$facebook->api_client->friends_get();
$notifications = &$facebook->api_client->notifications_get();
$facebook->api_client->end_batch();
You won’t see any significant performance gains on two calls, but you should if you push the Batch API to its limit and run 20 calls in a batch. See the Discussion for more information about what’s really happening.
Discussion
The Batch API is currently in beta, so remember that you probably shouldn’t build production code on it without being very careful, and you should report any bugs you might find into the Facebook Bug Tracker at http://bugs.developers.facebook.com.
Batching is considerably more efficient because it saves you roundtrips to the server on each call, and it lets Facebook process up to 20 calls in parallel at the same time. If you made each of those calls individually, you’d have to do them in series and would have 40 calls and responses instead of two. If you need to run the calls in your batch in the order you’ve listed them (rather than in parallel, which is the default), you can override the batch_mode variable in the Facebook Client Library:
// Default is 0, which is parallel
// (unless you've modified facebookapi_php5_restlib.php)
$facebook->api_client->batch_mode = FacebookRestClient::BATCH_MODE_DEFAULT;
// Explicitly setting the mode to parallel (0)
$facebook->api_client->batch_mode = FacebookRestClient::BATCH_MODE_SERVER_PARALLEL;
// Overriding the mode to serial (2)
// (don't forget to set it back!)
$facebook->api_client->batch_mode = FacebookRestClient::BATCH_MODE_SERIAL_ONLY;
Although this may change in the future, your batch will currently exit if there’s an error in one of the calls, but any calls that you’ve made up to that point will still be committed. (In other words, this isn’t a batched transaction in which the changes are committed only at the end; if you make any calls that modify Facebook-side data, they will still modify the data, even if the whole batch isn’t successful.) If you’re running in serial mode, try to optimize your code so that the calls most likely to result in errors happen at the end of the batch (e.g., something such as publishing to a News Feed will return an error if you’ve exceeded your allocations for the day).
Return by reference
Notice the ampersands (&) in front of the two calls inside the batch in the example in the Solution. This tells PHP that you want the return value from them as a reference rather than as a copy of the value. Without the ampersand there, PHP would normally return a copy of an array from a Friends.get() call, rather than a reference to the actual data stored in memory. This might seem a little abstruse if you don’t have a programming background, but stick with me because it’s important.
Let’s say that I’m your accountant and you really need to know how much money you spent on Big Gulp Slushies from 7-Eleven so far this year. If you pick up the phone and call me and I tell you that you spent $10,314 on crushed ice and syrup, you now have the value (and probably a serious bill from the dentist), and you can use it to do whatever you needed to do with it. The problem is that you spend about $28 a day on Big Gulp Slushies, and so that one-time value I passed you is true only at the moment I give it to you and immediately becomes untrue the next time you go into a 7-Eleven (which is probably where you phoned from, so that’s a pretty short window of truth).
Now let’s further suppose that I’m your accountant 50 years into the future and that we’re actually connected by a telepathic data link (and, of course, that you aren’t dead from Slushie overconsumption).