Struct Laravel Package

Getting Started

This release is a maintenance/compatibility release for flyingdr/struct, not a feature release — but it contains a BC break, so treat the upgrade as a deliberate step rather than a routine composer update.

Minimal steps:

1. Upgrade with composer require flyingdr/struct:^0.3.
2. Search your codebase for every occurrence of the old type names and rename them:
   • @var Int → @var Integer
   • @var String → @var Str
   • Any class-name/annotation references to Int / String in property docblocks or annotations.
3. Run your test suite — the type coercion is what will break, and it usually breaks loudly (type mismatch / unexpected cast), which is good.

Where to look first:

• The commit linked in the release notes (1b03ec9…) is the authoritative diff for the rename; skim it before upgrading a large codebase so you know exactly which identifiers changed.
• Your own struct definitions — that is where 100% of the breakage lives. There is nothing to change in service providers or config, because this package is a plain PHP library, not a Laravel package with config/artifacts.

First use case in a Laravel app: define a struct for an inbound payload or an outbound API shape so you stop passing raw associative arrays around.

use FlyingDR\Struct\Struct;

class CreateUserStruct extends Struct
{
    /** @var Integer */
    public $id;

    /** @var Str */
    public $name;

    /** @var Str */
    public $email;
}

$user = new CreateUserStruct($request->validated());

The struct gives you typed, named properties instead of $data['name'] sprinkled across controllers and jobs.

Implementation Patterns

Use structs as a boundary object, not as a domain model. The sweet spot is at the edges of your app: request payloads, job payloads, third-party API responses, and event data. Instantiate the struct once, validate/sanitize at that edge, then pass the typed object inward. This keeps your services free of array_key_exists noise.

Pair with Form Requests rather than replacing them. Let Laravel's validation own the rules and let the struct own the shape:

public function store(StoreUserRequest $request)
{
    $struct = new CreateUserStruct($request->validated());
    CreateUserJob::dispatch($struct);
    // ...
}

Because the struct is serializable, it travels through queues cleanly and arrives typed on the other side.

Centralize a DTO namespace. Put structs in app/Structs (or app/DataTransferObjects) and keep one struct per payload shape. Resist the urge to make them polymorphic; a flat, boring struct is easier to reason about and easier to map to an Eloquent model or API Resource.

Map explicitly at the seams. Write a small toArray()/toModel() hop in your controller or a dedicated mapper rather than teaching the struct about Eloquent. That keeps the struct reusable for non-DB flows (webhooks, imports) and avoids coupling your transport layer to your persistence layer.

Compose for nested payloads. For a payload with a nested address object, define a separate AddressStruct and construct it inside the parent's factory method. This keeps each struct testable in isolation and makes the JSON shape obvious.

Use them in tests as fixtures. Because structs are typed and self-documenting, they make excellent test inputs: new CreateUserStruct(['id' => 1, 'name' => 'x', 'email' => '[email protected]']) is clearer than a bare array, and a bad fixture fails fast on the type check.

Gotchas and Tips

• The rename is the whole story of 0.3.0. Int and String were invalid class names under PHP 7, so they became Integer and Str. Any struct still annotated with the old names will silently miss type handling or throw — either way, audit every docblock. A grep -rn "@var \(Int\|String\)\b" across app/ is the fastest sweep.
• Do not rename only half the pair. The release notes call out both "properties and corresponding annotations" — if you use a string-keyed annotation map and a docblock, update both, or you get behaviour that differs between the two paths.
• This is why the jump looks bigger than it is. There is no new functionality; the diff is compatibility and cleanup. If a review or changelog suggests otherwise, it is describing the performance numbers, not new API surface.
• Performance is now a reason to pin to 0.3.0 on PHP 7.1+. Structure creation is reported up to 50× faster than on PHP 5.6. If you have a hot loop that builds structs per row (importers, report generation, queue batch processing), this release may be a measurable win — but benchmark your own path before claiming it, since struct construction is rarely the bottleneck compared to I/O.
• Pin the constraint consciously. Going from ^0.2 to ^0.3 is a breaking change under semver pre-1.0, so composer update in CI will fail rather than silently break production. Prefer pinning and upgrading on purpose.
• Debugging a mysterious type mismatch. Check the PHP version on the machine that fails before you check the code — 0.3.0 is explicitly the "supports all current PHP versions" release, so if one environment is on an older runtime, it is the outlier.
• Extension point to keep in mind. If you have a shared base struct with custom casting logic of your own, the rename can hide in inherited annotations just as easily as in leaf classes. Grep the base class first.