8000 [Refactor] Update package to use camel-case field names (#530) · CodingSeo/laravel-json-api@239db6e · GitHub
[go: up one dir, main page]
Skip to content

Commit 239db6e

Browse files
lindyhopchrislindyhopchris
authored
[Refactor] Update package to use camel-case field names (cloudcreativity#530)
Switch package to using camel-case as default JSON API member names. Refer to upgrade guide for change affecting the soft deletes trait. Closes cloudcreativity#393
1 parent f0f9ec6 commit 239db6e

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+416
-275
lines changed

‎CHANGELOG.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,15 @@
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+
## Unreleased
6+
7+
### Changed
8+
- [#393](https://github.com/cloudcreativity/laravel-json-api/issues/393)
9+
**BREAKING:** when using the `SoftDeletesModel` trait on an adapter, the expected JSON API field
10+
for the soft delete attribute now defaults to the camel-case version of the model column. For example,
11+
column `deleted_at` previously defaulted to the JSON API field `deleted-at`, whereas now it will
12+
default to `deletedAt`. To continue to use dash-case, set the `softDeleteField` property on your adapter.
13+
514
## [2.0.0] - 2020-06-17
615

716
### Added

‎composer.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@
6666
},
6767
"extra": {
6868
"branch-alias": {
69-
"dev-develop": "2.x-dev"
69+
"dev-develop": "3.x-dev"
7070
},
7171
"laravel": {
7272
"providers": [

‎docs/basics/adapters.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -103,21 +103,21 @@ If your resource supports client-generated ids, refer to the client-generated id
103103

104104
When filling a model with attributes received in a JSON API request, the adapter will convert the JSON API
105105
field name to either the snake case or camel case equivalent. For example, if your JSON API resource had
106-
an attribute field called `published-at`, this is mapped to `published_at` if your model uses snake case keys,
106+
an attribute field called `publishedAt`, this is mapped to `published_at` if your model uses snake case keys,
107107
or `publishedAt` if not.
108108

109109
> We work out whether your model uses snake case or camel case keys based on your model's `$snakeAttributes`
110110
static property.
111111

112112
If you have a JSON API field name that needs to map to a different model attribute, this can be defined in your
113-
adapter's `$attributes` property. For example, if the `published-at` field needed to be mapped to the
113+
adapter's `$attributes` property. For example, if the `publishedAt` field needed to be mapped to the
114114
`published_date` attribute on your model, it must be defined as follows:
115115

116116
```php
117117
class Adapter extends AbstractAdapter
118118
{
119119
protected $attributes = [
120-
'published-at' => 'published_date',
120+
'publishedAt' => 'published_date',
121121
];
122122

123123
// ...
@@ -132,25 +132,25 @@ you will protect any attributes that are not fillable using Eloquent's
132132

133133
There may be cases where an attribute is fillable on your model, but you do not want to allow your JSON API to
134134
fill it. You can set your adapter to skip attributes received from a client by listing the JSON API
135-
field name in the `$guarded` property on your adapter. For example, if we did not want the `published-at` field
135+
field name in the `$guarded` property on your adapter. For example, if we did not want the `publishedAt` field
136136
to be filled into our model, we would define it as follows:
137137

138138
```php
139139
class Adapter extends AbstractAdapter
140140
{
141-
protected $guarded = ['published-at'];
141+
protected $guarded = ['publishedAt'];
142142

143143
// ...
144144
}
145145
```
146146

147147
Alternatively, you can white-list JSON API fields that can be filled by adding them to the `$fillable` property
148-
on your adapter. For example, if we only wanted the `title`, `content` and `published-at` fields to be filled:
148+
on your adapter. For example, if we only wanted the `title`, `content` and `publishedAt` fields to be filled:
149149

150150
```php
151151
class Adapter extends AbstractAdapter
152152
{
153-
protected $fillable = ['title', 'content', 'published-at'];
153+
protected $fillable = ['title', 'content', 'publishedAt'];
154154

155155
// ...
156156
}
@@ -170,7 +170,7 @@ your adapter. For example:
170170
```php
171171
class Adapter extends AbstractAdapter
172172
{
173-
protected $dates = ['created-at', 'updated-at', 'published-at'];
173+
protected $dates = ['createdAt', 'updatedAt', 'publishedAt'];
174174

175175
// ...
176176
}

‎docs/basics/controllers.md

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -90,8 +90,8 @@ class PostsController extends JsonApiController
9090
9191
### Resource Hooks
9292

93-
The controller allows you to hook into the resource lifecycle by invoking the following methods if they are
94-
implemented. These methods allow you to easily implement application specific actions, such as firing events
93+
The controller allows you to hook into the resource lifecycle by invoking the following methods if they are
94+
implemented. These methods allow you to easily implement application specific actions, such as firing events
9595
or dispatching jobs.
9696

9797
| Hook | Arguments | Request Class |
@@ -106,12 +106,12 @@ or dispatching jobs.
106106
| `created` | record, request | `CreateResource` |
107107
| `saved` | record, request | `CreateResource` or `UpdateResource` |
108108
| `deleting` | record, request | `DeleteResource` |
109-
| `deleted` | record, request | `DeleteResource` |
109+
| `deleted` | record, request | `DeleteResource` |
110110

111111
> The request class is the validated request in the `CloudCreativity\LaravelJsonApi\Http\Requests` namespace.
112112
113113
The `searching`, `searched`, `reading` and `didRead` hooks are invoked when resource(s) are being accessed,
114-
i.e. a `GET` request. The `searching` and `searched` hooks are invoked when reading any resources
114+
i.e. a `GET` request. The `searching` and `searched` hooks are invoked when reading any resources
115115
(the *index* action), while `reading` and `didRead` are invoked when reading a specific record
116116
(the *read* action).
117117

@@ -158,7 +158,7 @@ if reading the `author` relationship on a `posts` resource, the `readingRelation
158158
methods will be invoked if they exist.
159159

160160
The `reading...` and `didRead...` methods are invoked when accessing the related resource or the relationship data,
161-
i.e. a `GET` relationship request. The `replacing...` and `replaced...` methods are invoked when changing the
161+
i.e. a `GET` relationship request. The `replacing...` and `replaced...` methods are invoked when changing the
162162
entire relationship in a `PATCH` relationship request.
163163

164164
For *to-many* relationships, the `adding...` and `added...` methods are invoked when adding resources to the
@@ -184,7 +184,7 @@ For example, if we wanted to send a `202 Accepted` response when a resource was
184184
protected function deleted($record)
185185
{
186186
return $this->reply()->meta([
187-
'accepted-at' => Carbon\Carbon::now()->toW3cString()
187+
'acceptedAt' => Carbon\Carbon::now(),
188188
], 202);
189189
}
190190
```
@@ -197,7 +197,7 @@ Content-Type: application/vnd.api+json
197197
198198
{
199199
"meta": {
200-
"accepted-at": "2018-04-10T11:56:52+00:00"
200+
"acceptedAt": "2018-04-10T11:56:52+00:00"
201201
}
202202
}
203203
```
@@ -224,11 +224,11 @@ use CloudCreativity\LaravelJsonApi\Http\Controllers\JsonApiController;
224224

225225
class PostsController extends JsonApiController
226226
{
227-
227+
228228
public function share(\App\Post $post): \Illuminate\Http\Response
229229
{
230230
\App\Jobs\SharePost::dispatch($post);
231-
231+
232232
return $this->reply()->content($post);
233233
}
234234
}
@@ -257,11 +257,11 @@ use CloudCreativity\LaravelJsonApi\Http\Requests\FetchResource;
257257

258258
class PostsController extends JsonApiController
259259
{
260-
260+
261261
public function share(FetchResource $request, \App\Post $post): \Illuminate\Http\Response
262262
{
263263
\App\Jobs\SharePost::dispatch($post);
264-
264+
265265
return $this->reply()->content($post);
266266
}
267267
}

‎docs/basics/schemas.md

Lines changed: 27 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ for this deprecated class can be found
1616

1717
## Defining Resources
1818

19-
Your API's configuration contains a list of resources that appear in its JSON API documents in its `resources` array.
19+
Your API's configuration contains a list of resources that appear in its JSON API documents in its `resources` array.
2020
This array maps the JSON API resource object `type` to the PHP class that it relates to. For example:
2121

2222
```php
@@ -29,7 +29,7 @@ This array maps the JSON API resource object `type` to the PHP class that it rel
2929
```
3030

3131
> You need to list **every** resource that can appear in a JSON API document in the `resources` configuration,
32-
even resources that do not have API routes defined for them. This is so that the JSON API encoder
32+
even resources that do not have API routes defined for them. This is so that the JSON API encoder
3333
can locate a schema for each PHP class it encounters.
3434

3535
## Creating Schemas
@@ -56,9 +56,9 @@ method implemented if it is for an Eloquent resource. For example:
5656
```php
5757
class Schema extends SchemaProvider
5858
{
59-
59+
6060
protected $resourceType = 'posts';
61-
61+
6262
/**
6363
* @param App\Post $resource
6464
* @return string
@@ -89,27 +89,27 @@ A resource object can contain an `attributes` object containing additional prope
8989
Attributes are returned by the `getAttributes()` method on your schema. If you have generated your schema,
9090
this method will already be implemented.
9191

92-
As an example, a schema for a `posts` resource could look like this:
92+
As an example, a schema for a `posts` resource could look like this:
9393

9494
```php
9595
class Schema extends SchemaProvider
9696
{
9797

9898
// ...
99-
99+
100100
/**
101101
* @param App\Post $post
102102
* @return array
103103
*/
104104
public function getAttributes($post)
105105
{
106106
return [
107-
'created-at' => $post->created_at->toW3cString(),
108-
'updated-at' => $post->updated_at->toW3cString(),
109-
'title' => $post->title,
107+
'createdAt' => $post->created_at,
110108
'content' => $post->content,
109+
'publishedAt' => $post->published_at,
111110
'slug' => $post->slug,
112-
'published-at' => $post->published_at ? $post->published_at->toW3cString() : null,
111+
'title' => $post->title,
112+
'updatedAt' => $post->updated_at,
113113
];
114114
}
115115
}
@@ -122,21 +122,21 @@ The above schema would result in the following resource object:
122122
"type": "posts",
123123
"id": "1",
124124
"attributes": {
125-
"created-at": "2018-01-01T11:00:00+00:00",
126-
"updated-at": "2018-01-01T12:10:00+00:00",
127-
"title": "My First Post",
125+
"createdAt": "2018-01-01T11:12:13.356234Z",
128126
"content": "...",
127+
"publishedAt": "2018-01-01T12:30:10.258250Z",
129128
"slug": "my-first-post",
130-
"published-at": "2018-01-01T12:00:00+00:00"
129+
"title": "My First Post",
130+
"updatedAt": "2018-01-01T12:30:10.258250Z"
131131
}
132132
}
133133
```
134134

135135
## Relationships
136136

137137
A resource object may have a `relationships` key that holds a relationships object. This object describes linkages
138-
to other resource objects. Relationships can either be to-one or to-many. The JSON API spec allows these linkages
139-
to be described in resource relationships in multiple ways - either through a `links`, `data` or `meta` value,
138+
to other resource objects. Relationships can either be to-one or to-many. The JSON API spec allows these linkages
139+
to be described in resource relationships in multiple ways - either through a `links`, `data` or `meta` value,
140140
or a combination of all three.
141141

142142
> It's worth mentioning again that every PHP class that could be returned as a related object must have a schema
@@ -157,9 +157,9 @@ For example, if our `App\Post` model has a `comments` relationship, its relation
157157
class Schema extends SchemaProvider
158158
{
159159
$resourceType = 'posts';
160-
160+
161161
// ...
162-
162+
163163
public function getRelationships($post, $isPrimary, array $includeRelationships)
164164
{
165165
return [
@@ -189,7 +189,7 @@ This would generate the following resource object:
189189
}
190190
```
191191

192-
> These links will only work if you register them when define your API's routing. For `related` links, see
192+
> These links will only work if you register them when define your API's routing. For `related` links, see
193193
[Fetching Resources](../fetching/resources.md) and for the `self` link, see
194194
[Fetching Relationships](../fetching/relationships.md).
195195

@@ -246,7 +246,7 @@ include the author data if the related resource was to be included in a compound
246246
```php
247247
class Schema extends SchemaProvider
248248
{
249-
$resourceType = 'posts';
249+
protected $resourceType = 'posts';
250250

251251
// ...
252252

@@ -277,10 +277,10 @@ To return meta for a relationship on a resource object:
277277
```php
278278
class Schema extends SchemaProvider
279279
{
280-
$resourceType = 'posts';
281-
280+
protected $resourceType = 'posts';
281+
282282
// ...
283-
283+
284284
public function getRelationships($post, $isPrimary, array $includeRelationships)
285285
{
286286
return [
@@ -312,7 +312,7 @@ This would generate the following resource object:
312312
}
313313
```
314314

315-
As with `data`, we wrap the meta in a closure so that the cost of generating it is only incurred if the
315+
As with `data`, we wrap the meta in a closure so that the cost of generating it is only incurred if the
316316
relationship is definitely appearing in the encoded response. This however is optional - i.e. you would not need
317317
to wrap the meta in a closure if there is no cost involved in generating it.
318318

@@ -325,10 +325,10 @@ included:
325325
```php
326326
class Schema extends SchemaProvider
327327
{
328-
$resourceType = 'posts';
329-
328+
protected $resourceType = 'posts';
329+
330330
// ...
331-
331+
332332
public function getRelationships($post, $isPrimary, array $includeRelationships)
333333
{
334334
return [

0 commit comments

Comments
 (0)
0