Add UnserializeCast

Data objects can now restore values that were stored with serialize(),
such as serialized database columns or cache entries, through
#[WithCast(UnserializeCast::class)]. The cast can fail silently, leaving
the value to the built-in conversion, and allowedClasses limits which
classes unserialize() may create.

Port of spatie/laravel-data#1220 at main a161f325d5.

Hypervel adaptations:

- allowedClasses defaults to false, so no objects are restored unless
  their classes are listed. Spatie allows every class by default, which
  runs __wakeup() and __destruct() for any class named in the value.
  Pass true to allow every class.
- failSilently no longer turns coroutine cancellation into a failed
  cast. The restore hooks of allowed classes can suspend, such as
  SerializesModels querying the database.
- The docs cover the allowed classes, including nested ones, and warn
  against unserializing untrusted data. Their failSilently example lists
  the class it restores.

All upstream UnserializeCast tests are ported, with coverage for the
default, a data object restoring only allowed classes, and cancellation
during a restore hook. The cast tests, analysis and formatting pass.

Author: binaryfire

data-objects.md

@@ -22,6 +22,7 @@
     - [Abstract Data Objects](#abstract-data-objects)
     - [Backed Enums](#backed-enums)
 - [Casts and Transformers](#casts-and-transformers)
+    - [Unserializing Values](#unserializing-values)
     - [Custom Casts](#custom-casts)
     - [Custom Transformers](#custom-transformers)
     - [Global Casts and Transformers](#global-casts-and-transformers)
@@ -898,6 +899,38 @@ class InvoiceData extends Data
 }
 ```
 
+<a name="unserializing-values"></a>
+### Unserializing Values
+
+The `UnserializeCast` runs PHP's `unserialize` function on a value. This is useful when you store serialized values yourself, for example in a database column or a cache:
+
+```php
+use Hypervel\Data\Attributes\WithCast;
+use Hypervel\Data\Casts\UnserializeCast;
+
+class SongData extends Data
+{
+    public function __construct(
+        public string $title,
+        #[WithCast(UnserializeCast::class, allowedClasses: [SongMetadata::class])]
+        public SongMetadata $metadata,
+    ) {
+    }
+}
+```
+
+The `allowedClasses` argument lists the classes that may be created while unserializing. Any other class becomes a `__PHP_Incomplete_Class` object, so a property typed as that class fails with a `TypeError`. This also applies to nested objects: when `SongMetadata` holds a `CarbonImmutable` date, `CarbonImmutable` must be listed as well. By default, no classes are allowed, so only scalar values, arrays, and enum cases are restored. You may pass `true` to allow every class.
+
+> [!WARNING]
+> Only unserialize trusted data. Class restrictions do not make user-controlled serialized data safe. For user input, use JSON and validate the decoded values.
+
+When the value cannot be unserialized, an exception is thrown. You may make the cast fail silently instead, which leaves the value to the built-in conversion:
+
+```php
+#[WithCast(UnserializeCast::class, failSilently: true, allowedClasses: [SongMetadata::class])]
+public SongMetadata $metadata;
+```
+
 <a name="custom-casts"></a>
 ### Custom Casts
 

porting-from-laravel.md

@@ -720,7 +720,7 @@ Laravel's deprecated `InvokableRule` contract is not available. Change rules tha
 
 When porting `spatie/laravel-data`, replace its namespace with `Hypervel\Data` and review the [Data Objects documentation](/docs/{{version}}/data-objects). The familiar `Data`, `Dto`, `Resource`, `Optional`, mapping, casting, validation, lazy-value, collection, resource, and Eloquent APIs are all available.
 
-Replace Spatie's `From*` attributes with Hypervel contextual constructor attributes. `UnserializeCast` is not included; write a custom cast that passes `allowed_classes` to `unserialize()` for trusted values. Livewire and TypeScript integrations are also not included.
+Replace Spatie's `From*` attributes with Hypervel contextual constructor attributes. Livewire and TypeScript integrations are not included.
 
 In `config/data.php`, the `casts`, `transformers`, `normalizers`, and `rule_inferrers` options only hold your own extensions; remove Spatie's built-in entries, since Hypervel's built-in handling is fixed. If you enabled Spatie's optional `FormRequestNormalizer`, keep it as `Hypervel\Data\Normalizers\FormRequestNormalizer`. Typed iterable items are always cast and transformed, and an array given to a collection property becomes that collection.
 
@@ -734,6 +734,7 @@ Review these behavior differences in ported code:
 - Custom `pipeline()` overrides and `DataPipe` classes are not supported. Rebuild them with named factories, `prepareForPipeline()`, or factory hooks.
 - A value that a union property already accepts is kept, such as a string for `string|SongData` or an array for `array|Collection`, and validation applies the rules of the declared type that holds it. Declare `Collection` alone when the property should always hold a collection. See [type conversion](/docs/{{version}}/data-objects#type-conversion).
 - A model attribute holding `null` is passed as `null` instead of falling back to the property's default or `Optional`. Columns that were not selected still count as missing.
+- `UnserializeCast` restores no objects unless their classes are listed in `allowedClasses`. List the classes your stored values contain, including nested ones. See [unserializing values](/docs/{{version}}/data-objects#unserializing-values).
 - A custom cast's `$properties` contains only declared property values keyed by PHP property name, without undeclared input or raw input names.
 - `CreationContext::$dataClass` is the class the creation started with, even while nested objects are created, and the context has no `from()`, `collect()`, or `currentPath`. Replace `$context->from()` with `TargetData::factory($context)->from()`, which copies the context's options but not its hooks. A cast can read `$property->className` for the class that declares the property.
 - An array or collection cannot be collected into a paginator target or given to a paginator property. Pass a Hypervel paginator so its pagination details are kept.