# restclient-php  #

[![Latest Version](https://img.shields.io/packagist/v/academicpuma/restclient-php.svg?style=flat-square)](https://packagist.org/packages/academicpuma/restclient-php)
[![License](https://img.shields.io/badge/license-GPLv3-blue.svg?style=flat-square)](https://bitbucket.org/bibsonomy/restclient-php/raw/default/license.txt)
[![PHP](https://img.shields.io/badge/PHP-%3E=5.4-green.svg?style=flat-square)](http://docs.php.net/manual/en/migration54.new-features.php)

The **restclient-php** library is a full-featured REST Client for PUMA and BibSonomy written in PHP. This library uses [Guzzle HTTP Client](https://github.com/guzzle) for HTTP requests.

**Table of Contents**

[TOC]

## Features ##

* provides all functions that are supported by the PUMA/BibSonomy API
* contains model classes for easy data handling
* supports BasicAuth authentication
* supports OAuth authentication
* easy to use with the help of the Composer Autoloader and PHP Namespaces.

## System requirements ##

* PHP 5.4
* Composer
* cURL for PHP

## Changelog ##

**Version 1.0.10**

Display and inline math modes are also recognized by the "remove curly braces" option now.

**Version 1.0.8**

* Fixed bug where curly braces of the misc field would be removed which produced errors when parsing the field.

**Version 1.0.7**

* Fixed bug in appendMiscProp function.

**Version 1.0.6**

* New option introduced to determine whether BibTex cleaning should be applied.

**Version 1.0.5**

* New options were introduced to determine how curly braces will be handled (removed/unhandled).

**Version 1.0.4**

* Introduced options for handling curly braces in abstracts.
* Added possibility to pass curl options to requests.

**Version 1.0.1**

* URL encoding in URLBuilder added
* Tex decoding added
* Confusing constant names of the `Grouping` class changed

## Getting started ##

### Installation ###

- Get Composer here: (https://getcomposer.org/download/ "Download Composer")
- Install Composer: (https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx "How To Install Composer")
- Add the restclient to your "requires" within composer.json file:

```json
"require": {
        "academicpuma/restclient-php": "^1.0"
}
```

More information about Composer you will find [here](https://bitbucket.org/bibsonomy/restclient-php/wiki/Home#markdown-header-installation-via-composer)

### Creating a Client ###

In order to instantiate a RESTClient object, an Accessor object has to be created. It holds authentication information, the base URL which will be prepend to all HTTP requests, and the RESTClient itself. There are two available Accessor
classes. One for "BasicAuth" and one for "OAuth".

The RESTClient constructor expects an Accessor object.

```php
<?php

require 'path/to/vendor/autoload.php';

use AcademicPuma\RestClient\RESTClient;
use AcademicPuma\RestClient\Accessor\BasicAuthAccessor;

$basicAuthAccessor = new BasicAuthAccessor('http://puma.uni-kassel.de', 'John_Doe', '123abc456def');
$restClient = new RESTClient($basicAuthAccessor);

?>
```

More Information about Accessors you will find [here](https://bitbucket.org/bibsonomy/restclient-php/wiki/Home#markdown-header-create-an-accessor).

### Making requests ###

Simply call a method on a RESTClient object to trigger the specified REST-API method:

```php
<?php

echo $restClient->getPosts()->xml();

?>
```

[Get more Information about requests](https://bitbucket.org/bibsonomy/restclient-php/wiki/Basic%20Requests)

Information retrieved from the REST-API can also be comfortably represented in form of Model-Objects:

```php
<?php

$posts = $restClient->getPosts()->model();
$post = $posts[0];
echo $post->getResource()->getTitle();

?>
```

## OAuth for PUMA and BibSonomy ##

Have a look at [https://bitbucket.org/bibsonomy/restclient-php/wiki/OAuth](https://bitbucket.org/bibsonomy/restclient-php/wiki/OAuth) for using __restclient-php__ with OAuth authentication.