Initial commit with release v1.0

.gitignore

@@ -0,0 +1,8 @@
+composer.lock
+.buildpath
+.settings
+.project
+build
+vendor
+output.log
+test/Jenkins/Test.php

.travis.yml

@@ -0,0 +1,10 @@
+language: php
+php:
+  - 5.5
+  - 5.4
+  - 5.3
+
+before_script:
+  - composer install
+
+script: ./vendor/bin/phpunit

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Shaun Carlson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,125 @@
+Jenkins Web API
+===============
+[![Build Status](https://travis-ci.org/mogman1/jenkins-web-api.svg?branch=master)](https://travis-ci.org/mogman1/jenkins-web-api)
+
+I only noticed, somewhat sheepishly, that there were two other Jenkins PHP libraries 
+already out there by the time I finished my work on this.  Admittedly, at present this 
+library doesn't break any new ground, it provides an API for reading the most common 
+data from Jenkins in addition to being able to trigger remote builds.  Future releases 
+already in the works will allow creating new objects on Jenkins (like jobs), as well as 
+reading them.
+
+Currently, the following data objects are supported:
+
+- Job
+- Build
+- Node
+- Queue Item
+- View
+
+Installation
+------------
+This package can be installed using composer:
+```
+  "require": {
+    "mogman1/jenkins-web-api": "1.*"
+  }
+```
+
+Usage
+-----
+All implementations of ApiObject use the Jenkins class to communicate with your Jenkins 
+server, with the actual connection information managed by the Http class:
+
+```php
+use mogman1\Jenkins\Jenkins
+use mogman1\Jenkins\Server\Http
+
+$http = new Http("http://jenkins-server", "jenkinsUsername", "userAccessToken");
+$jenkins = new Jenkins($http);
+```
+
+The library assumes that Jenkins' CSRF crumb tokens are being used and automatically 
+fetches a crumb for each request (a future release will check if crumbs are being used
+and change behaviour accordingly).
+
+The Jenkins class can be used to fetch top-level information, such as info on the 
+Views available, the Jenkins Node, or available Jobs.
+
+```php
+$node = $jenkins->getNodeInfo();
+foreach ($node->jobs as $job) {
+  echo $job->name."\n";
+  echo $job->url."\n";
+  echo $job->color."\n";
+}
+```
+
+When objects are returned as part of information obtained from other objects, like 
+the jobs returned from the Node object, they are usually in reduced-info state to 
+minimize calls to Jenkins for information until you really need it.  The get all 
+fields available for that object, or simply to fetch the latest from the server, use 
+the update() method:
+
+```php
+$job->update();
+//access to additional fields, such as past builds
+foreach ($job->builds as $build) {
+  echo $build->number."\n";
+}
+```
+
+You can also directly fetch a job you already know the name of, which will come back 
+with all information already loaded (no need to call update()).
+
+```php
+$job = $jenkins->getJob("jenkins-web-api");
+//go crazy
+```
+
+Job objects are also capable of triggering builds.  If you have parameters enabled for 
+your job, you can pass them in as an array.  If your job requires the additional 
+authentication token, you'll need to pass this in as one of the parameters.  The return 
+value here is a QueueItem because Jenkins doesn't create an actual build right away 
+(see [this comment](https://issues.jenkins-ci.org/browse/JENKINS-12827?focusedCommentId=201381&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-201381) from the Jenkins issue tracker).  
+
+Getting information on the build you triggered can require some shenanigans.  Generally 
+a queue item is stuck in a Jenkins queue for a several seconds before being acted on by
+Jenkins, so you'll have to poll this object until the build becomes available under
+QueueItem::$executable.  However, please note that eventually queued items get removed 
+from the Jenkins queue and you won't be able to fetch data on it anymore (you'll get a 
+404 response which triggers an exception).  My experience is that it you have plenty of 
+time before it goes away, but keep that in mind.
+
+```php
+$queueItem = $job->triggerBuild(array('token' => "secret", 'param1' => "val1"));
+$build = null;
+try {
+  while (!$queueItem->executable) {
+    $queueItem->update()
+    sleep(1);
+  }
+
+  $build = $queueItem->executable;
+} catch (JenkinsConnectionException $e) {
+  //couldn't get build info
+}
+
+echo $build->getConsoleLog();
+```
+
+For everything else, take a look at the code.  All methods and properties have been
+commented to explain what they do (to the best of my knowledge at the time).  Please
+feel free to get in contact with me for feature requests, bug fixes, or anything else.
+
+Looking Forward
+---------------
+There are a few areas that I know will have interface-breaking changes sooner than later:
+
+- Users
+- Health Report (Job)
+- Action (multiple classes)
+- Property (Job)
+
+Basically any place where an array is being returned, I'm hoping to be able to convert 
+into full-on objects once I understand the what's being returned from Jenkins better.

composer.json

@@ -0,0 +1,29 @@
+{
+    "name": "mogman1/jenkins-web-api",
+    "description": "PHP API wrapper for retrieving information from Jenkins and triggering builds.",
+    "version": "1.0.0",
+    "type": "library",
+    "keywords": ["jenkins","api","ci"],
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Shaun Carlson",
+            "email": "[email protected]",
+            "role": "Developer"
+        }
+    ],
+    "support": {
+        "email": "[email protected]",
+        "source": "https://github.com/mogman1/jenkins-web-api",
+        "issues": "https://github.com/mogman1/jenkins-web-api/issues"
+    },
+    "require": {
+        "php": ">=5.3"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "4.1.*"
+    },
+    "autoload": {
+        "psr-0": {"mogman1\\": "src"}
+    }
+}

phpunit.xml.dist

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit bootstrap="./vendor/autoload.php" colors="true">
+  <testsuite>
+    <directory>test</directory>
+  </testsuite>
+  <filter>
+    <whitelist processUncoveredFilesFromWhitelist="true">
+      <directory suffix=".php">src</directory>
+    </whitelist>
+  </filter>
+  <logging>
+    <log type="coverage-html" target="build/coverage" charset="UTF-8" />
+  </logging>
+</phpunit>

src/mogman1/Jenkins/ApiObject.php

@@ -0,0 +1,75 @@
+<?php
+
+namespace mogman1\Jenkins;
+
+use mogman1\Jenkins\Exception\InvalidApiObjectException;
+
+abstract class ApiObject {
+  /**
+   * @var Jenkins
+   */
+  protected $conn;
+
+  /**
+   * Path on Jenkins server to fetch information on this API object from
+   * @var string
+   */
+  public $url;
+
+  public function __construct(Jenkins $conn, $url) {
+    $this->conn = $conn;
+    $this->url = $url;
+  }
+
+  /**
+   * Returns full URL with server info, instead of just path (which is stored in $url)
+   * @return string
+   */
+  public function getUrl() {
+    return $this->conn->getServerUrl().$this->url;
+  }
+
+  /**
+   * Determines if object is in a valid state
+   * @return bool
+   */
+  public function isValid() {
+    if (!$this->url) return FALSE;
+    if (!($this->conn instanceof Jenkins)) return FALSE;
+
+    return $this->isImpValid();
+  }
+
+  /**
+   * Required method for determining if implementing class is in a valid
+   * state.
+   *
+   * @return bool
+   */
+  abstract protected function isImpValid();
+
+  /**
+   * Updates object with information coming from Jenkins server
+   * @throws InvalidApiObjectException
+   */
+  public function update() {
+    $jsonData = $this->conn->get($this->url)->getJson();
+    $this->updateProperties($jsonData);
+  }
+
+  /**
+   * Receives data from a Jenkins API call and updates object properties
+   * @param JsonData $data
+   * @throws InvalidApiObjectException
+   */
+  public function updateProperties(JsonData $data) {
+    $this->updateImpProperties($data);
+    if (!$this->isValid()) throw new InvalidApiObjectException("API object in invalid state");
+  }
+
+  /**
+   * Required method for implementing class to update properties from data.
+   * @param JsonData $data
+   */
+  abstract protected function updateImpProperties(JsonData $data);
+}