Getting Started

Check runtime requirements first. v1.3.1 is the first release with PHP 8 support, so pin your project to PHP 8.0+ and a Laravel version that satisfies the package's Composer constraints. If you're still on PHP 7.x, stay on the prior tag rather than forcing this one.
Install and verify discovery. Run composer require <vendor>/<package>, then confirm the service provider is auto-discovered (standard on Laravel 8+). If the package ships a config file, publish it with php artisan vendor:publish --tag=<package>-config before touching type settings.
Pick a small first use case. Define a class or DTO that uses a union type (e.g. public int|string $id;) and push it through the package's main entry point. This exercises the new union-type reflection path end-to-end in a few lines.
Where to look first: the v1.3.1 changelog, the package's type-resolution/reflection code, and any test fixtures involving ReflectionUnionType. Those three spots tell you whether the new support matches how you intend to use it.
Day-to-day entry point: most usage will be declaring typed properties/params in your own classes and letting the package resolve them. Start there before exploring extension points.

Implementation Patterns

Use union types at boundaries, not everywhere. DTOs, form requests, cast definitions, and API payloads are the natural places for int|string or string|array. Keep unions out of core domain logic where a concrete type is clearer.
Declare, don't branch manually. Instead of if (is_int($x)) ... else ..., let the package's resolver interpret int|string and normalize the value. This is the main workflow v1.3.1 unlocks.
Cross-version compatibility. If you share code with PHP 7.x projects, keep a @var int|string docblock alongside the typed property. Older package versions and static analyzers still read the docblock even when reflection can't express the union.
Custom type handling. If defaults don't cover a case, bind a custom type handler/resolver in a service provider rather than subclassing the package internals. Look for a registry or TypeHandler-style extension point in the docs.
CI matrix. Test on PHP 8.0 and 8.1. Union reflection behaves consistently, but implicit-nullable deprecations in 8.1 will surface in the package's own dependencies and can affect your integration.
Combine with Laravel validation. Where the package maps to validation rules, a int|string property usually maps to ['sometimes', 'integer', 'string']-style rules; verify the mapping rather than assuming.

mixed is not a union. Reflection reports mixed as a named type (on 8.0) not a ReflectionUnionType; don't expect it to hit the new code path.
Order isn't guaranteed. ReflectionUnionType::getTypes() does not promise declaration order. Never rely on int|string coming back as int first.
Nullable unions are subtle. ?int and int|null are equivalent in reflection; int|string|null is a three-member union. Confirm the package handles the null member explicitly.
Intersection types aren't covered. v1.3.1 adds unions only. A&B syntax (8.1) will not be handled by the new resolver.
Debug the reflection layer first. var_dump((new ReflectionProperty($class, 'prop'))->getType()) — if you get a ReflectionNamedType instead of ReflectionUnionType, the package isn't reaching the v1.3.1 code path (often a stale cached class or an old version constraint).
Config cache hides changes. After adding type mappings, run php artisan config:clear. Cached config is a common reason new unions appear unsupported in production but fine locally.
Watch for PHP 8.1 deprecations. Implicit nullable parameters and ${var} interpolation in the package's code may emit notices; suppress only after confirming they're harmless in your Laravel version.
Extension points over forks. Prefer the documented handler/resolver registration if you need to customize union behavior; forking the reflection logic will break on the next minor release.