Wednesday, April 20, 2011

CURLOPT_HEADERFUNCTION Tutorial with Example

Cutting to the Chase


So I've noticed there isn't much for documentation on the use of CURLOPT_HEADERFUNCTION so I've decided to try explaining it. So lets start with an example.


CURLOPT_HEADERFUNCTION Example


<?php
class cURL {
    public $response;
    public $header;
    function cURL($url){
        $ch = curl_init($url);
        curl_setopt_array($ch, array(
            CURLOPT_RETURNTRANSFER => true, //Causes curl_exec() to return the response
            CURLOPT_HEADER         => false, //Suppress headers from returning in curl_exec()
            CURLOPT_HEADERFUNCTION => array($this, 'header_callback'),
        ));
        $this->response = curl_exec($ch);
        curl_close($ch);
        return $this->response;
    }

    function header_callback($ch, $header_line){
        $this->header .= $header_line;
        return strlen($header_line);
    }
}
?>

This is a really simple example of the use of curl. Really a solid class would have a whole lot more going on, but that isn't what this example is for...

CURLOPT_HEADERFUNCTION expects the name of the function to callback when it receives the headers from the request. There are two common ways you'll see this:


  • CURLOPT_HEADERFUNCTION => 'header_callback',

  • CURLOPT_HEADERFUNCTION => array($this, 'header_callback'),

If you are familiar with call_user_func_array() you're a step ahead and can skip to the next section.
For a normal function, simply the name of the function will suffice, but to call a method you'll need to pass an array with the object and the method to call on it.
In my example, I'm calling $this->header_callback() by using array($this, 'header_callback').


The Callback Function/Method

 

You'll need to define the function or method you'll want to use as the callback.
There isn't a whole lot of variation between working example's I've found, that is probably because there isn't a whole lot you can do.

Parameter 1: The curl object created by curl_init. This is handy for some rare scenarios, but for the most part useless.

Parameter 2: A single line from the header. This is where some people get lost, its the GOTCHA and I'll explain it below.

Returns: The function/method MUST return the number of bytes written. Why? I'm really not sure, but it must be done or it throws errors at you till you die.


The GOTCHA!


Something not clearly stated anywhere is that the header doesn't come all in one chunk, in my experience the callback is executed for each line of the header.
This makes using CURLOPT_HEADERFUNCTION outside of an object cumbersome because you'll likely end up using a global variable (which is just ugly and some old guys will call you the devil).
For OOP'ers, you'll have no problem just appending the lines to a property like in my example where I use $this->header.


Comment, Tweet, Like, Share, or whatever is hip with the kids these days


If you found this useful and better than other tutorials for CURLOPT_HEADERFUNCTION, please show me some love on the great interwebs.

7 comments:

  1. never seen it quite explained so simply... thanks for taking the time... was looking at this, this aft. when i was tweaking my twitter call api. thanks again.

    ReplyDelete
  2. Glad you found it helpful William. I appreciate all positive and negative feedback.

    ReplyDelete
  3. the docs for this are so lame.. this tutorial is perfect!

    ReplyDelete
  4. Great stuff, real time saver. Thank you!

    ReplyDelete