8000 [Feature] Add links generator and remove links factory · startupengine/laravel-json-api@48fb88f · GitHub
[go: up one dir, main page]
Skip to content

Commit 48fb88f

Browse files
lindyhopchrislindyhopchris
committed
[Feature] Add links generator and remove links factory
The new links generator uses the URL generator from an API. As part of this refactoring, it was possible to extract page generation from the standard paging strategy into a `CreatesPages` trait. Also added initial pagination feature tests.
1 parent 2fd6b75 commit 48fb88f

23 files changed

+898
-778
lines changed

‎CHANGELOG.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,9 @@ a `use` statement.
2626
- Fixed merging API resources objects.
2727

2828
### Removed
29-
- This package no longer supports Laravel 5.3
29+
- This package no longer supports Laravel 5.3.
30+
- The `Document\GeneratesLink` trait was removed.
31+
- The `Document\LinkFactory` was removed and the API `links()` helper must be used instead.
3032

3133
## [0.9.1] - 2017-06-26
3234

‎docs/features/helpers.md

Lines changed: 65 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@
55
Laravel provides a number of global [helper PHP functions](https://laravel.com/docs/helpers). This package
66
provides some additional helpers that allow you to manually use capabilities within the package.
77

8+
Helpers are either *global* (like Laravel's helpers) or scoped to a specific API. The latter we refer to as
9+
*API helpers*.
10+
811
## Global Helpers
912

1013
### `json_api()`
@@ -35,6 +38,16 @@ This will return the JSON API request instance, or `null` if there is no inbound
3538

3639
The following helpers methods are available on the API instances.
3740

41+
### `client()`
42+
43+
This helper returns a HTTP client for [sending JSON API requests](./http-clients/) to remote servers. You
44+
must provide a Guzzle client as the first argument:
45+
46+
```php
47+
$guzzleClient = new GuzzleHttp\Client(['base_uri' => 'http://example.com/api/']);
48+
$client = json_api('v1')->client($guzzleClient);
49+
```
50+
3851
### `encoder()`
3952

4053
Gets an encoder that is configured with the API's details. This can be used to manually serialize data to arrays, or
@@ -55,12 +68,59 @@ depth arguments in PHP's native `json_encode()` method.
5568
echo json_api('v1')->encoder(JSON_PRETTY_PRINT)->encodeData($post);
5669
```
5770

58-
### `client()`
71+
### `links()`
5972

60-
This helper returns a HTTP client for [sending JSON API requests](./http-clients/) to remote servers. You
61-
must provide a Guzzle client as the first argument:
73+
This helper returns a generator that allows you to create JSON API link objects for URLs in your API. For example:
6274

6375
```php
64-
$guzzleClient = new GuzzleHttp\Client(['base_uri' => 'http://example.com/api/']);
65-
$client = json_api('v1')->client($guzzleClient);
76+
/** @var \Neomerx\JsonApi\Contracts\Document\LinkInterface $link */
77+
$link = json_api('v1')->links()->index('posts');
78+
$meta = ['foo' => 'bar'];
79+
$link = json_api('v1)->links()->index('posts', $meta);
6680
```
81+
82+
The following methods on the links generator create links for resources within your API:
83+
84+
- `index($type, $meta)`
85+
- `create($type, $meta)`
86+
- `read($type, $id, $meta)`
87+
- `update($type, $id, $meta)`
88+
- `delete($type, $id, $meta)`
89+
- `relatedResource($type, $id, $relationship, $meta)`
90+
- `readRelationship($type, $id, $relationship, $meta)`
91+
- `replaceRelationship($type, $id, $relationship, $meta)`
92+
- `addRelationship($type, $id, $relationship, $meta)`
93+
- `removeRelationship($type, $id, $relationship, $meta)`
94+
95+
> In all of these methods, `$meta` is an optional argument.
96+
97+
All these methods take an additional optional argument - an array of parameters. Use this if you need to pass
98+
additional parameters that are required when generating the URLs within the link objects.
99+
100+
### `url()`
101+
102+
This helper returns a URL generator for the API, which makes it easy to generate string links to resources within
103+
the API. For example:
104+
105+
```php
106+
// http://localhost/api/v1/posts
107+
$url = json_api('v1')->url()->index('posts');
108+
// http://localhost/api/posts/1
109+
$url = json_api('v1')->url()->read('posts', 1);
110+
```
111+
112+
The available methods on the URL generator are as follows:
113+
114+
- `index($type)`
115+
- `create($type)`
116+
- `read($type, $id)`
117+
- `update($type, $id)`
118+
- `delete($type, $id)`
119+
- `relatedResource($type, $id, $relationship)`
120+
- `readRelationship($type, $id, $relationship)`
121+
- `replaceRelationship($type, $id, $relationship)`
122+
- `addRelationship($type, $id, $relationship)`
123+
- `removeRelationship($type, $id, $relationship)`
124+
125+
All these methods take an additional optional argument - an array of parameters. Use this if you need to pass
126+
additional parameters that are required when generating the URLs.

‎docs/features/pagination.md

Lines changed: 8 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -102,22 +102,19 @@ class Adapter extends EloquentAdapter
102102

103103
### Default Customisation
104104

105-
If you want to override the defaults for many resource types, bind a strategy to your service container in
106-
your `AppServiceProvider`:
105+
If you want to override the defaults for many resource types, then you can extend the standard strategy and inject
106+
your child class into your adapters. For example:
107107

108108
```php
109109
use CloudCreativity\LaravelJsonApi\Pagination\StandardStrategy;
110110

111-
class AppServiceProvider extends ServiceProvider
111+
class CustomStrategy extends StandardStrategy
112112
{
113113

114-
public function register()
114+
public function __construct()
115115
{
116-
$this->app->bind('my-paging-strategy', function ($app) {
117-
$strategy = $app->make(StandardStrategy::class);
118-
$strategy->withPageKey('page')->withPerPageKey('limit');
119-
return $strategy;
120-
});
116+
parent::__construct();
117+
$this->withPageKey('page')->withPerPageKey('limit');
121118
}
122119
}
123120
```
@@ -128,9 +125,9 @@ Then in your adapter:
128125
class Adapter extends EloquentAdapter
129126
{
130127

131-
public function __construct()
128+
public function __construct(CustomStrategy $paging)
132129
{
133-
parent::__construct(new Post(), app('my-paging-strategy'));
130+
parent::__construct(new Post(), $paging);
134131
}
135132

136133
// ...
@@ -297,9 +294,6 @@ class DateRangeStrategy implements PagingStrategyInterface
297294

298295
We recommend you look through the code for our `StandardStrategy` to see how to implement a strategy.
299296

300-
> We plan to extract as much as the functionality of the `StandardStrategy` as possible into traits, but have not
301-
got to this yet. If you are writing your own strategy and feel like submitting a PR, that would be great!
302-
303297
You can then inject your new strategy into your adapters as follows:
304298

305299
```php

‎src/Api/Api.php

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -342,6 +342,14 @@ public function url()
342342
return $this->factory->createUrlGenerator($this->url);
343343
}
344344

345+
/**
346+
* @return LinkGenerator
347+
*/
348+
public function links()
349+
{
350+
return $this->factory->createLinkGenerator($this->url());
351+
}
352+
345353
/**
346354
* @return ValidatorFactoryInterface
347355
*/

0 commit comments

Comments
 (0)
0