<commit_before>#Fractal wrapper for Laravel 5/Lumen#

[![Latest Stable Version](https://poser.pugx.org/appkr/fractal/v/stable)](https://packagist.org/packages/appkr/fractal) [![Total Downloads](https://poser.pugx.org/appkr/fractal/downloads)](https://packagist.org/packages/appkr/fractal) [![Latest Unstable Version](https://poser.pugx.org/appkr/fractal/v/unstable)](https://packagist.org/packages/appkr/fractal) [![License](https://poser.pugx.org/appkr/fractal/license)](https://packagist.org/packages/appkr/fractal)

This is a package, or rather, an **opinionated/laravel-istic use case of the famous [league/fractal](https://github.com/thephpleague/fractal) package in Laravel 5/Lumen environment**.

This project was started to fulfill a personal RESTful API service needs. In an initial attempt to evaluate various php API packages for Laravel, I found that the features of those packages providing are well excessive for my requirement.

If your requirement is simple like mine, this is the right package. But if you need more delicate package, head over to [chiraggude/awesome-laravel](https://github.com/chiraggude/awesome-laravel#restful-apis) to find a right one.

Using this package, I didn't want user of this package to sacrifice Laravel's recommended coding practices which we all commonly know, without having to require a package specific syntax/usage. And most importantly, I wanted he/she could build his/her API service quickly based on the examples provided.

## Usage
```php
// Respond json formatted 'Resource' model 
// including 'Manager' nesting, pagination, 
// and additional meta of ['version' => 1]
return $this->response()->setMeta(['version' => 1])->withPagination(
    Resource::with('manager')->latest()->paginate(25),
    new ResourceTransformer
);

// Respond simple json error with 422 response code
return $this->response()->unprocessableError($errors);
```

---

##Index

- [Goal](#goal)
- [Install](#install)
- [Bundled Example](#example)
- [Best Practices](#best-practices)
    - [Route(API Endpoints)](#route)
    - [Controller](#controller)
    - [FormRequest](#form-request)
    - [Handle TokenMismatchException](#token)
    - [Formatting Laravel's General Exceptions.](#exception-formatting)
    - [CORS in Javascript Client](#cors)
- [Avaliable Response Methods](#api)
- [Access API Endpoints from a Client](#client)

---

<a name="goal"></a>
##Goal
- Provides easy access to Fractal instance for Laravel 5/Lumen (ServiceProvider).
- Provides configuration capability for Fractal and response format.
- Provides use case examples, so that users can quickly copy & paste to his/her project.

<a name="install"></a>
##Install
Use composer. Define `"appkr/fractal": "0.4.*"` at your project `composer.json`'s require section and `composer update`.

Or require it directly at a console.

```bash
$ composer require "appkr/fractal:0.4.*"
```

Add the service provider.

```php
// For Laravel - config/app.php
'providers'=> [
    Appkr\Fractal\ApiServiceProvider::class,
]

// For Lumen - boostrap/app.php
$app->register(Appkr\Fractal\ApiServiceProvider::class);
```

Finally, issue a publish assets command at a console.

```bash
// For Laravel only
$ php artisan vendor:publish --provider="Appkr\Fractal\ApiServiceProvider"
```

Configuration file is located at `config/fractal.php` or `vendor/appkr/fractal/src/config/fractal.php`.

Done !

---<commit_msg>explicit setting of fractal version was explained<commit_after>#Fractal wrapper for Laravel 5/Lumen#

[![Latest Stable Version](https://poser.pugx.org/appkr/fractal/v/stable)](https://packagist.org/packages/appkr/fractal) [![Total Downloads](https://poser.pugx.org/appkr/fractal/downloads)](https://packagist.org/packages/appkr/fractal) [![Latest Unstable Version](https://poser.pugx.org/appkr/fractal/v/unstable)](https://packagist.org/packages/appkr/fractal) [![License](https://poser.pugx.org/appkr/fractal/license)](https://packagist.org/packages/appkr/fractal)

This is a package, or rather, an **opinionated/laravel-istic use case of the famous [league/fractal](https://github.com/thephpleague/fractal) package in Laravel 5/Lumen environment**.

This project was started to fulfill a personal RESTful API service needs. In an initial attempt to evaluate various php API packages for Laravel, I found that the features of those packages providing are well excessive for my requirement.

If your requirement is simple like mine, this is the right package. But if you need more delicate package, head over to [chiraggude/awesome-laravel](https://github.com/chiraggude/awesome-laravel#restful-apis) to find a right one.

Using this package, I didn't want user of this package to sacrifice Laravel's recommended coding practices which we all commonly know, without having to require a package specific syntax/usage. And most importantly, I wanted he/she could build his/her API service quickly based on the examples provided.

## Usage
```php
// Respond json formatted 'Resource' model 
// including 'Manager' nesting, pagination, 
// and additional meta of ['version' => 1]
return $this->response()->setMeta(['version' => 1])->withPagination(
    Resource::with('manager')->latest()->paginate(25),
    new ResourceTransformer
);

// Respond simple json error with 422 response code
return $this->response()->unprocessableError($errors);
```

---

##Index

- [Goal](#goal)
- [Install](#install)
- [Bundled Example](#example)
- [Best Practices](#best-practices)
    - [Route(API Endpoints)](#route)
    - [Controller](#controller)
    - [FormRequest](#form-request)
    - [Handle TokenMismatchException](#token)
    - [Formatting Laravel's General Exceptions.](#exception-formatting)
    - [CORS in Javascript Client](#cors)
- [Avaliable Response Methods](#api)
- [Access API Endpoints from a Client](#client)

---

<a name="goal"></a>
##Goal
- Provides easy access to Fractal instance for Laravel 5/Lumen (ServiceProvider).
- Provides configuration capability for Fractal and response format.
- Provides use case examples, so that users can quickly copy & paste to his/her project.

<a name="install"></a>
##Install
Use composer. Define `"appkr/fractal": "0.4.*"` and `"league/fractal": "@dev",` at your project `composer.json`'s require section and `composer update`.

```json
"require": {
  "...": "...",
  "appkr/fractal": "0.4.*",
  "league/fractal": "@dev",
}
```

**`Note`** Since this package depends on the `setMeta()` api of the `league/fractal` which is available only at 0.13.*@dev, but the `league/fractal` have not tagged a stable 0.13 release yet, we need to explicitly lower the minimum-stability of the `league/fractal` at our root project's composer.json. That way we can avoid lowering the minimum-stability setting to dev at our root project's composer.json.

Add the service provider.

```php
// For Laravel - config/app.php
'providers'=> [
    Appkr\Fractal\ApiServiceProvider::class,
]

// For Lumen - boostrap/app.php
$app->register(Appkr\Fractal\ApiServiceProvider::class);
```

Finally, issue a publish assets command at a console.

```bash
// For Laravel only
$ php artisan vendor:publish --provider="Appkr\Fractal\ApiServiceProvider"
```

Configuration file is located at `config/fractal.php` or `vendor/appkr/fractal/src/config/fractal.php`.

Done !

---
{'fraction_non_alphanumeric': 0.1354209586595248, 'fraction_numerical': 0.004669688229638786, 'mean_word_length': 4.738376674546887, 'pattern_counts': {'":': 7, '<': 11, '<?xml version=': 0, '>': 33, 'https://': 20, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7672457', 'n_tokens_mistral': 2307, 'n_tokens_neox': 2181, 'n_words': 688}