PhpFreebase Example

PhpFreebase is very simple to use. You will need to learn a few things about Freebase itself. You need to understand how Freebase organizes it's information so you understand how to write simple MQL queries. You can find links to the Freebase documentation on the project home page.

Getting started with PhpFreebase is simple. The library simply needs to be included in your code. If you use a framework such as CodeIgniter or Cake, it is simple to load the library into your code with a call to your library load method. i.e. $this->load->library('phpfreebase') in CodeIgniter.

Once the library is loaded you simply need to decide if your query will be to the production data or to the sandbox for testing. If your query is against the sandbox you will need to make a call to setSandbox() passing "true" as the parameter. To changed back to the production data you call setSandbox() passing "false" as the parameter. Note that if you do not need to query the sandbox, you do not need to make this call. The library will use the production data by default.

Now that you know what system you are querying against, you can move on to bulding the query. The Freebase API makes use of JSON objects to pass the query parameters. To ease the way for Php developers the PhpFreebase library works with Php arrays and converts the query to JSON before sending it on to the Freebase system. It then converts the response back to what ever type of Php object you wish, array, associative array, object, boolean, or json. This makes handling the result set easier in Php.

So let's define a simple query. We will query the Freebase system and ask for a list of automotive makes.

        // Buld query
        $q = array('cursor' => true,
                    'pagesize' => 1000,
                    'estimate-count' => null,
                    'uniqueness_failure' => 'hard',
                    'query' => array(0 => array('type' => '/automotive/make',
                    'limit' => 1000,
                    'sort' => 'name',
                    'name' => null,
                    'guid' => null,
                    'timestamp' => null)));

An easy way to create queries is to use the online tools at Freebase.Com which builds queries as json strings. Then pass that string to the decode() method to see how it gets converted into a Php array. If you do this a few times pretty soon you will have a good grasp on how to build your queries. Once you have a query you need to add it to the internal query list. You do this by calling $this->freebase->addQuery($q). You can add many queries but I would try to limit the number of queries to something reasonable like 10 or 20 depending on the size of the result sets.

When you have all your queries added to the query list you simply need to execute the query by calling $this->freebase->get(). This method will return the result set in an associative array by default. That can be changed by passing the mode parameter.

Now that you have executed your query and gotten the result set. You can iterate over the result set or dump it to the screen to peek inside.

You might have noticed the query we passed had a "cursor" parameter. When this parameter is set to true, the result set includes a cusor id that can be used to return further values from the same query in a paging mannor. A call to $this->freebase->getCursor() will return the cursor id for use in the next query.

Likewise, we asked for our results to be page to limit the load on the server and the connection time. We requested that freebase return 1000 records for us. You can read more about cursors and paging results on the Freebase developer's site.

So a complete query sequence from start to finnish might look like this;

        // Include the library
       // Buld query
        $q = array('cursor' => true,
                    'pagesize' => 1000,
                    'estimate-count' => null,
                    'uniqueness_failure' => 'hard',
                    'query' => array(0 => array('type' => '/automotive/make',
                    'limit' => 1000,
                    'sort' => 'name',
                    'name' => null,
                    'guid' => null,
                    'timestamp' => null)));
        // Execute the query
        // get results and status information
        $results = $this->freebase->get('array');
        $cursor = $this->freebase->getCursor();
        $status = $this->freebase->getStatus();
        $query_str = $this->freebase->query_str;
        $query_array = $this->freebase->queries;
        $result_str = $this->freebase->result_str;
        // Print it all out
            // Display results
            echo "Result";
            echo $result;
            echo "Cursor";
            echo $cursor;
            echo "Status";
            echo $status;
            echo "Query String";
            echo $query_str;
            echo "Query Array";
            echo "Result String";
            echo $result_str;
            // Display Error info
            echo "Error Occurred";
            echo "Status: $status";
            echo $this->freebase->getMessage();

Other useful methods and properties that can be used to retreive data from the query results are:


returns the query status


This publically accessible property holds the actual query string sent to the Freebase system.


This publically accessible property stores the list of queries.


This publically accessible property stores the json result string returned by Freebase.

News & Updates

Get The Source Code

Source code for this project may be available as downloads or through one of the SCM repositories used by the project, as accessible from the project develop page. More>>


Join This Project To join this project, please contact the project administrators of this project, as shown on the project summary page. More>>

Project Details

About this project:

This project was registered on SourceForge.net on:

Jan 28, 2010

The phpfreebase project is described by the project team as follows:

"A Php class library to query and write data to the Freebase Open Database System."

Web Designer

If you are a web page designer interested in this project, please consider reaching out to the project admin (per the "Join this project" section, above) to offer your assistance.