Merge pull request #96 from orlitzky/master

Add autoloader to allow manual installation and update documentation

Author: kbsali

README.markdown

@@ -8,32 +8,32 @@ Uses [Redmine API](http://www.redmine.org/projects/redmine/wiki/Rest_api/).
 
 * Follows PSR-0 conventions and coding standard: autoload friendly
 * API entry points implementation state :
- * OK Attachments
- * OK Groups
- * OK Custom Fields
- * OK Issues
- * OK Issue Categories
- * OK Issue Priorities
- * *NOK Issue Relations - only partially implemented*
- * OK Issue Statuses
- * OK News
- * OK Projects
- * OK Project Memberships
- * OK Queries
- * OK Roles
- * OK Time Entries
- * OK Time Entry Activities
- * OK Trackers
- * OK Users
- * OK Versions
- * OK Wiki
+* OK Attachments
+* OK Groups
+* OK Custom Fields
+* OK Issues
+* OK Issue Categories
+* OK Issue Priorities
+* *NOK Issue Relations - only partially implemented*
+* OK Issue Statuses
+* OK News
+* OK Projects
+* OK Project Memberships
+* OK Queries
+* OK Roles
+* OK Time Entries
+* OK Time Entry Activities
+* OK Trackers
+* OK Users
+* OK Versions
+* OK Wiki
 
 ## Todo
 
 * Check header's response code (especially for POST/PUT/DELETE requests)
- * See http://stackoverflow.com/questions/9183178/php-curl-retrieving-response-headers-and-body-in-a-single-request/9183272#9183272
+* See http://stackoverflow.com/questions/9183178/php-curl-retrieving-response-headers-and-body-in-a-single-request/9183272#9183272
 * Maybe Guzzle for handling http connections
- * https://github.com/guzzle/guzzle
+* https://github.com/guzzle/guzzle
 
 ## Limitations
 
@@ -45,27 +45,98 @@ A possible solution to this would be to create an extra APIs implementing the mi
 
 ## Requirements
 
-* PHP >= 5.3.2 with [cURL](http://php.net/manual/en/book.curl.php) extension,
+* PHP >= 5.4
+* The PHP [cURL](http://php.net/manual/en/book.curl.php) extension
+* The PHP [SimpleXML](http://php.net/manual/en/book.simplexml.php) extension
+* The PHP [JSON](http://php.net/manual/en/book.json.php) extension
+* [PHPUnit](https://phpunit.de/) >= 4.0 (optional) to run the test suite
 * "Enable REST web service" for your Redmine project (/settings/edit?tab=authentication)
- * then obtain your *API access key* in your profile page : /my/account
- * or use your *username & password*
+* then obtain your *API access key* in your profile page : /my/account
+* or use your *username & password*
 
 ## Install
 
-Through [composer](http://getcomposer.org/download/), simply run :
+### Composer
+
+[Composer](http://getcomposer.org/download/) users can simply run:
 
 ```bash
 $ php composer.phar require kbsali/redmine-api:~1.0
 ```
 
+at the root of their projects. To utilize the library, include
+Composer's `vendor/autoload.php` in the scripts that will use the
+`Redmine` classes.
+
+For example,
+
+```php
+<?php
+// This file is generated by Composer
+require_once 'vendor/autoload.php';
+$client = new Redmine\Client('http://redmine.example.com', 'username', 'password');
+```
+
+### Manual
+
+It is also possible to install the library oneself, either locally to
+a project or globally; say, in `/usr/share/php`.
+
+First, download and extract the library somewhere. For example, the
+following steps extract v1.5.1 of the library into the
+`vendor/php-redmine-api-1.5.1` directory:
+
+```bash
+$ mkdir vendor
+$ wget -q https://github.com/kbsali/php-redmine-api/archive/v1.5.1.tar.gz
+$ tar -xf v1.5.1.tar.gz -C vendor/
+$ rm v1.5.1.tar.gz
+```
+
+Now, in any scripts that will use the `Redmine` classes, include the
+`lib/autoload.php` file from the php-redmine-api directory. For
+example,
+
+```php
+<?php
+// This file ships with php-redmine-api
+require 'vendor/php-redmine-api-1.5.1/lib/autoload.php';
+$client = new Redmine\Client('http://redmine.example.com', 'username', 'password');
+```
+
+### Running the test suite
+
+If you have [PHPUnit](https://phpunit.de/) >= 4.0 installed, you can
+run the test suite to make sure that the library will function
+properly on your system. Simply run `phpunit` in the php-redmine-api
+directory. For example,
+
+```
+$ phpunit
+PHPUnit 4.3.1 by Sebastian Bergmann.
+
+Configuration read from ./phpunit.xml.dist
+
+...............................................................  63 / 276 ( 22%)
+............................................................... 126 / 276 ( 45%)
+............................................................... 189 / 276 ( 68%)
+............................................................... 252 / 276 ( 91%)
+........................
+
+Time: 591 ms, Memory: 10.50Mb
+```
+
 ## Basic usage of `php-redmine-api` client
 
 ```php
 <?php
 
-// This file is generated by Composer
+// For Composer users (this file is generated by Composer)
 require_once 'vendor/autoload.php';
 
+// Or if you've installed the library manually, use this instead.
+// require 'vendor/php-redmine-api-x.y.z/lib/autoload.php';
+
 $client = new Redmine\Client('http://redmine.example.com', 'API_ACCESS_KEY');
 //-- OR --
 $client = new Redmine\Client('http://redmine.example.com', 'username', 'password');
@@ -84,7 +155,7 @@ $client->api('issue')->all([
 ]);
 ```
 
-see `example.php`
+See `example.php` for further examples.
 
 ## User Impersonation
 
@@ -110,4 +181,4 @@ $client->setImpersonateUser(null);
 * Thanks to [Thomas Spycher](https://github.com/tspycher/) for the 1st version of the class.
 * Thanks to [Thibault Duplessis aka. ornicar](https://github.com/ornicar) for the php-github-api library, great source of inspiration!
 * And all the [contributors](https://github.com/kbsali/php-redmine-api/graphs/contributors)
- * specially [JanMalte](https://github.com/JanMalte) for his impressive contribution to the test coverage! :)
+* specially [JanMalte](https://github.com/JanMalte) for his impressive contribution to the test coverage! :)

lib/autoload.php

@@ -0,0 +1,31 @@
+<?php
+
+/* An autoloader for Redmine\Foo classes. This should be require()d by
+ * the user before attempting to instantiate any of the Redmine
+ * classes.
+ */
+
+spl_autoload_register(function ($class) {
+    /* All of the classes have names like "Redmine\Foo", so we need to
+     * replace the backslashes with frontslashes if we want the name
+     * to map directly to a location in the filesystem.
+     */
+    $class = str_replace('\\', '/', $class);
+
+    /* First, check under the current directory. It is important that
+     * we look here first, so that we don't waste time searching for
+     * test classes in the common case.
+     */
+    $path = dirname(__FILE__).'/'.$class.'.php';
+    if (file_exists($path)) {
+        require_once($path);
+    }
+
+    /* If we didn't find what we're looking for already, maybe it's
+     * a test class?
+     */
+    $path = dirname(__FILE__).'/../test/'.$class.'.php';
+    if (file_exists($path)) {
+        require_once($path);
+    }
+});

phpunit.xml.dist

@@ -9,7 +9,7 @@
          processIsolation="false"
          stopOnFailure="false"
          syntaxCheck="false"
-         bootstrap="test/bootstrap.php"
+         bootstrap="lib/autoload.php"
 >
     <testsuites>
         <testsuite name="php-redmine-api Test Suite">