<commit_before>[![Build Status](https://travis-ci.org/tebru/retrofit-php.svg?branch=master)](https://travis-ci.org/tebru/retrofit-php)

# Retrofit PHP
This library aims to ease creation of REST clients.  It is blatantly stolen from square/retrofit (https://github.com/square/retrofit) and implemented in PHP.

## Installation
This library is still under development.  Please install from dev-master.

```
composer require tebru/retrofit-php:dev-master
```

## Setup
You must register the annotation namespaces.  For example:

```
AnnotationRegistry::registerAutoloadNamespace('Tebru\Retrofit\Annotation', __DIR__ . '/vendor/tebru/retrofit-php/src');
AnnotationRegistry::registerAutoloadNamespace('JMS\Serializer\Annotation', __DIR__ . '/vendor/jms/serializer/src');
```

Create a new `Retrofit` object and specify the cache directory.  Defaults to `/tmp`

```
$retrofit = new \Tebru\Retrofit\Retrofit(__DIR__ . '/cache');
```

Register all services with the `Retrofit` object.  These are the interfaces you're creating.  This is necessary to generate the cache file.

```
$retrofit->registerServices([FooService::class, BarService::class]);
$retrofit->registerService(BazService::class);
```

Create the cache.  We need to do this in order to prevent costly class generation during runtime.  Passing `false` to this method will only compile the classes if a cache file does not currently exist.

```
$retrofit->createCache(true|false);
```

Finally load the classes into memory.

```
$retrofit->load();
```

You can use the console command (likely in `vendor/tebru/retrofit-php/bin/console`) to generate the cache file

Run `path/to/console retrofit:compile source/directory cache/directory`

Source and cache directory are both relative to the directory you're executing the command from

## Usage Overview
*Usage examples are referenced from Square's documentation*

Retrofit allows you to define your REST API through annotations.

```
<?php

use Tebru\Retrofit\Annotation as Rest;

interface GitHubService
{
    /**
     * @Rest\GET("/users/{user}/list")
     * @Rest\Returns("ArrayCollection<ListRepo>")
     */
    public function listRepos($user);
}
```

```
<?php

use Tebru\Retrofit\Adapter\RestAdapter;<commit_msg>Updating docs<commit_after>[![Build Status](https://travis-ci.org/tebru/retrofit-php.svg?branch=master)](https://travis-ci.org/tebru/retrofit-php)

# Retrofit PHP
This library aims to ease creation of REST clients.  It is blatantly stolen from square/retrofit (https://github.com/square/retrofit) and implemented in PHP.

## Installation
This library is still under development.  Please install from dev-master.

```
composer require tebru/retrofit-php:dev-master
```

## Setup
You must register the annotation namespaces.  For example:

```
AnnotationRegistry::registerAutoloadNamespace('Tebru\Retrofit\Annotation', __DIR__ . '/vendor/tebru/retrofit-php/src');
AnnotationRegistry::registerAutoloadNamespace('JMS\Serializer\Annotation', __DIR__ . '/vendor/jms/serializer/src');
```

Create a new `Retrofit` object and specify the cache directory.  Defaults to `/tmp`

```
$retrofit = new \Tebru\Retrofit\Retrofit(__DIR__ . '/cache');
```

Register all services with the `Retrofit` object.  These are the interfaces you're creating.  This is necessary to generate the cache file.

```
$retrofit->registerServices([FooService::class, BarService::class]);
$retrofit->registerService(BazService::class);
```

Create the cache.  We need to do this in order to prevent costly class generation during runtime.  Passing `false` to this method will only compile the classes if a cache file does not currently exist.

```
$retrofit->createCache(true|false);
```

Finally load the classes into memory.

```
$retrofit->load();
```

You can use the console command (likely in `vendor/tebru/retrofit-php/bin/console`) to generate the cache file.  In some development/deployment workflows, all of the above setup could be bypassed using the command to generate the cache file.  The only requirement after the cache is generated is to require the file, which is what `load()` does.

Run `path/to/console retrofit:compile source/directory cache/directory`

Source and cache directory are both relative to the directory you're executing the command from

## Usage Overview
*Usage examples are referenced from Square's documentation*

Retrofit allows you to define your REST API through annotations.

```
<?php

use Tebru\Retrofit\Annotation as Rest;

interface GitHubService
{
    /**
     * @Rest\GET("/users/{user}/list")
     * @Rest\Returns("ArrayCollection<ListRepo>")
     */
    public function listRepos($user);
}
```

```
<?php

use Tebru\Retrofit\Adapter\RestAdapter;
{'fraction_non_alphanumeric': 0.11573777493060004, 'fraction_numerical': 0.0, 'mean_word_length': 4.9291139240506325, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 13, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6731528', 'n_tokens_mistral': 1415, 'n_tokens_neox': 1355, 'n_words': 448}