LarsNieuwenhuizen/ClubhouseConnector

<a href="https://codeclimate.com/github/LarsNieuwenhuizen/ClubhouseConnector/maintainability"><img src="https://api.codeclimate.com/v1/badges/9d0b03e99be71ba6c335/maintainability" /></a>
<a href="https://codeclimate.com/github/LarsNieuwenhuizen/ClubhouseConnector/test_coverage"><img src="https://api.codeclimate.com/v1/badges/9d0b03e99be71ba6c335/test_coverage" /></a>
[![Build Status](https://travis-ci.org/LarsNieuwenhuizen/ClubhouseConnector.svg?branch=master)](https://travis-ci.org/LarsNieuwenhuizen/ClubhouseConnector)

# Clubhouse connector

This library allows you to easily make use of
the Clubhouse api integrations through one connector.

## Single point of entry
All you need to do is construct the Connector object with a configuration file.
The configuration is done throught yaml and looks like this.

#### config.yaml
```yaml
Clubhouse:
  api:
    uri: 'https://api.clubhouse.io/api/v3/'
    token: 'myApiTokenHere'
```

#### Creating the connector

```phph
$connector = new Connector('config.yaml');
```

#### Using clubhouse components
The components are accessed through their respective services like this:

```php
$connector->getEpicsService()->list();
```

This as you probably expects call the list of epics.
This will return you a collection on Epic objects.

## Objectification
All the Clubhouse resources will translated into Domain objects per component.

### Resource models and collections
All resource types will have their own Model and when retrieving multiple items,
the models will be gathered in IteratorAggregate Collections.

This is done so collections retrieved can be iterated over instantly and data is converted into
models, so we can use the data in a more specified way and make better use of the data later on.

So for example:

```php
$epics = $connector->epics()->list();

foreach ($epics as $epic) {
    echo $epic->getName();
    echo $epic->getCreatedAt()->format('d-m-Y');
}
```

## Using the services

There will be services created for all components within Clubhouse and subcomponents (labels, categories, comments etc...)

To use a service you'll access it throught the connector as described above.

### CRUD examples

1. Create an Epic

```php
$epic = new Epic();
$epic->setName('My first created Epic')
    ->setDescription('This is the description for my Epic');

$createdEpic = $connector->epics()->create($epic);
```

2. Update an existing Epic
```php
$existingEpic = $connector->epics()->get(1);
$existingEpic->setName('A new name for this Epic');

$updatedEpic = $connector->epics()->update($existingEpic);
```

3. Delete an Epic
```php
$connector->epics()->delete(1);
```

4. List all Epics
```php
$collection = $connector->epics()->list();
```


## Currently usable resources

  - Epics
  - Milestones
  - Projects
  - Stories
  
```php
$connector->epics()
$connector->milestones()
$connector->projects()
$connector->stories()
```

## PSR Logging

You can add your own logger if you feel the need to catch the logs somewhere :)
All you need is a logger which interfaces with [PSR-3 logger interface](https://www.php-fig.org/psr/psr-3/).

When you have that simply construct the connector with it as such:

```php
$logger = new MyOwnPsrLogger();
$connector = new Connector('config.yaml', $logger);
```

## Magic methods
The method and variable names I used in the connector are like `getEpicsService()`
But to make it a bit more relatable with Clubhouse naming and simply a bit shorter,
I added magic method calls for the services.

So instead of calling `$connector->getEpicsService()->list()`
You can also call `$connector->epics()->list()`