PHP SDK: Infrastructure & Authentication

.gitignore

@@ -1,2 +1,8 @@
 # OS X
 .DS_Store
+
+# Generated documentation
+docs/
+
+# Local settings
+*.local.php

Makefile

@@ -0,0 +1,4 @@
+.PHONY: docs
+
+docs:
+	phpdoc -d Splunk -t docs

README.md

@@ -51,7 +51,7 @@ into the repository with git:
 
 ## Requirements
 
-The SDK requires PHP 5.3+
+The SDK requires PHP 5.2+
 
 ## ...
 

Splunk.php

@@ -0,0 +1,30 @@
+<?php
+/**
+ * Copyright 2012 Splunk, Inc.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License"): you may
+ * not use this file except in compliance with the License. You may obtain
+ * a copy of the License at
+ * 
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * Intercepts failed attempts to load classes of the form 'Splunk_*'
+ * and automatically includes the appropriate PHP file for the class.
+ */
+function Splunk_autoload($className)
+{
+    if (substr_compare($className, 'Splunk_', 0, strlen('Splunk_')) != 0)
+        return false;
+    $file = str_replace('_', '/', $className);
+    return include dirname(__FILE__) . "/$file.php";
+}
+
+spl_autoload_register('Splunk_autoload');

Splunk/Context.php

@@ -0,0 +1,99 @@
+<?php
+/**
+ * Copyright 2012 Splunk, Inc.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License"): you may
+ * not use this file except in compliance with the License. You may obtain
+ * a copy of the License at
+ * 
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * This class allows clients to issue HTTP requests to a Splunk server.
+ * 
+ * @package Splunk
+ */
+class Splunk_Context
+{
+    private $username;
+    private $password;
+    private $host;
+    private $port;
+    private $scheme;
+    private $http;
+
+    private $token;
+
+    /**
+     * @param array $args {
+     *      'username' => (optional) The username to login with. Defaults to "admin".
+     *      'password' => (optional) The password to login with. Defaults to "changeme".
+     *      'host' => (optional) The hostname of the Splunk server. Defaults to "localhost".
+     *      'port' => (optional) The port of the Splunk server. Defaults to 8089.
+     *      'scheme' => (optional) The scheme to use: either "http" or "https". Defaults to "https".
+     *      'http' => (optional) An Http object that will be used for performing HTTP requests.
+     * }
+     */
+    public function __construct($args)
+    {
+        $args = array_merge(array(
+            'username' => 'admin',
+            'password' => 'changeme',
+            'host' => 'localhost',
+            'port' => 8089,
+            'scheme' => 'https',
+            'http' => new Splunk_Http(),
+        ), $args);
+
+        $this->username = $args['username'];
+        $this->password = $args['password'];
+        $this->host = $args['host'];
+        $this->port = $args['port'];
+        $this->scheme = $args['scheme'];
+        $this->http = $args['http'];
+    }
+
+    // === Operations ===
+
+    /**
+     * Authenticates to the Splunk server.
+     */
+    public function login()
+    {
+        $response = $this->http->post($this->url('/services/auth/login'), array(
+            'username' => $this->username,
+            'password' => $this->password,
+        ));
+
+        $sessionKey = Splunk_Util::getTextContentAtXpath(
+            new SimpleXMLElement($response['body']),
+            '/response/sessionKey');
+
+        $this->token = 'Splunk ' . $sessionKey;
+    }
+
+    // === Accessors ===
+
+    /**
+     * Returns the token used to authenticate HTTP requests
+     * after logging in.
+     */
+    public function getToken()
+    {
+        return $this->token;
+    }
+
+    // === Utility ===
+
+    private function url($path)
+    {
+        return "{$this->scheme}://{$this->host}:{$this->port}{$path}";
+    }
+}

Splunk/Http.php

@@ -0,0 +1,154 @@
+<?php
+/**
+ * Copyright 2012 Splunk, Inc.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License"): you may
+ * not use this file except in compliance with the License. You may obtain
+ * a copy of the License at
+ * 
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * HTTP abstraction layer.
+ * 
+ * @package Splunk
+ */
+class Splunk_Http
+{
+    public function get($url)
+    {
+        return $this->request('get', $url);
+    }
+
+    public function post($url, $params=array())
+    {
+        return $this->request('post', $url, http_build_query($params));
+    }
+
+    /**
+     * @param string $method        HTTP request method (ex: 'get').
+     * @param string $url           URL to fetch.
+     * @param string $request_body  content to send in the request.
+     * @return object {
+     *      'status' => HTTP status code (ex: 200).
+     *      'reason' => HTTP reason string (ex: 'OK').
+     *      'headers' => Dictionary of headers. (ex: array('Content-Length' => '0')).
+     *      'body' => Content of the response.
+     * }
+     */
+    private function request($method, $url, $request_body='')
+    {
+        $opts = array(
+            CURLOPT_HTTPGET => TRUE,
+            CURLOPT_URL => $url,
+            CURLOPT_TIMEOUT => 60,  // secs
+            CURLOPT_RETURNTRANSFER => TRUE,
+            CURLOPT_HEADER => TRUE,
+            // disable SSL certificate validation
+            CURLOPT_SSL_VERIFYPEER => FALSE,
+        );
+
+        switch ($method)
+        {
+            case 'get':
+                $opts[CURLOPT_HTTPGET] = TRUE;
+                break;
+            case 'post':
+                $opts[CURLOPT_POST] = TRUE;
+                $opts[CURLOPT_POSTFIELDS] = $request_body;
+                break;
+            default:
+                $opts[CURLOPT_CUSTOMREQUEST] = strtoupper($method);
+                break;
+        }
+
+        if (!($curl = curl_init()))
+            throw new Splunk_ConnectException('Unable to initialize cURL.');
+        if (!(curl_setopt_array($curl, $opts)))
+            throw new Splunk_ConnectException(curl_error($curl));
+        if (!($response = curl_exec($curl)))
+            throw new Splunk_ConnectException(curl_error($curl));
+
+        $status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
+
+        $header_size = curl_getinfo($curl, CURLINFO_HEADER_SIZE);
+        $header_text = substr($response, 0, $header_size);
+        $body = substr($response, $header_size);
+
+        $headers = array();
+        $header_lines = explode("\r\n", trim($header_text));
+        $status_line = array_shift($header_lines);
+        foreach ($header_lines as $line)
+        {
+            list($key, $value) = explode(':', $line, 2);
+            $headers[$key] = trim($value);
+        }
+
+        list($http_version, $_, $reason) = explode(' ', $status_line, 3);
+
+        $response = array(
+            'status' => $status,
+            'reason' => $reason,
+            'headers' => $headers,
+            'body' => $body,
+        );
+
+        if ($status >= 400)
+            throw new Splunk_HttpException($response);
+        else
+            return $response;
+    }
+}
+
+/**
+ * Thrown when unable to connect to a Splunk server.
+ * 
+ * @package Splunk
+ */
+class Splunk_ConnectException extends Exception {}
+
+/**
+ * Thrown when an HTTP request fails due to a non 2xx status code.
+ * 
+ * @package Splunk
+ */
+class Splunk_HttpException extends Exception
+{
+    private $response;
+
+    // === Init ===
+
+    public function __construct($response)
+    {
+        $detail = Splunk_HttpException::parseFirstMessageFrom($response);
+
+        // FIXME: Include HTTP "reason" in message
+        $message = "HTTP {$response['status']} {$response['reason']}";
+        if ($detail != NULL)
+            $message .= ' -- ' . $detail;
+
+        $this->response = $response;
+        parent::__construct($message);
+    }
+
+    private static function parseFirstMessageFrom($response)
+    {
+        return Splunk_Util::getTextContentAtXpath(
+            new SimpleXMLElement($response['body']),
+            '/response/messages/msg');
+    }
+
+    // === Accessors ===
+
+    public function getResponse()
+    {
+        return $this->response;
+    }
+}

Splunk/Util.php

@@ -0,0 +1,48 @@
+<?php
+/**
+ * Copyright 2012 Splunk, Inc.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License"): you may
+ * not use this file except in compliance with the License. You may obtain
+ * a copy of the License at
+ * 
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * Internal utilities used by the Splunk package.
+ * 
+ * @package Splunk
+ */
+class Splunk_Util
+{
+    /**
+     * @param SimpleXMLElement  $xmlElement
+     * @param string            $xpathExpr
+     * @return string|NULL
+     */
+    public static function getTextContentAtXpath($xmlElement, $xpathExpr)
+    {
+        $matchingElements = $xmlElement->xpath($xpathExpr);
+        return (count($matchingElements) == 0)
+            ? NULL
+            : Splunk_Util::getTextContentOfXmlElement($matchingElements[0]);
+    }
+
+    /**
+     * @param SimpleXMLElement $xmlElement
+     * @return string
+     */
+    private static function getTextContentOfXmlElement($xmlElement)
+    {
+        // HACK: Some versions of PHP 5 can't access the [0] element
+        //       of a SimpleXMLElement object properly.
+        return (string) $xmlElement;
+    }
+}