Skip to content

Commit

Permalink
✨ Finalize v3
Browse files Browse the repository at this point in the history
  • Loading branch information
@marcreichel
marcreichel committed Oct 21, 2021
1 parent b2df4ab commit fd80fce
Show file tree
Hide file tree
Showing 51 changed files with 701 additions and 336 deletions.
194 changes: 107 additions & 87 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@
[![GitHub](https://img.shields.io/github/license/marcreichel/igdb-laravel)](https://packagist.org/packages/marcreichel/igdb-laravel)
[![Gitmoji](https://img.shields.io/badge/gitmoji-%20😜%20😍-FFDD67.svg)](https://gitmoji.dev)

This is a Laravel wrapper for version 4 of the [IGDB API](https://api-docs.igdb.com/) (Apicalypse) including [webhook handling](#-webhooks-since-v230) since version 2.3.0.
This is a Laravel wrapper for version 4 of the [IGDB API](https://api-docs.igdb.com/) (Apicalypse)
including [webhook handling](#-webhooks-since-v230) since version 2.3.0.

## Basic installation

Expand Down Expand Up @@ -45,6 +46,11 @@ return [
*/
'cache_lifetime' => env('IGDB_CACHE_LIFETIME', 3600),

/*
* Path where the webhooks should be handled.
*/
'webhook_path' => 'igdb-webhook/handle',

/*
* The webhook secret.
*
Expand All @@ -58,8 +64,8 @@ return [
## Usage

If you're familiar with the [Eloquent System](https://laravel.com/docs/eloquent)
and the [Query Builder](https://laravel.com/docs/queries) of Laravel you
will love this package as it uses a similar approach.
and the [Query Builder](https://laravel.com/docs/queries) of Laravel you will love this package as it uses a similar
approach.

### Models

Expand All @@ -77,9 +83,8 @@ $games = Game::where('first_release_date', '>=', 1546297200)->get();

### Query Builder

You can use one of the defined models listed above. The search results will be
mapped into the used model automatically then. This method is used in the
examples below.
You can use one of the defined models listed above. The search results will be mapped into the used model automatically
then. This method is used in the examples below.

Otherwise you can use the Query Builder itself like this:

Expand All @@ -93,10 +98,9 @@ $games = $igdb->get();

#### Select

Select which fields should be in the response. If you want to have all available
fields in the response you can also skip this method as the query builder will
select `*` by default. (**Attention**: This is the opposite behaviour from the
Apicalypse API)
Select which fields should be in the response. If you want to have all available fields in the response you can also
skip this method as the query builder will select `*` by default. (**Attention**: This is the opposite behaviour from
the Apicalypse API)

```php
use MarcReichel\IGDBLaravel\Models\Game;
Expand Down Expand Up @@ -126,8 +130,8 @@ use MarcReichel\IGDBLaravel\Models\Game;
$games = Game::where('first_release_date', '>=', 1546297200)->get();
```

For convenience, if you want to verify that a column is equal to a given value,
you may pass the value directly as the second argument to the `where` method:
For convenience, if you want to verify that a column is equal to a given value, you may pass the value directly as the
second argument to the `where` method:

```php
use MarcReichel\IGDBLaravel\Models\Game;
Expand All @@ -137,8 +141,8 @@ $games = Game::where('name', 'Fortnite')->get();

##### Or Statements

You may chain where constraints together as well as add `or` clauses to the query.
The `orWhere` method accepts the same arguments as the `where` method:
You may chain where constraints together as well as add `or` clauses to the query. The `orWhere` method accepts the same
arguments as the `where` method:

```php
use MarcReichel\IGDBLaravel\Models\Game;
Expand All @@ -160,8 +164,7 @@ $games = Game::whereBetween('first_release_date', 1546297200, 1577833199)->get()

###### whereNotBetween

The `whereNotBetween` method verifies that a field's value lies outside of two
values:
The `whereNotBetween` method verifies that a field's value lies outside of two values:

```php
use MarcReichel\IGDBLaravel\Models\Game;
Expand All @@ -171,8 +174,7 @@ $games = Game::whereNotBetween('first_release_date', 1546297200, 1577833199)->ge

###### whereIn

The `whereIn` method verifies that a given field's value is contained within the
given array:
The `whereIn` method verifies that a given field's value is contained within the given array:

```php
use MarcReichel\IGDBLaravel\Models\Game;
Expand All @@ -182,7 +184,7 @@ $games = Game::whereIn('category', [0,4])->get();

###### whereNotIn

The `whereNotIn` method verifies that the given field's value is **not**
The `whereNotIn` method verifies that the given field's value is **not**
contained in the given array:

```php
Expand All @@ -193,7 +195,7 @@ $games = Game::whereNotIn('category', [0,4])->get();

###### whereInAll / whereNotInAll / whereInExact / whereNotInExact

Alternatively you could use one of these methods to match against **all** or **exactly** the given array.
Alternatively you could use one of these methods to match against **all** or **exactly** the given array.

###### whereNull

Expand Down Expand Up @@ -227,8 +229,7 @@ $games = Game::whereDate('first_release_date', '2019-01-01')->get();

###### whereYear

The `whereYear` method may be used to compare a fields's value against a specific
year:
The `whereYear` method may be used to compare a fields's value against a specific year:

```php
use MarcReichel\IGDBLaravel\Models\Game;
Expand All @@ -238,8 +239,7 @@ $games = Game::whereYear('first_release_date', 2019)->get();

###### whereHas / whereHasNot

These methods have the same syntax as `whereNull` and `whereNotNull` and literally
do the exact same thing.
These methods have the same syntax as `whereNull` and `whereNotNull` and literally do the exact same thing.

##### Parameter Grouping

Expand All @@ -253,13 +253,13 @@ $games = Game::where('name', 'Fortnite')
})->get();
```

#### Ordering, Limit, & Offset
#### Ordering, Limit & Offset

##### orderBy

The `orderBy` method allows you to sort the result of the query by a given field.
The first argument to the `orderBy` method should be the field you wish to sort
by, while the second argument controls the direction of the sort and may be either
The `orderBy` method allows you to sort the result of the query by a given field. The first argument to the `orderBy`
method should be the field you wish to sort by, while the second argument controls the direction of the sort and may be
either
`asc` or `desc`:

```php
Expand All @@ -270,8 +270,8 @@ $games = Game::orderBy('first_release_date', 'asc')->get();

##### skip / take

To limit the number of results returned from the query, or to skip a given
number of results in the query, you may use the `skip` and `take` methods (`take` is limited to a maximum of 500):
To limit the number of results returned from the query, or to skip a given number of results in the query, you may use
the `skip` and `take` methods (`take` is limited to a maximum of 500):

```php
use MarcReichel\IGDBLaravel\Models\Game;
Expand All @@ -289,8 +289,7 @@ $games = Game::offset(10)->limit(5)->get();

#### Cache

You can overwrite the default cache time for one specific query. So you can for
example turn off caching for a query:
You can overwrite the default cache time for one specific query. So you can for example turn off caching for a query:

```php
use MarcReichel\IGDBLaravel\Models\Game;
Expand Down Expand Up @@ -331,8 +330,7 @@ $game = Game::first();

#### Find

If you know the Identifier of the model you can simply call the `find`-method
with the identifier as a parameter:
If you know the Identifier of the model you can simply call the `find`-method with the identifier as a parameter:

```php
use MarcReichel\IGDBLaravel\Models\Game;
Expand All @@ -342,10 +340,9 @@ $game = Game::find(1905);

##### FindOrFail

`find` returns `null` if no result were found. If you want to throw an Exception
instead use `findOrFail`. This will throw an
`MarcReichel\IGDBLaravel\Exceptions\ModelNotFoundException` if no result were
found.
`find` returns `null` if no result were found. If you want to throw an Exception instead use `findOrFail`. This will
throw an
`MarcReichel\IGDBLaravel\Exceptions\ModelNotFoundException` if no result were found.

#### Relationships (Extends)

Expand All @@ -357,9 +354,8 @@ use MarcReichel\IGDBLaravel\Models\Game;
$game = Game::with(['cover', 'artworks'])->get();
```

By default, every field (`*`) of the relationship is selected.
If you want to define the fields of the relationship yourself you have to define
the relationship as the array-key and the fields as an array:
By default, every field (`*`) of the relationship is selected. If you want to define the fields of the relationship
yourself you have to define the relationship as the array-key and the fields as an array:

```php
use MarcReichel\IGDBLaravel\Models\Game;
Expand Down Expand Up @@ -397,8 +393,7 @@ if ($game) {

#### Query-Builder-based approach

If you used the Query Builder itself you must check if a property exists
yourself.
If you used the Query Builder itself you must check if a property exists yourself.

## ✨ Webhooks (since v2.3.0)

Expand All @@ -408,15 +403,28 @@ Since version 2.3.0 of this package you can create webhooks and handle their req

#### Configuration

Inside your `config/igdb.php` file you need to have a `webhook_secret` of your choice like so (you only need to create this if you upgraded from a prior version of this package. New installations have this configured automatically):
Inside your `config/igdb.php` file you need to have a `webhook_path` and `webhook_secret` of your choice like so (you
only need to create this if you upgraded from a prior version of this package. New installations have this configured
automatically):

```php
return [
// ...
// Other configs
// ...

'webhook_secret' => env('IGDB_WEBHOOK_SECRET', null)

/*
* Path where the webhooks should be handled.
*/
'webhook_path' => 'igdb-webhook/handle',

/*
* The webhook secret.
*
* This needs to be a string of your choice in order to use the webhook
* functionality.
*/
'webhook_secret' => env('IGDB_WEBHOOK_SECRET', null),
];
```

Expand All @@ -426,35 +434,6 @@ And then set a secret inside your `.env` file:
IGDB_WEBHOOK_SECRET=yoursecret
```

#### Routing

Create a POST route where you want to handle the incoming webhook requests and simply call `Webhook::handle($request)`:

```php
use Illuminate\Http\Request;
use MarcReichel\IGDBLaravel\Models\Webhook;

Route::post('webhook/handle', function (Request $request) {
return Webhook::handle($request);
})->name('handle-webhook');
```

Add the route to the `VerifyCsrfToken` middleware (in `app/Http/Middleware/VerifyCsrfToken.php`):

```diff
class VerifyCsrfToken extends Middleware
{
/**
* The URIs that should be excluded from CSRF verification.
*
* @var array
*/
protected $except = [
+ 'webhook/handle'
];
}
```

That's it!

### Creating a webhook
Expand All @@ -463,25 +442,28 @@ Let's say we want to be informed whenever a new game is created on https://igdb.

First of all we need to inform IGDB that we want to be informed.

For this we create a webhook like so:
For this we create a webhook like so (for example inside a controller):

```php
use MarcReichel\IGDBLaravel\Enums\Webhook\Method;
use MarcReichel\IGDBLaravel\Models\Game;
use Illuminate\Routing\Controller;

Game::createWebhook(route('handle-webhook'), 'create');
class ExampleController extends Controller
{
public function createWebhook()
{
Game::createWebhook(Method::CREATE)
}
}
```

The first parameter describes the route where we want to handle the webhook.
The second parameter needs to be one of `create`, `update` or `delete` according to
which event we want to listen for.

### Listen for events

Now that we have created our webhook we can listen for a specific event - in our case
when a game is created.
Now that we have created our webhook we can listen for a specific event - in our case when a game is created.

For this we create a Laravel EventListener or for sake of simplicity we just listen for an event
inside the `boot()` method of our `app/providers/EventServiceProvider.php`:
For this we create a Laravel EventListener or for sake of simplicity we just listen for an event inside the `boot()`
method of our `app/providers/EventServiceProvider.php`:

```php
use MarcReichel\IGDBLaravel\Events\GameCreated;
Expand All @@ -490,14 +472,52 @@ use Illuminate\Support\Facades\Event;
public function boot()
{
Event::listen(function (GameCreated $event) {
// $event->game holds the game data
// $event->data holds the (unexpanded!) data (of the game in this case)
});
}
```

[Here](src/Events) you can find a list of all available events.

Further information on how to set up event listeners can be found on the [official docs](https://laravel.com/docs/events).
Further information on how to set up event listeners can be found on
the [official docs](https://laravel.com/docs/events).

### Manage webhooks via CLI

#### List your webhooks

```bash
$ php artisan igdb:webhooks
```

#### Create a webhook

```bash
$ php artisan igdb:webhooks:create {model?} {--method=}
```

You can also just call `php artisan igdb:webhooks:create` without any arguments. The command will then ask for the
required data interactively.

The `model` parameter needs to be the (studly cased) class name of a model (e.g. `Game`).

The `--method` option needs to be one of `create`, `update` or `delete` accordingly for which event you want to listen.

#### Reactivate a webhook

```bash
$ php artisan igdb:webhooks:reactivate {id}
```

For `{id}` insert the id of the (inactive) webhook.

#### Delete a webhook

```bash
$ php artisan igdb:webhooks:delete {id?} {--A|all}
```

You may provide the `id` of a webhook to delete it or use the `-A`/`--all` flag to delete all your registered webhooks.

## Testing

Expand Down
2 changes: 1 addition & 1 deletion composer.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
],
"type": "library",
"require": {
"php": "^7.3 | ^7.4 | ^8.0",
"php": "^8.0",
"laravel/framework": "^8.40.0",
"guzzlehttp/guzzle": "~6.0|~7.0",
"ext-json": "*"
Expand Down
Loading

0 comments on commit fd80fce

Please sign in to comment.