Thursday, June 18, 2015

Feature of the Week: New REST Client for PHP

We spent some time developing a new full-featured REST Client in PHP in order to make it much easier for you to develop new Apps for the BibSonomy universe.

The new REST client library comes with a lot of new features:


  • It's full-featured that means the client supports the whole functionality of the API.
  • It contains a model such that it is convenient for you to work with the data.
  • It supports Basic Auth as well as OAuth authentication methods.
  • It's easy to integrate in your PHP App, since we have used composer, a powerful tool in order to integrate and autoload requirements of 3rd party software.
  • You can output a fetched set of publications as a CSL-rendered publication list in your favorite citation style.

In order to use the restclient-php library you need to do three steps:

  1. Install the library via composer and include the autoloader file.

    Installing Composer locally is a matter of just running the installer in your project directory:

    curl -sS https://getcomposer.org/installer | php

    Then, add the restclient to the requirements of your project. Run the following command on a terminal within your project folder:

    php composer.phar require academicpuma/restclient-php:1.0.0-alpha
     
  2. Create an Accessor. This object is required to authenticate your App on the REST API of BibSonomy. You can choose between two authentication methods, Basic Auth or OAuth. For Basic Auth this would be:

    <?php

    require 'path/to/vendor/autoload.php';
    use AcademicPuma\RestClient\Accessor\BasicAuthAccessor;

    $accessor = new BasicAuthAccessor('http://www.bibsonomy.org', [your-username], '[your-apikey]');
    ?>
     
  3. Create a RESTClient object and perform a request. This object is your interface to BibSonomy. This class provides all supported functions to get, create, update, and delete posts, tags, documents, user and groups. For example:

    <?php

    use AcademicPuma\RestClient\RESTClient;
    use AcademicPuma\RestClient\Config;

    $restClient = new RESTClient($accessor);
    //choose Resource type and tags
    $restClient->getPosts(Config\Resourcetype::BIBTEX, Config\Grouping::USER, [username], ['tag1', 'tag2']);
    ?>


    Now, you can choose the format. There are four options: XML, CSL (JSON), Model (PHP Objects), Bibliography (CSL-rendered publication list):

    <?php
    
    
    //output xml
    echo $restClient->xml();
    
    //output CSL
    echo json_encode($restClient->csl());
    
    //use the model
    $posts = $restClient->model();
    foreach($posts as $post) {
        echo $post->getResource()->getTitle()."<br />\n";
    }
    
    //print a bibliography in your preferred style and language
    echo $restClient->bibliography('apa', 'en-US');
    
    ?>
    
Currently restclient-php is considered as unstable alpha version. If you encounter  any errors or problems, feel free to report an issue on our code repository.

Happy tagging,
Sebastian.