Initial commit, API beginnings and simple README.

DuckDuckGo/API.php

@@ -0,0 +1,166 @@
+<?php
+
+/**
+ * @file DuckDuckGo/API.php
+ * This file provides the base class to interface with the DuckDuckGo API. 
+ * It will also include any necessary classes.
+ * With this interface, you can currently only perform ZeroClickInfo queries.
+ */
+
+namespace DuckDuckGo;
+
+/* Include the necessary classes. */
+require_once(dirname(__FILE__) . DIRECTORY_SEPARATOR . 'APIResult.php');
+require_once(dirname(__FILE__) . DIRECTORY_SEPARATOR . 'ZeroClickInfo.php');
+
+class API
+{
+
+    /* General API options and flags. */
+
+    /**
+     * The API base URL. This defaults to api.duckduckgo.com.
+     */
+    public $baseURL;
+    /**
+     * Whether to use HTTPS or not. This defaults to FALSE (no HTTPS).
+     */
+    public $secure;
+    /**
+     * Whether to disallow HTML in the result. This defaults to FALSE (don't disallow HTML).
+     */
+    public $noHTML;
+
+    /**
+     * Query-specific flags
+     */
+
+    /**
+     * Whether or not to return Disambiguation (D) results (ZeroClickInfo).
+     * Defaults to FALSE (allow disambiguation results).
+     */
+    public $noDisambiguations;
+
+
+    /* Constructors and internal functions. */
+
+    /**
+     * Constructor.
+     */
+    public function __construct()
+    {
+        $this->secure = FALSE;
+        $this->noHTML = FALSE;
+        $this->noDisambiguations = FALSE;
+        $this->baseURL = 'api.duckduckgo.com';
+    }
+
+    /**
+     * Construct an API URL, given a section and an associative options array.
+     * @param section   Which part of the API to call.
+     * @param options   An associative array containing options to pass in key => value form.
+     * @return          The API URL that corresponds with this query, which then can be retrieved in order to get the query results.
+     */
+    protected function constructURL($section, $options)
+    {
+        $url = '';
+        if($this->secure) {
+            $url .= 'https://' . $this->baseURL;
+        } else {
+            $url .= 'http://' . $this->baseURL;
+        }
+        $url .= $section;
+
+        if(count($options) > 0) {
+            $url .= '?' . \urlencode(\current(\array_keys($options))) . '=' . \urlencode(\array_shift($options));
+
+            foreach($options as $name => $value) {
+                $url .= '&' . \urlencode($name) . '=' . \urlencode($value);
+            }
+        }
+
+        return $url;
+    }
+
+    /**
+     * Given an API section and query options, queries the API and returns the raw results.
+     * @param section   Which part of the API to call.
+     * @param options   An associative array containing options to pass in key => value form.
+     * @return          The raw results of the API call.
+     */
+    protected function getAPIResult($section, $options)
+    {
+        $url = $this->constructURL($section, $options);
+
+        if(\function_exists('curl_init')) {
+            $curl = \curl_init($url);
+            \curl_setopt($curl, CURLOPT_HEADER, FALSE);
+            \curl_setopt($curl, CURLOPT_FOLLOWLOCATION, FALSE);
+            \curl_setopt($curl, CURLOPT_FRESH_CONNECT, TRUE);
+            \curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
+
+            $result = \curl_exec($ch);
+            \curl_close($curl);
+
+            return $result;
+        }
+
+        if(\function_exists('http_get') && \function_exists('http_parse_message')) {
+            $options = array(
+                'redirect' => 0,
+            );
+
+            return \http_parse_message(\http_get($url), $options)->body;
+        }
+
+        if(\ini_get('allow_url_fopen')) {
+            $context = \stream_context_create(array(
+                'http' => array(
+                    'follow_location' => 0,
+                )
+            ));
+
+            $handle = \fopen($url, 'r', FALSE, $context);
+            $result = \stream_get_contents($handle);
+            \fclose($handle);
+
+            return $result;
+        }
+
+        throw new Exception('Could not find suitable method to retrieve API result. Either install the cURL or pear_http extension, or set allow_url_fopen to 1.');
+    }
+
+
+    /* API functions. */
+
+    /**
+     * Perform a ZeroClickInfo query against the DuckDuckGo API.
+     * @param query     The term to query for.
+     * @return          A ZeroClickInfo object containing the results of the query.
+     * @see ZeroClickInfo
+     */
+    public function zeroClickQuery($query)
+    {
+        $result = $this->getAPIResult('/', array(
+            'q' => $query,
+            'format' => 'json',
+            'no_html' => ($this->noHTML ? 1 : 0),
+            'no_redirect' => 1,
+            'skip_disambig' => ($this->noDisambiguations ? 1 : 0),
+        ));
+
+        if(!$result) {
+            throw new Exception('Could not retrieve API result.');
+        }
+
+        return new ZeroClickInfo(\json_decode($result, TRUE));
+    }
+
+}
+
+/**
+ * @example API.php
+ * $api = new DuckDuckGo\API();
+ * $info = $api->zeroClickQuery('Internet Relay Chat');
+ * echo $info->definition;
+ */

DuckDuckGo/APIResult.php

@@ -0,0 +1,23 @@
+<?php
+
+/**
+ * @file DuckDuckGo/APIResult.php
+ * This file provides the base class for API results.
+ * All API result classes must extend from this class.
+ */
+
+namespace DuckDuckGo;
+
+/**
+ * Abstract class where API result classes are based on.
+ */
+abstract class APIResult
+{
+
+    /**
+     * Direct API field --> member mappings.
+     * These mappings allow to directly map API keys to members of the result class.
+     */
+    protected static $directMappings = array();
+
+}