From 5be1e2d9e1e4abcc8d5637217565e5660bd09f15 Mon Sep 17 00:00:00 2001 From: Davey Shafik Date: Sun, 26 Jan 2025 05:02:42 -0800 Subject: [PATCH] docs: Update docs to cover SkipExtraParameters attribute --- docs/basic-usage.md | 26 ++++++++++++++++++++++++++ docs/how-bag-works.md | 18 ++++++++++-------- docs/laravel-controller-injection.md | 23 +++++++++++++++++++++++ 3 files changed, 59 insertions(+), 8 deletions(-) diff --git a/docs/basic-usage.md b/docs/basic-usage.md index 93cf521..a33185b 100644 --- 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 index 4fab4da..39078c6 100644 --- 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 index bc4df56..788a48f 100644 --- 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.