[Refactor] Update package to use camel-case field names (#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 #393

Author: lindyhopchris

CHANGELOG.md

@@ -2,6 +2,15 @@
 All notable changes to this project will be documented in this file. This project adheres to
 [Semantic Versioning](http://semver.org/) and [this changelog format](http://keepachangelog.com/).
 
+## Unreleased
+
+### Changed
+- [#393](https://github.com/cloudcreativity/laravel-json-api/issues/393)
+**BREAKING:** when using the `SoftDeletesModel` trait on an adapter, the expected JSON API field
+for the soft delete attribute now defaults to the camel-case version of the model column. For example,
+column `deleted_at` previously defaulted to the JSON API field `deleted-at`, whereas now it will
+default to `deletedAt`. To continue to use dash-case, set the `softDeleteField` property on your adapter.
+
 ## [2.0.0] - 2020-06-17
 
 ### Added

composer.json

@@ -66,7 +66,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-develop": "2.x-dev"
+            "dev-develop": "3.x-dev"
         },
         "laravel": {
             "providers": [

docs/basics/adapters.md

@@ -103,21 +103,21 @@ If your resource supports client-generated ids, refer to the client-generated id
 
 When filling a model with attributes received in a JSON API request, the adapter will convert the JSON API
 field name to either the snake case or camel case equivalent. For example, if your JSON API resource had
-an attribute field called `published-at`, this is mapped to `published_at` if your model uses snake case keys,
+an attribute field called `publishedAt`, this is mapped to `published_at` if your model uses snake case keys,
 or `publishedAt` if not.
 
 > We work out whether your model uses snake case or camel case keys based on your model's `$snakeAttributes`
 static property.
 
 If you have a JSON API field name that needs to map to a different model attribute, this can be defined in your
-adapter's `$attributes` property. For example, if the `published-at` field needed to be mapped to the
+adapter's `$attributes` property. For example, if the `publishedAt` field needed to be mapped to the
 `published_date` attribute on your model, it must be defined as follows:
 
 ```php
 class Adapter extends AbstractAdapter
 {
     protected $attributes = [
-        'published-at' => 'published_date',
+        'publishedAt' => 'published_date',
     ];
 
     // ...
@@ -132,25 +132,25 @@ you will protect any attributes that are not fillable using Eloquent's
 
 There may be cases where an attribute is fillable on your model, but you do not want to allow your JSON API to
 fill it. You can set your adapter to skip attributes received from a client by listing the JSON API
-field name in the `$guarded` property on your adapter. For example, if we did not want the `published-at` field
+field name in the `$guarded` property on your adapter. For example, if we did not want the `publishedAt` field
 to be filled into our model, we would define it as follows:
 
 ```php
 class Adapter extends AbstractAdapter
 {
-    protected $guarded = ['published-at'];
+    protected $guarded = ['publishedAt'];
 
     // ...
 }
 ```
 
 Alternatively, you can white-list JSON API fields that can be filled by adding them to the `$fillable` property
-on your adapter. For example, if we only wanted the `title`, `content` and `published-at` fields to be filled:
+on your adapter. For example, if we only wanted the `title`, `content` and `publishedAt` fields to be filled:
 
 ```php
 class Adapter extends AbstractAdapter
 {
-    protected $fillable = ['title', 'content', 'published-at'];
+    protected $fillable = ['title', 'content', 'publishedAt'];
 
     // ...
 }
@@ -170,7 +170,7 @@ your adapter. For example:
 ```php
 class Adapter extends AbstractAdapter
 {
-    protected $dates = ['created-at', 'updated-at', 'published-at'];
+    protected $dates = ['createdAt', 'updatedAt', 'publishedAt'];
 
     // ...
 }

docs/basics/controllers.md

@@ -90,8 +90,8 @@ class PostsController extends JsonApiController
 
 ### Resource Hooks
 
-The controller allows you to hook into the resource lifecycle by invoking the following methods if they are 
-implemented. These methods allow you to easily implement application specific actions, such as firing events 
+The controller allows you to hook into the resource lifecycle by invoking the following methods if they are
+implemented. These methods allow you to easily implement application specific actions, such as firing events
 or dispatching jobs.
 
 | Hook | Arguments | Request Class |
@@ -106,12 +106,12 @@ or dispatching jobs.
 | `created` | record, request | `CreateResource` |
 | `saved` | record, request | `CreateResource` or `UpdateResource` |
 | `deleting` | record, request | `DeleteResource` |
-| `deleted` | record, request | `DeleteResource` | 
+| `deleted` | record, request | `DeleteResource` |
 
 > The request class is the validated request in the `CloudCreativity\LaravelJsonApi\Http\Requests` namespace.
 
 The `searching`, `searched`, `reading` and `didRead` hooks are invoked when resource(s) are being accessed,
-i.e. a `GET` request. The `searching` and `searched` hooks are invoked when reading any resources 
+i.e. a `GET` request. The `searching` and `searched` hooks are invoked when reading any resources
 (the *index* action), while `reading` and `didRead` are invoked when reading a specific record
 (the *read* action).
 
@@ -158,7 +158,7 @@ if reading the `author` relationship on a `posts` resource, the `readingRelation
 methods will be invoked if they exist.
 
 The `reading...` and `didRead...` methods are invoked when accessing the related resource or the relationship data,
-i.e. a `GET` relationship request. The `replacing...` and `replaced...` methods are invoked when changing the 
+i.e. a `GET` relationship request. The `replacing...` and `replaced...` methods are invoked when changing the
 entire relationship in a `PATCH` relationship request.
 
 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
 protected function deleted($record)
 {
     return $this->reply()->meta([
-        'accepted-at' => Carbon\Carbon::now()->toW3cString()
+        'acceptedAt' => Carbon\Carbon::now(),
     ], 202);
 }
 ```
@@ -197,7 +197,7 @@ Content-Type: application/vnd.api+json
 
 {
   "meta": {
-    "accepted-at": "2018-04-10T11:56:52+00:00"
+    "acceptedAt": "2018-04-10T11:56:52+00:00"
   }
 }
 ```
@@ -224,11 +224,11 @@ use CloudCreativity\LaravelJsonApi\Http\Controllers\JsonApiController;
 
 class PostsController extends JsonApiController
 {
-    
+
     public function share(\App\Post $post): \Illuminate\Http\Response
     {
         \App\Jobs\SharePost::dispatch($post);
-        
+
         return $this->reply()->content($post);
     }
 }
@@ -257,11 +257,11 @@ use CloudCreativity\LaravelJsonApi\Http\Requests\FetchResource;
 
 class PostsController extends JsonApiController
 {
-    
+
     public function share(FetchResource $request, \App\Post $post): \Illuminate\Http\Response
     {
         \App\Jobs\SharePost::dispatch($post);
-        
+
         return $this->reply()->content($post);
     }
 }

docs/basics/schemas.md

@@ -16,7 +16,7 @@ for this deprecated class can be found
 
 ## Defining Resources
 
-Your API's configuration contains a list of resources that appear in its JSON API documents in its `resources` array. 
+Your API's configuration contains a list of resources that appear in its JSON API documents in its `resources` array.
 This array maps the JSON API resource object `type` to the PHP class that it relates to. For example:
 
 ```php
@@ -29,7 +29,7 @@ This array maps the JSON API resource object `type` to the PHP class that it rel
 ```
 
 > You need to list **every** resource that can appear in a JSON API document in the `resources` configuration,
-even resources that do not have API routes defined for them. This is so that the JSON API encoder 
+even resources that do not have API routes defined for them. This is so that the JSON API encoder
 can locate a schema for each PHP class it encounters.
 
 ## Creating Schemas
@@ -56,9 +56,9 @@ method implemented if it is for an Eloquent resource. For example:
 ```php
 class Schema extends SchemaProvider
 {
-    
+
     protected $resourceType = 'posts';
-    
+
     /**
      * @param App\Post $resource
      * @return string
@@ -89,27 +89,27 @@ A resource object can contain an `attributes` object containing additional prope
 Attributes are returned by the `getAttributes()` method on your schema. If you have generated your schema,
 this method will already be implemented.
 
-As an example, a schema for a `posts` resource could look like this: 
+As an example, a schema for a `posts` resource could look like this:
 
 ```php
 class Schema extends SchemaProvider
 {
 
     // ...
-    
+
     /**
      * @param App\Post $post
      * @return array
      */
     public function getAttributes($post)
     {
         return [
-            'created-at' => $post->created_at->toW3cString(),
-            'updated-at' => $post->updated_at->toW3cString(),
-            'title' => $post->title,
+            'createdAt' => $post->created_at,
             'content' => $post->content,
+            'publishedAt' => $post->published_at,
             'slug' => $post->slug,
-            'published-at' => $post->published_at ? $post->published_at->toW3cString() : null,
+            'title' => $post->title,
+            'updatedAt' => $post->updated_at,
         ];
     }
 }
@@ -122,21 +122,21 @@ The above schema would result in the following resource object:
     "type": "posts",
     "id": "1",
     "attributes": {
-        "created-at": "2018-01-01T11:00:00+00:00",
-        "updated-at": "2018-01-01T12:10:00+00:00",
-        "title": "My First Post",
+        "createdAt": "2018-01-01T11:12:13.356234Z",
         "content": "...",
+        "publishedAt": "2018-01-01T12:30:10.258250Z",
         "slug": "my-first-post",
-        "published-at": "2018-01-01T12:00:00+00:00"
+        "title": "My First Post",
+        "updatedAt": "2018-01-01T12:30:10.258250Z"
     }
 }
 ```
 
 ## Relationships
 
 A resource object may have a `relationships` key that holds a relationships object. This object describes linkages
-to other resource objects. Relationships can either be to-one or to-many. The JSON API spec allows these linkages 
-to be described in resource relationships in multiple ways - either through a `links`, `data` or `meta` value, 
+to other resource objects. Relationships can either be to-one or to-many. The JSON API spec allows these linkages
+to be described in resource relationships in multiple ways - either through a `links`, `data` or `meta` value,
 or a combination of all three.
 
 > 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
 class Schema extends SchemaProvider
 {
     $resourceType = 'posts';
-    
+
     // ...
-    
+
     public function getRelationships($post, $isPrimary, array $includeRelationships)
     {
         return [
@@ -189,7 +189,7 @@ This would generate the following resource object:
 }
 ```
 
-> These links will only work if you register them when define your API's routing. For `related` links, see 
+> These links will only work if you register them when define your API's routing. For `related` links, see
 [Fetching Resources](../fetching/resources.md) and for the `self` link, see
 [Fetching Relationships](../fetching/relationships.md).
 
@@ -246,7 +246,7 @@ include the author data if the related resource was to be included in a compound
 ```php
 class Schema extends SchemaProvider
 {
-    $resourceType = 'posts';
+    protected $resourceType = 'posts';
 
     // ...
 
@@ -277,10 +277,10 @@ To return meta for a relationship on a resource object:
 ```php
 class Schema extends SchemaProvider
 {
-    $resourceType = 'posts';
-    
+    protected $resourceType = 'posts';
+
     // ...
-    
+
     public function getRelationships($post, $isPrimary, array $includeRelationships)
     {
         return [
@@ -312,7 +312,7 @@ This would generate the following resource object:
 }
 ```
 
-As with `data`, we wrap the meta in a closure so that the cost of generating it is only incurred if the 
+As with `data`, we wrap the meta in a closure so that the cost of generating it is only incurred if the
 relationship is definitely appearing in the encoded response. This however is optional - i.e. you would not need
 to wrap the meta in a closure if there is no cost involved in generating it.
 
@@ -325,10 +325,10 @@ included:
 ```php
 class Schema extends SchemaProvider
 {
-    $resourceType = 'posts';
-    
+    protected $resourceType = 'posts';
+
     // ...
-    
+
     public function getRelationships($post, $isPrimary, array $includeRelationships)
     {
         return [