10000 Merge branch 'master' into develop · martynling/laravel-json-api@a269b16 · GitHub
[go: up one dir, main page]
Skip to content

Commit a269b16

Browse files
lindyhopchrislindyhopchris
committed
Merge branch 'master' into develop
2 parents 14f1d43 + be8fed9 commit a269b16

File tree

3 files changed

+203
-0
lines changed

3 files changed

+203
-0
lines changed

‎docs/custom/controllers.md

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
# Controllers
2+
3+
This chapter describes how to implement your own controller for processing JSON API requests and returning JSON API
4+
responses.
5+
6+
## Setup
7+
8+
In order to send JSON API responses, you will need to apply the `ReplyTrait` to your controller. If your resource
9+
has a hydrator, you can also inject it via the constructor.
10+
11+
Here is an example controller:
12+
13+
```php
14+
namespace App\Http\Controllers\Api;
15+
16+
use App\JsonApi\Users;
17+
use CloudCreativity\LaravelJsonApi\Http\Responses\ReplyTrait;
18+
use Illuminate\Routing\Controller;
19+
20+
class UsersController extends Controller
21+
{
22+
23+
use ReplyTrait;
24+
25+
private $hydrator;
26+
27+
public function __construct(Users\Hydrator $hydrator)
28+
{
29+
$this->hydrator = $hydrator;
30+
}
31+
32+
// Methods as per below...
33+
}
34+
```
35+
36+
## Resource Actions
37+
38+
As described in the [routing](../routing.md) chapter, there are five resource actions for which you need to implement
39+
methods:
40+
41+
1. `index()`
42+
2. `create()`
43+
3. `read()`
44+
4. `update()`
45+
5. `delete()`
46+
47+
They are able to accept a few parameters and must make use of the reply trait to return a response.
48+
49+
The following are examples covering these functions. Do take note that you will need to import the namespaces
50+
correctly.
51+
52+
### Index
53+
54+
```php
55+
/**
56+
* @param \CloudCreativity\JsonApi\Contracts\Http\ApiInterface $api
57+
* @param \CloudCreativity\JsonApi\Contracts\Http\Requests\RequestInterface $request
58+
* @return \Illuminate\Http\Response
59+
*/
60+
public function index(ApiInterface $api, RequestInterface $request)
61+
{
62+
$result = $api->getStore()->query(
63+
$request->getResourceType(),
64+
$request->getParameters()
65+
);
66+
67+
return $this->reply()->content($result);
68+
}
69+
```
70+
71+
### Create
72+
73+
```php
74+
/**
75+
* @param \CloudCreativity\JsonApi\Contracts\Http\Requests\RequestInterface $request
76+
* @return \Illuminate\Http\Response
77+
*/
78+
public function create(RequestInterface $request)
79+
{
80+
$resource = $request->getDocument()->getResource();
81+
// As an example, if we wanted to wrap the change in a transaction...
82+
$record = \DB::transaction(function () use ($resource, $request) {
83+
$record = new User();
84+
$this->hydrator->hydrate($request->getDocument()->getResource(), $record);
85+
$record->save();
86+
87+
return $record;
88+
});
89+
90+
return $this->reply()->created($record);
91+
}
92+
```
93+
94+
### Read
95+
96+
```php
97+
/**
98+
* @param \CloudCreativity\JsonApi\Contracts\Http\Requests\RequestInterface $request
99+
* @return \Illuminate\Http\Response
100+
*/
101+
public function read(RequestInterface $request)
102+
{
103+
return $this->reply()->content($request->getRecord());
104+
}
105+
```
106+
### Update
107+
108+
```php
109+
/**
110+
* @param \CloudCreativity\JsonApi\Contracts\Http\Requests\RequestInterface $request
111+
* @return \Illuminate\Http\Response
112+
*/
113+
public function update(RequestInterface $request)
114+
{
115+
/** @var User $record */
116+
$record = $request->getRecord();
117+
$resource = $request->getDocument()->getResource();
118+
$this->hydrator->hydrate($resource, $record);
119+
$passwordChanged = $record->hasPasswordChanged();
120+
$record->save();
121+
122+
// for example, if we wanted to fire an event...
123+
if ($passwordChanged) {
124+
event(new UserChangedPassword($record));
125+
}
126+
127+
return $this->reply()->content($record);
128+
}
129+
```
130+
131+
### Delete
132+
133+
```php
134+
/**
135+
* @param \CloudCreativity\JsonApi\Contracts\Http\Requests\RequestInterface $request
136+
* @return \Illuminate\Http\Response
137+
*/
138+
public function delete(RequestInterface $request)
139+
{
140+
/** @var User $record */
141+
$record = $request->getRecord();
142+
$record->delete();
143+
144+
return $this->reply()->noContent();
145+
}
146+
```
147+
148+
## Relationships
149+
150+
If you have defined relationships in the schema of a resource, you would then need to add the following actions to your
151+
controller:
152+
153+
1. `readRelatedResource()`
154+
2. `readRelationship()`
155+
156+
### Read Related Resource
157+
158+
If you link one resource to another through relationship, you'll need this to read the related resource.
159+
160+
```php
161+
/**
162+
* @param \CloudCreativity\JsonApi\Contracts\Http\Requests\RequestInterface $request
163+
* @return \Illuminate\Http\Response
164+
*/
165+
public function readRelatedResource(RequestInterface $request)
166+
{
167+
$record = $request->getRecord();
168+
$key = $request->getRelationshipName();
169+
$method = 'get' . ucfirst($key);
170+
171+
return $this
172+
->reply()
173+
->content(call_user_func([$record, $method]));
174+
}
175+
```
176+
177+
### Read Relationship
178+
179+
This is for reading the relationship between two resources.
180+
181+
```php
182+
/**
183+
* @param \CloudCreativity\JsonApi\Contracts\Http\Requests\RequestInterface $request
184+
* @return \Illuminate\Http\Response
185+
*/
186+
public function readRelationship(RequestInterface $request)
187+
{
188+
$record = $request->getRecord();
189+
$key = $request->getRelationshipName();
190+
$method = 'get' . ucfirst($key);
191+
192+
return $this
193+
->reply()
194+
->relationship(call_user_func([$record, $method]));
195+
}
196+
```

‎docs/eloquent/controllers.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Eloquent Controllers
2+
3+
@todo

‎mkdocs.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,7 @@ pages:
99
- Installation: installation.md
1010
- API Setup: api.md
1111
- Routing: routing.md
12+
- Eloquent:
13+
- Controllers: eloquent/controllers.md
14+
- Non-Eloquent:
15+
- Controllers: custom/controllers.md

0 commit comments

Comments
 (0)
0