talanoff/laravel-wubook

A WuBook bridge for Laravel 5.x, 6.x, 7.x http://wubook.net

0.1.1 2020-03-20 13:47 UTC

This package is auto-updated.

Last update: 2022-07-20 19:12:36 UTC


README

Laravel WuBook was created by, and is maintained by Filippo Galante, and is a WuBook Wired API bridge for Laravel 5. Feel free to check out the change log, releases, license, and contribution guidelines. In order to use the API you have to request a provider key by sending an E-Mail at devel@wubook.net, in order to connect your WuBook account, and you'll be free to try all its features.

Latest Version on Packagist Software License StyleCI Build Status Coverage Status Quality Score Total Downloads

Installation

Either PHP 5.5+ or HHVM 3.6+ are required.

To get the latest version of Laravel WuBook, simply require the project using Composer:

$ composer require talanoff/laravel-wubook

Instead, you may of course manually update your require block and run composer update if you so choose:

{
    "require": {
        "talanoff/laravel-wubook": "0.1.*"
    }
}

The package uses the fxmlrpc client to make a call to the Wired API service. The standard dependencies are used to create the HTTP client and message, feel free to create a pull request in order to add new features.

Once Laravel WuBook is installed, you need to register the service provider. Open up config/app.php and add the following to the providers key.

'providers' => [
   // OTHER PROVIDERS
   'Talanoff\LaravelWubook\WuBookServiceProvider::class'
],

You can register the WuBook facade in the aliases key of your config/app.php file if you like.

'aliases' => [
   // OTHER ALIASES
   'WuBook' => Talanoff\LaravelWubook\Facades\WuBook::class
],

Configuration

Laravel WuBook requires connection configuration.

Create a config/wubook.php file in your app that you can modify to set your configuration. Also, make sure you check for changes to the original config file in this package between releases.

Account parameters
[
    'username' => 'your-user',              
    'password' => 'your-password',          
    'provider_key' => 'your-provider-key', 
    'lcode' => 'your-lcode',
]

The lcode parameter is a property ID provided by WuBook and you can find it the main control panel within the profile management section.

The provider_key is released by the WuBook development team and if you need to create a new key associated with your WuBook account, please write an E-Mail at devel@wubook.net.

cache_token parameter

If cache_token parameter is set to true, all the API function will use a cached value and automatically renew it if necessary. If you need to retrieve the current token, call the method

Cache::get('wubook.token')     // ex. '9869117656.9552'

The package will store also a 'wubook.token.ops' key, in order to trace the number of calls made with current token, in order to refresh it if the maximum number of operation has been reached.

Attention: If cache_token is set to false, the package will not check if the token has exceeded the maximum number of operations!

The values stored inside the cache will expire after 3600 seconds and if the cache_token parameter is set to true it will be automatically renewed. Please read http://tdocs.wubook.net/wired/policies.html

Usage

WuBookManager

This is the class of most interest. It is bound to the ioc container as 'wubook' and can be accessed using the Facades\WuBook facade. In order to make a call to the Wired API, you may call these methods that refers to a specific area of the service.

Facades\WuBook

This facade will dynamically pass static method calls to the 'wubook' object in the ioc container which by default is the WuBookManager class.

WuBookServiceProvider

This class contains no public methods of interest. This class should be added to the providers array in config/app.php. This class will setup ioc bindings.

WuBook API methods results

The fxmlrpc client always returns an associative array, that may be changed by the package in order to retrieve the resulting data from the XML/RPC function.

If an error occured during the call, a WuBookException will be thrown. If the call is successfully executed (see http://tdocs.wubook.net/wired/return.html) an array will be returned with this values:

// An error occurred
return [
    'has_error' => true,
    'data' => 'A human readeable error message'
]

// Success
return [
    'has_error' => false,
    'data' => [ /* THE XML/RPC FUNCTION RESPONSE */ ]
]

Only the WuBookAuth API returns different values for a successful call:

acquire_token()             
// returns a string (ex. '9869117656.9552'), throws an exception otherwise

release_token($token)       
// returns a boolean if the token is successfully released, throws an exception otherwise

is_token_valid($token, $request_new = false)        
// - if the token is valid returns an integer representing the total operations made with the token
// - if `request_new` is set to `true` and the token is not valid the method `aquire_token()` is called
// - false otherwise

provider_info($token = null)
// returns an array with the provider infos
Real Examples

Here you can see an example of just how simple this package is to use. Out of the box, the default cache_token parameter is set to false so:

use Talanoff\LaravelWuBook\Facades\WuBook;
// you can alias this in config/app.php if you like

// Retrieve the token
$token = WuBook::auth()->acquire_token()        // (ex. '9869117656.9552')

WuBook::rooms()->fetch_rooms(1)                 // See http://tdocs.wubook.net/wired/rooms.html#fetching-existing-rooms
// this example is simple, and there are far more methods available
// The result will be an associative array with this structure

[
    0 => [
        id => 123,
        name => 'room',
        shortname => 'ro',
        occupancy => 2,
        men => 2,
        children => 0,
        subroom => 0,
        // ...
    ],
    1 => [
        // ...
    ],
]

If you prefer to use dependency injection over facades like me, then you can easily inject the manager like so:

use Talanoff\LaravelWuBook\WuBookManager;
use Illuminate\Support\Facades\App; // you probably have this aliased already

class RoomManager
{
    protected $wubook;

    public function __construct(WuBookManager $wubook)
    {
        $this->wubook = $wubook;
    }

    public function fetch_rooms($ancillary = 0)
    {
        $this->wubook->fetch_rooms($ancillary);
    }
}

App::make('RoomManager')->fetch_rooms(1);

For more information on how to use the \LaravelWubook\WuBookManager class we are calling behind the scenes here, check out the Wired API doc.

Further Information

There are other classes in this package that are not documented here. This is because they are not intended for public use and are used internally by this package.

Security

If you discover a security vulnerability within this package, please send an e-mail to Filippo Galante at filippo.galante@b-ground.com. All security vulnerabilities will be promptly addressed.

License

Laravel WuBook is licensed under The MIT License (MIT).