8000 Merge tag 'v0.11.2' into develop · CodingSeo/laravel-json-api@2cd6089 · GitHub
[go: up one dir, main page]
Skip to content

Commit 2cd6089

Browse files
lindyhopchrislindyhopchris
committed
Merge tag 'v0.11.2' into develop
Update status code assertion and allow host to not be added to encoded URLs.
2 parents 5f2347e + 6ea8203 commit 2cd6089

File tree

15 files changed

+573
-57
lines changed

15 files changed

+573
-57
lines changed

‎CHANGELOG.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,19 @@
22
All notable changes to this project will be documented in this file. This project adheres to
33
[Semantic Versioning](http://semver.org/) and [this changelog format](http://keepachangelog.com/).
44

5+
## [0.11.2] - 2017-11-14
6+
7+
### Added
8+
- The host can now be omitted from encoded URLs if needed.
9+
10+
### Changed
11+
- The test response `assertStatus` method now outputs the error messages if the response status is
12+
unexpected and the response has JSON API errors in it. This restores a the behaviour that was present
13+
in `v0.10`.
14+
15+
### Fixed
16+
- Corrected invalid import statement in abstract hydrator stub.
17+
518
## [0.11.1] - 2017-09-26
619

720
### Fixed

‎docs/api.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -134,12 +134,14 @@ register routes for your API.
134134

135135
### Host
136136

137-
When processing inbound HTTP requests, the current server host will always be used when encoding JSON API documents.
137+
When processing inbound HTTP requests, the current server host will be used when encoding JSON API documents.
138138

139139
When encoding JSON API documents outside of HTTP requests, we use the `url.host` option from your API's configuration.
140140
If the value is `null`, we default to Laravel's `app.url` config setting. Otherwise, we'll use the value you've
141141
provided.
142142

143+
If you do not want the host to be appended to URLs in the encoded document, set `url.host` to `false`.
144+
143145
### Namespace
144146

145147
The URL namespace is the URL under which all resources for the API are nested. For example, if the namespace is

‎docs/custom/controllers.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,6 @@ controller:
141 1E79 141
2. `readRelationship()`
142142

143143
### Read Related Resource
144-
145144
If you link one resource to another through relationship, you'll need this to read the related resource.
146145

147146
```php

‎docs/features/custom-errors.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Custom Errors
2+
3+
## Introduction
4+
5+
This package allows you to return [JSON API error objects](http://jsonapi.org/format/1.0/#error-objects) which can include various information about what went wrong.
6+
7+
## Custom Errors In Controllers
8+
9+
This is particularly useful for errors that you have to manually present to the user through the controller. In order to magically return errors, you would need to use the `ErrorsAwareTrait`.
10+
11+
12+
Below is an example of a scenario which a user fails to login due to incorrect credentials.
13+
14+
```php
15+
namespace App\Http\Controllers\Api\V1;
16+
17+
use CloudCreativity\JsonApi\Contracts\Http\Requests\RequestInterface as JsonApiRequest;
18+
use CloudCreativity\JsonApi\Document\Error;
19+
20+
class JsonWebTokensController extends Controller
21+
{
22+
protected function guard()
23+
{
24+
return Auth::guard('jwt');
25+
}
26+
27+
public function create(JsonApiRequest $request)
28+
{
29+
$resource_attributes = $request->getDocument()->getResource()->getAttributes();
30+
$credentials = [
31+
'email' => $resource_attributes->email,
32+
'password' => $resource_attributes->password,
33+
];
34+
35+
if ($this->guard()->attempt($credentials)) {
36+
// Success!
37+
} else {
38+
// Incorrect login details
39+
return $this->reply()->errors(Error::create([
40+
'status' => 422,
41+
'title' => 'Login failed.',
42+
'detail' => 'These credentials do not match our records.'
43+
]));
44+
45+
}
46+
}
47+
}
48+
```
49+
50+
And the response given would be the following:
51+
52+
```json
53+
{
54+
"errors": [
55+
{
56+
"status": "422",
57+
"title": "Login failed.",
58+
"detail": "These credentials do not match our records."
59+
}
60+
]
61+
}
62+
```

‎docs/features/inclusion.md

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Inclusion
2+
3+
## Introduction
4+
5+
This package supports the specification of [JSON API Inclusion of Related Resources](http://jsonapi.org/format/1.0/#fetching-includes). This allows you to load all the data of the specified resources that is bounded by relationship.
6+
7+
### Using Include Parameter
8+
9+
Per the specification, the client is able to request for the inclusion of related resources through the following HTTP request:
10+
11+
```http
12+
GET /api/posts?include=comments HTTP/2.0
13+
Accept: application/vnd.api+json
14+
```
15+
16+
However, by default, this package denies inclusion of related resources via parameter and would throw the follow error message.
17+
18+
```json
19+
{
20+
"errors": [
21+
{
22+
"title": "Include paths should contain only allowed ones.",
23+
"source": {
24+
"parameter": "include"
25+
}
26+
}
27+
]
28+
}
29+
30+
```
31+
32+
To allow certain resources to be included using request parameters, it must be manually enabled through the resource's `Validators.php` file.
33+
34+
```php
35+
namespace App\JsonApiV1\Posts;
36+
37+
class Validators extends AbstractValidatorProvider
38+
{
39+
protected $allowedIncludePaths = [
40+
'comments'
41+
];
42+
43+
/* Your code here ...*/
44+
}
45+
```
46+
47+
48+
### Auto Inclusion
49+
50+
It is possible to force the inclusion of certain related resources; displaying it even when the client did not specify the related resource in the include parameter. To enable the automatic inclusion of resources, edit the resource's `Schema.php` file.
51+
52+
```php
53+
namespace App\JsonApiV1\Posts;
54+
55+
class Schema extends EloquentSchema
56+
{
57+
58+
/* Your code here ...*/
59+
60+
public function getIncludePaths()
61+
{
62+
return [
63+
'comments'
64+
];
65+
}
66+
}
67+
```
68+
69+
And when the client sends the following request:
70+
71+
```http
72+
GET /api/posts HTTP/2.0
73+
Accept: application/vnd.api+json
74+
```
75+
76+
The response would look something like this:
77+
78+
```json
79+
{
80+
"data": [
81+
{
82+
"type": "posts",
83+
"id": "6118bf58-7374-4e9a-9843-d1b0e53ac0b9",
84+
"attributes": {
85+
"created-at": "2017-10-14T07:56:44+00:00",
86+
"updated-at": "2017-10-14T07:56:44+00:00",
87+
"title": "Bernadine McClure",
88+
"description": "Provident recusandae est rem consequatur. Et alias ut culpa architecto eligendi et temporibus. Aliquam ipsa vitae mollitia totam fuga."
89+
},
90+
"relationships": {
91+
"comments": {
92+
"data": [
93+
{
94+
"type": "comments",
95+
"id": "3813a5ba-3d7b-432d-aa0d-eb0c3bd4e1a1"
96+
},
97+
{
98+
"type": "comments",
99+
"id": "bb3dd8a2-8678-480e-b477-87c8fddc5702"
100+
}
101+
],
102+
"meta": {
103+
"total": 2
104+
},
105+
"links": {
106+
"self": "http://localhost:8000/api/v1/posts/6118bf58-7374-4e9a-9843-d1b0e53ac0b9/relationships/comments",
107+
"related": "http://localhost:8000/api/v1/posts/6118bf58-7374-4e9a-9843-d1b0e53ac0b9/comments"
108+
}
109+
}
110+
},
111+
"links": {
112+
"self": "http://localhost:8000/api/v1/posts/6118bf58-7374-4e9a-9843-d1b0e53ac0b9"
113+
}
114+
}
115+
],
116+
"included": [
117+
{
118+
"type": "comments",
119+
"id": "3813a5ba-3d7b-432d-aa0d-eb0c3bd4e1a1",
120+
"attributes": {
121+
"created-at": "2017-10-14T09:47:09+00:00",
122+
"updated-at": "2017-10-14T09:47:09+00:00",
123+
"description": "Excellent post!"
124+
},
125+
"relationships": {
126+
"post": {
127+
"data": {
128+
"type": "posts",
129+
"id": "6118bf58-7374-4e9a-9843-d1b0e53ac0b9"
130+
},
131+
"links": {
132+
"self": "http://localhost:8000/api/v1/comments/3813a5ba-3d7b-432d-aa0d-eb0c3bd4e1a1/relationships/post",
133+
"related": "http://localhost:8000/api/v1/comments/3813a5ba-3d7b-432d-aa0d-eb0c3bd4e1a1/post"
134+
}
135+
}
136+
}
137+
},
138+
{
139+
"type": "comments",
140+
"id": "bb3dd8a2-8678-480e-b477-87c8fddc5702",
141+
"attributes": {
142+
"created-at": "2017-10-14T07:57:52+00:00",
143+
"updated-at": "2017-10-14T07:57:52+00:00",
144+
"description": "I really like your post!"
145+
},
146+
"relationships": {
147+
"post": {
148+
"data": {
149+
"type": "posts",
150+
"id": "6118bf58-7374-4e9a-9843-d1b0e53ac0b9"
151+
},
152+
"links": {
153+
"self": "http://localhost:8000/api/v1/comments/bb3dd8a2-8678-480e-b477-87c8fddc5702/relationships/post",
154+
"related": "http://localhost:8000/api/v1/comments/bb3dd8a2-8678-480e-b477-87c8fddc5702/post"
155+
}
156+
}
157+
}
158+
}
159+
]
160+
}
161+
162+
```

‎mkdocs.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ pages:
1616
- Non-Eloquent:
1717
- Controllers: custom/controllers.md
1818
- Digging Deeper:
19+
- Inclusion: features/inclusion.md
20+
- Custom Errors: features/custom-errors.md
1921
- Broadcasting: features/broadcasting.md
2022
- Helpers: features/helpers.md
2123
- HTTP Clients: features/http-clients.md

‎src/Api/Repository.php

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -165,16 +165,16 @@ private function normalizeRootNamespace($namespace)
165165
*/
166166
private function normalizeUrl(array $url, $host = null)
167167
{
168+
$prependHost = false !== array_get($url, 'host');
169+
168170
if ($host) {
169171
$url['host'] = $host;
170-
}
171-
172-
if (!array_get($url, 'host')) {
172+
} elseif (!isset($url['host'])) {
173173
$url['host'] = $this->config->get('app.url');
174174
}
175175

176176
return new Url(
177-
(string) $url['host'],
177+
$prependHost ? (string) $url['host'] : '',
178178
(string) array_get($url, 'namespace'),
179179
(string) array_get($url, 'name')
180180
);

‎src/Testing/TestResponse.php

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
use Illuminate\Support\Collection;
1313
use Neomerx\JsonApi\Contracts\Document\DocumentInterface as Keys;
1414
use Neomerx\JsonApi\Contracts\Http\Headers\MediaTypeInterface;
15+
use PHPUnit\Framework\Assert as PHPUnit;
1516
use RuntimeException;
1617

1718
class TestResponse extends BaseTestResponse
@@ -56,6 +57,26 @@ public function assertJsonApiResponse(
5657
return $this;
5758
}
5859

60+
/**
61+
* Assert that the response has the given status code.
62+
*
63+
* @param int $status
64+
* @return $this
65+
*/
66+
public function assertStatus($status)
67+
{
68+
$actual = $this->getStatusCode();
69+
$message = "Expected status code {$status} but received {$actual}";
70+
$content = (array) json_decode((string) $this->getContent(), true);
71+
if (isset($content[Keys::KEYWORD_ERRORS])) {
72+
$message .= " with errors:\n" . json_encode($content, JSON_PRETTY_PRINT);
73+
}
74+
75+
PHPUnit::assertSame($status, $actual, $message);
76+
77+
return $this;
78+
}
79+
5980
/**
6081
* Assert a response with a singular resource in the `data` member.
6182
*

‎stubs/abstract/hydrator.stub

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,9 @@
33
namespace DummyNamespace;
44

55
use CloudCreativity\JsonApi\Contracts\Hydrator\HydratesRelatedInterface;
6-
use CloudCreativity\JsonApi\Contracts\Object\StandardObjectInterface;
76
use CloudCreativity\JsonApi\Hydrator\AbstractHydrator;
87
use CloudCreativity\JsonApi\Hydrator\RelatedHydratorTrait;
8+
use CloudCreativity\Utils\Object\StandardObjectInterface;
99

1010
class Hydrator extends AbstractHydrator implements HydratesRelatedInterface
1111
{

‎stubs/api.php

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,8 @@
6767
| detected from the inbound HTTP request. In other circumstances
6868
| (e.g. broadcasting), the host will be taken from the setting here.
6969
| If it is `null`, the `app.url` config setting is used as the default.
70+
| If you set `host` to `false`, the host will never be appended to URLs
71+
| for inbound requests.
7072
|
7173
| The name setting is the prefix for route names within this API.
7274
|

‎tests/Integration/BroadcastingTest.php

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,5 @@ public function testBroadcastWith()
1515

1616
$this->assertSame('posts', array_get($data, 'data.type'));
1717
$this->assertEquals($id = $post->getKey(), array_get($data, 'data.id'));
18-
$this->assertEquals("http://localhost/api/v1/posts/$id", array_get($data, 'data.links.self'));
1918
}
2019
}

0 commit comments

Comments
 (0)
0