techsemicolon/hubstaff

A package for Hubstaff API integration

Hubstaff Package for PHP

This is a PHP package which integrates hubstaff API and gives you an efficient way to add hubstaff data/reports into your project. There are many improvements in terms of optimization in this package which are discussed below when applicable., _(*1)

Installation

Via Composer, _(*2)

``` bash $ composer require techsemicolon/hubstaff, <sub>(*3)</sub>

## Getting your API credentials

You will following 3 credentials to start with your hubstaff API integration : 

1. Email : The email address you use to login into hubstaff
2. Password : The secure password you use to login into hubstaff
3. App Token : This is an API key which you can get by following below steps : 

    - Visit https://developer.hubstaff.com/
    - Login using email and password mentioned above
    - Go to My Apps on the left hand side menu (URL : https://developer.hubstaff.com/my_apps)
    - Click on "Create App" button
    - Enter the name of your application
    - Select The organization from the dropdown if you have multiple organizations
    - Click on "Save" and you will have your App Token which is a long alphanumeric string
    - Keep it safe, preferably store it in your env(environmental files) and not in your actual application 

## Getting data from the APIs

To check out hubstaff APIs reference, you can visit their official documentation url https://api.hubstaff.com/v1/

How it internally works : 

1. Hubstaff asks for email and password to get the auth token. Auth token is different that your app token. App token is like an API key whereas auth token is a secured authentication mechanism to make sure the request getting sent for API is well authenticated.
2. Then we use Auth Token and App Token together in headers to get the data we want

Don't Worry :  Everything mentioned above is handled internally by the package, so there is no overhead for you ;)

Expiry of Auth Token : 

Apparently the auth token for Hubstaff does not have any expiry. Hence, once you get an auth token, you can use it like forever within the application. 

Getting auth token on every request :

I will suggest you to get the auth token using from https://developer.hubstaff.com/docs/api#!/auth/postV1Auth and save it in your env file to use within your application. This package has a flexibility to get auth token dynamically as the parameter of $authToken in authenticate() method is optional. However if the auth token is not having any expiry, it makes sence to get it once and save it to reuse rather than calling auth token API frequently. Also their server will throw error 429 which means too many requests for a particular API endpoint. So its better to get auth token and save it in your env just like you may save your app token.

To get any data using method you can use following example: 


```php
require_once('vendor/autoload.php');

use Hubstaff\Hubstaff;
//Get instance of Hubstaff

$hubstaff = Hubstaff::getInstance();

// Authenticate hubstaff with credentials you have
$appToken = 'your_app_token';
$email = 'your_hubstaff_email';
$password = 'your_hubstaff_password';
$authToken = 'your_auth_token';

$hubstaff->authenticate($appToken, $email, $password, $authToken);

//Get Repository you want and call the method on the same
$users = $hubstaff->getRepository('user')->getAllUsers();

Note : We have used singleton pattern internally to make sure that once authenticated, it uses the same instance everywhere for optimization and efficienty purposes., <sub>(*4)</sub>

Following table gives details description of methods available :, <sub>(*5)</sub>