docs: Update docs to cover SkipExtraParameters attribute

dshafik · Jan 26, 2025 · 5be1e2d · 5be1e2d
1 parent f8c0990
commit 5be1e2d
Show file tree

Hide file tree

Showing 3 changed files with 59 additions and 8 deletions.
diff --git a/docs/basic-usage.md b/docs/basic-usage.md
@@ -117,6 +117,32 @@ $value = MyValue::from([
 ])->toArray(); // ['name' => 'Davey Shafik', 'age' => null]
 ```
 
+## Stripping Extra Parameters
+
+By default, Bag will throw a `\Bag\Exceptions\AdditionalPropertiesException` exception if you try to instantiate a non-variadic Bag with extra parameters. You can disable this behavior by adding the `StripExtraParameters` attribute to the class:
+
+```php
+use Bag\Attributes\StripExtraParameters;
+use Bag\Bag;
+
+#[StripExtraParameters]
+readonly class MyValue extends Bag {
+    public function __construct(
+        public string $name,
+        public ?int $age,
+    ) {
+    }
+}
+
+$value = MyValue::from([
+    'name' => 'Davey Shafik',
+    'test' => true,
+])->toArray(); // [ 'name' => 'Davey Shafik', 'age' => null ] (note that 'test' is stripped)
+```
+
+> [!TIP]
+> You can also use the `StripExtraParameters` attribute when [injecting a Bag object into a controller](/laravel-controller-injection#avoiding-extra-parameters).
+
 ### Modifying a Value Object
 
 Value Objects are immutable, so you cannot change their properties directly. Instead, you can create a new instance with the updated values using the `Bag->with()` or `Bag->append()` methods:

diff --git a/docs/how-bag-works.md b/docs/how-bag-works.md
@@ -31,8 +31,9 @@ start("Bag::from($data)")
 -- Finalized Input Values --> missing(Missing Parameters) --> missingError{Error?}
 missingError -- Yes --> errorMissingParameters(MissingPropertiesException)
 missingError -- No --> extra(Extra Parameters) --> extraError{Error?}
-extraError -- Yes --> errorExtraParameters(ExtraPropertiesException)
-extraError -- No --> validate(Validate)
+extraError -- Yes --> errorExtraParameters(AdditionalPropertiesException)
+extraError -- No --> strip(Strip Extra Parameters)
+--> validate(Validate)
 --> valid{Valid?}
 valid -- No --> errorValidation(ValidationException)
 valid -- Yes --> cast(Cast Input)
@@ -57,6 +58,7 @@ click mapInput "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes
 click laravelParams "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/LaravelRouteParameters.php" _blank
 click missing "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/MissingParameters.php" _blank
 click extra "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/ExtraParameters.php" _blank
+click strip "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/StripExtraParameters.php" _blank
 click validate "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/Validate.php" _blank
 click cast "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/CastInputValues.php" _blank
 click construct "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/FillBag.php" _blank
@@ -122,8 +124,9 @@ start("Bag::validate($data)")
 -- Finalized Input Values --> missing(Missing Parameters) --> missingError{Error?}
 missingError -- Yes --> errorMissingParameters(MissingPropertiesException)
 missingError -- No --> extra(Extra Parameters) --> extraError{Error?}
-extraError -- Yes --> errorExtraParameters(ExtraPropertiesException)
-extraError -- No --> validate(Validate)
+extraError -- Yes --> errorExtraParameters(AdditionalPropertiesException)
+extraError -- No --> strip(Strip Extra Parameters) 
+--> validate(Validate)
 --> valid{Valid?}
 valid -- No --> errorValidation(ValidationException)
 valid -- Yes --> success(return true)
@@ -141,6 +144,7 @@ click fillNulls "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipe
 click mapInput "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/MapInput.php" _blank
 click missing "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/MissingParameters.php" _blank
 click extra "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/ExtraParameters.php" _blank
+click strip "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/StripExtraParameters.php" _blank
 click validate "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/Validate.php" _blank
 ```
 
@@ -160,9 +164,7 @@ start("Bag::from($data)")
 --> laravelParams(Laravel Route Parameter Binding)
 -- Finalized Input Values --> missing(Missing Parameters) --> missingError{Error?}
 missingError -- Yes --> errorMissingParameters(MissingPropertiesException)
-missingError -- No --> extra(Extra Parameters) --> extraError{Error?}
-extraError -- Yes --> errorExtraParameters(ExtraPropertiesException)
-extraError -- No
+missingError -- No --> strip(Strip Extra Parameters)
 --> construct("new Bag(...)")
 --> computed(Verify Computed Values)
 --> initialized{Initialized?}
@@ -183,7 +185,7 @@ click fillNulls "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipe
 click mapInput "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/MapInput.php" _blank
 click laravelParams "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/LaravelRouteParameters.php" _blank
 click missing "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/MissingParameters.php" _blank
-click extra "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/ExtraParameters.php" _blank
+click strip "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/StripExtraParameters.php" _
 click validate "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/Validate.php" _blank
 click cast "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/CastInputValues.php" _blank
 click construct "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/FillBag.php" _blank

diff --git a/docs/laravel-controller-injection.md b/docs/laravel-controller-injection.md
@@ -13,6 +13,26 @@ class MyController extends Controller {
 }
 ```
 
+## Avoiding Extra Parameters
+
+By default, Bag will throw a `\Bag\Exceptions\AdditionalPropertiesException` exception if you try to instantiate a non-variadic Bag with extra parameters. You can disable this behavior by adding the `StripExtraParameters` attribute to the controller parameter:
+
+```php
+use App\Values\MyValue;
+use Bag\Attributes\StripExtraParameters;
+
+class MyController extends Controller {
+    public function store(
+        #[StripExtraParameters] MyValue $value
+    ) {
+        // After stripping extra parameters, $value is a validated MyValue object
+    }
+}
+```
+
+> [!TIP]
+> You can also add the `StripExtraParameters` attribute to [the Bag class itself](/basic-usage#stripping-extra-parameters). 
+
 ## Automatic Validation 
 
 When you type hint a `Bag` object in your controller method, Bag will automatically validate the request data and inject the `Bag` object into your controller method.
@@ -35,6 +55,9 @@ class MyController extends Controller {
 }
 ```
 
+> [!NOTE]
+> This will also strip additional parameters from the request data that are not part of the `Bag` object.
+
 > [!TIP]
 > The `Bag->valid()` method will throw a `ValidationException` if the Bag object is not valid by default, you can pass in `false` to return null instead.