docs: Update docs

Author: dshafik

docs/basic-usage.md

@@ -79,7 +79,7 @@ Bag will cast all values to their defined type _automatically_ for all scalar ty
 
 ### 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()` method:
+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:
 
 ```php
 $value = MyValue::from([
@@ -93,3 +93,6 @@ dump($newValue->toArray()); // ['name' => 'Davey Shafik', 'age' => 41]
 ```
 
 You can pass either named arguments, or an array or Collection of key-value pairs to the `Bag->with()` method. 
+
+> [!TIP]
+> The `Bag->append()` method works the same way as `Bag->with()`, but it will not validate the new value object. You can manually validate the object using `Bag->valid()`.

docs/laravel-controller-injection.md

@@ -1,6 +1,6 @@
 # Laravel Controller Injection
 
-Bag can automatically inject _validated_ Bag objects into your controllers using Laravel's automatic dependency injection. This can take
+Bag can automatically inject Bag objects into your controllers using Laravel's automatic dependency injection. This can take
 the place of using Laravel's form request validation _and_ accessing the input data.
 
 ```php
@@ -13,5 +13,30 @@ class MyController extends Controller {
 }
 ```
 
+## 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.
 
+## Manual Validation
+
+If you want to inject the `Bag` object without validation, you can add the `WithoutValidation` attribute to the property:
+
+```php
+use App\Values\MyValue;
+use Bag\Attributes\WithoutValidation;
+
+class MyController extends Controller {
+    public function store(
+        #[WithoutValidation] MyValue $value
+    ) {
+        $value = $value->append(extra: 'data')->valid();
+        // $value is now a validated MyValue 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.
+
+> [!CAUTION]
+> The input values must still fulfill the requirements of the Bag constructor, all required properties must be present otherwise an exception will be thrown.

docs/mapping.md

@@ -125,7 +125,7 @@ class MyValue extends Bag {
 
 ## When Mapping Applies
 
-Input mapping is applied when calling `Bag::from()`. You can use either the original property name _or_ the mapped name when creating a Bag.
+Input mapping is applied when calling `Bag::from()` or `Bag::withoutValidation()`. You can use either the original property name _or_ the mapped name when creating a Bag.
 
 > [!TIP]
 > [Validation](validation) is applied to the original property name, not the mapped name.

docs/validation.md

@@ -29,7 +29,7 @@ readonly class MyValue extends Bag
 
 In this example we added a `#[Required]` attribute to the `name` property, and defined validation rules in the `rules()` method.
 
-You can validate a Bag object using the `Bag::validate()` method:
+You can validate a Bag object before creating it using the `Bag::validate()` method:
 
 ```php
 $value = MyValue::validate([
@@ -38,6 +38,27 @@ $value = MyValue::validate([
 ]);
 ```
 
+## Creating a Bag Without Validation
+
+If you want to create a Bag without automatically validating it, you can use the `Bag::withoutValidation()` method:
+
+```php
+$value = MyValue::withoutValidation([
+    'name' => 'Davey Shafik',
+    'age' => 40,
+]);
+```
+
+To futher append properties to a Bag without validation, you can use the `Bag::append()` method:
+
+```php
+$value = MyValue::withoutValidation([
+    'name' => 'Davey Shafik',
+])->append([
+    'age' => 40,
+]);
+```
+
 ## Built-in Validation Attributes
 
 Bag provides a number of built-in validation attributes, based on various Laravel validation rules:

docs/why.md

@@ -50,7 +50,7 @@ has [custom collection classes](https://spatie.be/docs/laravel-data/v4/as-a-data
 
 ## Hidden Properties
 
-Bag supports [hiding properties](hidden) when transforming to an array or JSON.
+Bag supports [hiding properties](hidden) when transforming to an array and/or JSON.
 
 ## Artisan `make:bag` Command