Docs refactor

config/data.php

@@ -93,7 +93,7 @@
      * method. By default, only when a request is passed the data is being validated. This
      * behaviour can be changed to always validate or to completely disable validation.
      */
-    'validation_type' => \Spatie\LaravelData\Support\Creation\ValidationType::OnlyRequests->value,
+    'validation_strategy' => \Spatie\LaravelData\Support\Creation\ValidationStrategy::OnlyRequests->value,
 
     /**
      * When using an invalid include, exclude, only or except partial, the package will

docs/_index.md

@@ -1,5 +1,5 @@
 ---
-title: v3
+title: v4
 slogan: Powerful data objects for Laravel
 githubUrl: https://github.com/spatie/laravel-data
 branch: main

docs/advanced-usage/creating-a-cast.md

@@ -14,7 +14,7 @@ interface Cast
 }
 ```
 
-The value that should be cast is given, and a `DataProperty` object which represents the property for which the value is cast. You can read more about the internal structures of the package [here](/docs/laravel-data/v3/advanced-usage/internal-structures).
+The value that should be cast is given, and a `DataProperty` object which represents the property for which the value is cast. You can read more about the internal structures of the package [here](/docs/laravel-data/v4/advanced-usage/internal-structures).
 
 Within the `context` array the complete payload is given.
 

docs/advanced-usage/creating-a-rule-inferrer.md

@@ -14,7 +14,7 @@ interface RuleInferrer
 }
 ```
 
-A collection of previous inferred rules is given, and a `DataProperty` object which represents the property for which the value is transformed. You can read more about the internal structures of the package [here](/docs/laravel-data/v3/advanced-usage/internal-structures).
+A collection of previous inferred rules is given, and a `DataProperty` object which represents the property for which the value is transformed. You can read more about the internal structures of the package [here](/docs/laravel-data/v4/advanced-usage/internal-structures).
 
 The `RulesCollection` contains all the rules for the property represented as `ValidationRule` objects.
 

docs/advanced-usage/creating-a-transformer.md

@@ -14,6 +14,6 @@ interface Transformer
 }
 ```
 
-The value that should be transformed is given, and a `DataProperty` object which represents the property for which the value is transformed. You can read more about the internal structures of the package [here](/docs/laravel-data/v3/advanced-usage/internal-structures).
+The value that should be transformed is given, and a `DataProperty` object which represents the property for which the value is transformed. You can read more about the internal structures of the package [here](/docs/laravel-data/v4/advanced-usage/internal-structures).
 
 In the end, the transformer should return a transformed value. Please note that the given value of a transformer can never be `null`.

docs/advanced-usage/pipeline.md

@@ -55,7 +55,7 @@ The `handle` method has several arguments:
 
 - **payload** the non normalized payload
 - **class** the `DataClass` object for the data
-  object [more info](/docs/laravel-data/v3/advanced-usage/internal-structures)
+  object [more info](/docs/laravel-data/v4/advanced-usage/internal-structures)
 - **properties** the key-value properties which will be used to construct the data object
 
 When using a magic creation methods, the pipeline is not being used (since you manually overwrite how a data object is

docs/advanced-usage/typescript.md

@@ -71,7 +71,7 @@ If you're using the `DtoTransformer` provided by the package, then be sure to pu
 Annotate each data object that you want to transform to Typescript with a `/** @typescript */` annotation or
 a `#[TypeScript]` attribute.
 
-To [generate the typescript file](https://spatie.be/docs/typescript-transformer/v3/laravel/executing-the-transform-command)
+To [generate the typescript file](https://spatie.be/docs/typescript-transformer/v4/laravel/executing-the-transform-command)
 , run this command:
 
 ```php

docs/advanced-usage/use-with-inertia.md

@@ -15,7 +15,7 @@ return Inertia::render('Song', SongsData::from($song));
 
 ## Lazy properties
 
-This package supports [lazy](https://spatie.be/docs/laravel-data/v3/as-a-resource/lazy-properties) properties, which can be manually included or excluded.
+This package supports [lazy](https://spatie.be/docs/laravel-data/v4/as-a-resource/lazy-properties) properties, which can be manually included or excluded.
 
 Inertia has a similar concept called [lazy data evaluation](https://inertiajs.com/partial-reloads#lazy-data-evaluation), where some properties wrapped in a closure only get evaluated and included in the response when explicitly asked.
 

docs/as-a-data-transfer-object/casts.md

@@ -118,4 +118,4 @@ Tip: we can also remove the `EnumCast` since the package will automatically cast
 
 ## Creating your own casts
 
-It is possible to create your casts. You can read more about this in the [advanced chapter](/docs/laravel-data/v3/advanced-usage/creating-a-cast).
+It is possible to create your casts. You can read more about this in the [advanced chapter](/docs/laravel-data/v4/advanced-usage/creating-a-cast).

docs/as-a-data-transfer-object/collections.md

@@ -101,6 +101,31 @@ There are a few requirements for this to work:
 - The method cannot be called **collect**
 - A **return type** must be defined
 
+## Creating a data object with collection
+
+You can create a data object with a collection of data object just like you would create a data object with a nested data object:
+
+```php
+use App\Data\SongData;
+use Illuminate\Support\Collection;
+
+class AlbumData extends Data
+{    
+    /** @var Collection<int, SongData> */
+    public Collection $songs;
+}
+
+AlbumData::from([
+    'title' => 'Never Gonna Give You Up',
+    'songs' => [
+        ['title' => 'Never Gonna Give You Up', 'artist' => 'Rick Astley'],
+        ['title' => 'Giving Up on Love', 'artist' => 'Rick Astley'],
+    ]
+]);
+```
+
+Since the collection type here is a `Collection`, the package will automatically convert the array into a collection of data objects.
+
 ## DataCollection's, PaginatedDataCollection's and CursorPaginatedCollection's
 
 The package also provides a few collection classes which can be used to create collections of data objects, it was a requirement to use these classes in the past versions of the package when nesting data objects collections in data objects. This is no longer the case and there are still valid use cases for them.

docs/as-a-data-transfer-object/computed.md

@@ -3,7 +3,7 @@ title: Computed values
 weight: 8
 ---
 
-Earlier we saw how default values can be set for a data object, the same approach can be used to set computed values, although slightly different:
+Earlier we saw how default values can be set for a data object, sometimes you want to set a default value based on other properties. For example, you might want to set a `full_name` property based on a `first_name` and `last_name` property. You can do this by using a computed property:
 
 ```php
 use Spatie\LaravelData\Attributes\Computed;
@@ -28,6 +28,8 @@ You can now do the following:
 SongData::from(['first_name' => 'Ruben', 'last_name' => 'Van Assche']);
 ```
 
+Please notice: the computed property won't be reevaluated when its dependencies change. If you want to update a computed property, you'll have to create a new object.
+
 Again there are a few conditions for this approach:
 
 - You must always use a sole property, a property within the constructor definition won't work

docs/as-a-data-transfer-object/creating-a-data-object.md

@@ -160,7 +160,7 @@ will try to create itself from the following types:
 - An *Arrayable* by calling `toArray` on it
 - An *array*
 
-This list can be extended using extra normalizers, find more about it [here](https://spatie.be/docs/laravel-data/v3/advanced-usage/normalizers).
+This list can be extended using extra normalizers, find more about it [here](https://spatie.be/docs/laravel-data/v4/advanced-usage/normalizers).
 
 When a data object cannot be created using magical methods or the default methods, a `CannotCreateData`
 exception will be thrown.
@@ -185,6 +185,6 @@ You can ignore the magical creation methods when creating a data object as such:
 SongData::withoutMagicalCreationFrom($song);
 ```
 
-## Advanced creation
+## Advanced creation using factories
 
-Internally this package is using a pipeline to create a data object from something. This pipeline exists of steps which transform properties into a correct structure and it can be completely customized. You can read more about it [here](/docs/laravel-data/v3/advanced-usage/pipeline).
+It is possible to configure how a data object is created, whether it will be validated, which casts to use and more. You can read more about it [here](/docs/laravel-data/v4/advanced-usage/factories).

docs/as-a-data-transfer-object/defaults.md

@@ -51,4 +51,4 @@ There are a few conditions for this approach:
 
 - You must always use a sole property, a property within the constructor definition won't work
 - The optional type is technically not required, but it's a good idea to use it otherwise the validation won't work
-- Validation won't be performed on the default value, so make sure it's valid
+- Validation won't be performed on the default value, so make sure it is valid

docs/as-a-data-transfer-object/factories.md

@@ -0,0 +1,73 @@
+---
+title: Factories
+weight: 10
+---
+
+It is possible to automatically create data objects in all sorts of forms with this package. Sometimes a little bit more
+control is required when a data object is being created. This is where factories come in.
+
+Factories allow you to create data objects like before but allow you to customize the creation process.
+
+For example, we can create a data object using a factory like this:
+
+```php
+SongData::factory()->from(['title' => 'Never gonna give you up', 'artist' => 'Rick Astley']);
+```
+
+Collecting a bunch of data objects using a factory can be done as such:
+
+```php
+SongData::factory()->collect(Song::all())
+```
+
+## Disable property name mapping
+
+We saw [earlier](/docs/laravel-data/v4/as-a-data-transfer-object/mapping-property-names) that it is possible to map
+property names when creating a data object from an array. This can be disabled when using a factory:
+
+```php
+ContractData::factory()->withoutPropertyNameMapping()->from(['name' => 'Rick Astley', 'record_company' => 'RCA Records']); // record_company will not be mapped to recordCompany
+```
+
+## Changing the validation strategy
+
+By default, the package will only validate Requests when creating a data object it is possible to change the validation
+strategy to always validate for each type:
+
+```php
+SongData::factory()->alwaysValidate()->from(['title' => 'Never gonna give you up', 'artist' => 'Rick Astley']);
+```
+
+Or completely disable validation:
+
+```php
+SongData::factory()->withoutValidation()->from(['title' => 'Never gonna give you up', 'artist' => 'Rick Astley']);
+```
+
+## Disabling magic methods
+
+A data object can be created
+using [magic methods](/docs/laravel-data/v4/as-a-data-transfer-object/creating-a-data-object.md#magical-creation) , this can be disabled
+when using a factory:
+
+```php
+SongData::factory()->withoutMagicalCreation()->from('Never gonna give you up'); // Won't work since the magical method creation is disabled
+```
+
+It is also possible to ignore the magical creation methods when creating a data object as such:
+
+```php
+SongData::factory()->ignoreMagicalMethod('fromString')->from('Never gonna give you up'); // Won't work since the magical method is ignored
+```
+
+## Adding additional global casts
+
+When creating a data object, it is possible to add additional casts to the data object:
+
+```php
+SongData::factory()->withCast('string', StringToUpperCast::class)->from(['title' => 'Never gonna give you up', 'artist' => 'Rick Astley']);
+```
+
+These casts will not replace the other global casts defined in the `data.php` config file, they will though run before
+the other global casts. You define them just like you would define them in the config file, the first parameter is the
+type of the property that should be cast and the second parameter is the cast class.

docs/as-a-data-transfer-object/mapping-property-names.md

@@ -20,7 +20,7 @@ class ContractData extends Data
 Creating the data object can now be done as such:
 
 ```php
-SongData::from(['name' => 'Rick Astley', 'record_company' => 'RCA Records']);
+ContractData::from(['name' => 'Rick Astley', 'record_company' => 'RCA Records']);
 ```
 
 Changing all property names in a data object to snake_case in the data the object is created from can be done as such:
@@ -37,7 +37,7 @@ class ContractData extends Data
 }
 ```
 
-You can also use the `MapName` attribute when you want to combine input (see [transforming data objects](https://spatie.be/docs/laravel-data/v3/as-a-resource/from-data-to-resource#mapping-property-names)) and output property name mapping:
+You can also use the `MapName` attribute when you want to combine input (see [transforming data objects](/docs/laravel-data/v4/as-a-resource/from-data-to-resource#mapping-property-names)) and output property name mapping:
 
 ```php
 #[MapName(SnakeCaseMapper::class)]

docs/as-a-data-transfer-object/nesting.md

@@ -115,11 +115,11 @@ The same is true for Laravel collections, but be sure to use two generic paramet
 
 ```php
 use App\Data\SongData;
-use \Illuminate\Support\Collection;
+use Illuminate\Support\Collection;
 
 class AlbumData extends Data
 {    
-    /** @var Collection<SongData> */
+    /** @var Collection<int, SongData> */
     public Collection $songs;
 }
 ```
@@ -139,29 +139,3 @@ class AlbumData extends Data
 ```
 
 This was the old way to define the type of data objects that will be stored within a collection. It is still supported, but we recommend using the annotation.
-
-### Creating a data object with collection
-
-You can create a data object with a collection of data object just like you would create a data object with a nested data object:
-
-```php
-new AlbumData(
-    'Never gonna give you up',
-    [
-        new SongData('Never gonna give you up', 'Rick Astley'),
-        new SongData('Giving up on love', 'Rick Astley'),
-    ]
-);
-```
-
-Or use the magical creation which will automatically create the data objects for you and also works with collections:
-
-```php
-AlbumData::from([
-    'title' => 'Never Gonna Give You Up',
-    'songs' => [
-        ['title' => 'Never Gonna Give You Up', 'artist' => 'Rick Astley'],
-        ['title' => 'Giving Up on Love', 'artist' => 'Rick Astley'],
-    ]
-]);
-```

docs/as-a-data-transfer-object/optional-properties.md

@@ -45,7 +45,8 @@ class SongData extends Data
     ) {
     }
 
-    public static function fromTitle(string $title): static{
+    public static function fromTitle(string $title): static
+    {
         return new self($title, Optional::create());
     }
 }