[Docs] Update validators chapter and upgrade guide

Author: lindyhopchris

CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file. This projec
 ## Unreleased
 
 ### Changed
+- [#497](https://github.com/cloudcreativity/laravel-json-api/issues/497) and
+[#529](https://github.com/cloudcreativity/laravel-json-api/pull/529)
+**BREAKING:** The method signature of the `AbstractValidators::rules()` method has changed,
+so that the method has access to the data that will be validated.
 - [#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,

docs/basics/validators.md

@@ -111,9 +111,11 @@ class Validators extends AbstractValidators
      *
      * @param mixed|null $record
      *      the record being updated, or null if creating a resource.
+     * @param array $data
+     *      the data being validated.
      * @return mixed
      */
-    protected function rules($record = null): array
+    protected function rules($record, array $data): array
     {
         return [
             //
@@ -218,7 +220,7 @@ class Validators extends AbstractValidators
 {
     // ...
 
-    protected function rules($record = null): array
+    protected function rules($record, array $data): array
     {
         return [
             'title' => 'required|string|min:1|max:255',
@@ -239,7 +241,7 @@ This is because the package complies with the JSON API spec and validates all re
 check that they exist. Therefore the following **does not** need to be used:
 
 ```php
-protected function rules($record = null): array
+protected function rules($record, array $data): array
 {
     return [
         'author.id' => 'exists:users,id',
@@ -253,7 +255,7 @@ type is provided to the constructor, then the plural form of the attribute name
 example:
 
 ```php
-protected function rules($record = null): array
+protected function rules($record, array $data): array
 {
     return [
         'author' => [
@@ -386,7 +388,7 @@ class Validators extends AbstractValidators
 {
     // ...
 
-    protected function rules($record = null): array
+    protected function rules($record, array $data): array
     {
         return [
             'title' => "required|string|min:3",
@@ -925,7 +927,7 @@ class Validators extends AbstractValidators
 {
     // ...
 
-    protected function rules($record = null): array
+    protected function rules($record, array $data): array
     {
         return [
             'name' => 'required|string',
@@ -962,7 +964,7 @@ class Validators extends AbstractValidators
         return $validator;
     }
 
-    protected function rules($record = null): array
+    protected function rules($record, array $data): array
     {
         $rules = [
             'name' => 'required|string',

docs/upgrade.md

@@ -2,6 +2,30 @@
 
 ## 2.x to 3.0
 
+### Validators
+
+The method signature of the `rules()` method has changed so that the method has access to the data
+that is going to be validated. You will need to amend the method signature on all of your validator
+classes.
+
+The method signature was previously:
+
+```
+protected function rules($record = null): array
+{
+    // ...
+}
+```
+
+It is now:
+
+```
+protected function rules($record, array $data): array
+{
+    // ...
+}
+```
+
 ### Soft Deletes
 
 Previously if no soft deletes field was set on an adapter, the JSON API field would default to the dash-case