Data Laravel Package

Getting Started

• Install with composer require fsi-open/data (check the repo's composer.json for the exact package name and Laravel version constraints before assuming).
• First place to look: README.md, then src/ for the service provider and the main contract/interface (often DataInterface, MapperInterface, or similar). The tests/ directory is the fastest way to see intended usage.
• Publish any config with php artisan vendor:publish --provider="Fsi\Data\..." if the package ships one; if not, expect zero-config usage.
• Minimal first use case: wrap a raw array or Eloquent model into a data object, then read fields through getters. Example shape:

$data = MyData::fromArray(['id' => 1, 'name' => 'Acme']);
echo $data->getName();

• If the package is mapper-oriented, start by defining one small data class and one mapper, then round-trip an array through it. That validates the core workflow before integrating with controllers or jobs.
• Version note (1.3.0): the latest release is dependency-only (it widens doctrine/dbal to ^4.0). There are no API changes, so nothing extra to learn before your first use case — but if you already have doctrine/dbal installed, resolve both packages together in one step:

composer require fsi-open/data doctrine/dbal --with-all-dependencies

Implementation Patterns

• DTO / data object pattern: Use package data objects as typed boundaries between layers (request → service → repository). Keep them immutable where the package supports it; mutate only through explicit setters or with* methods.
• Mapper/hydrator pattern: Define a mapper per source (array, Eloquent model, API payload). Centralize field mapping there instead of scattering array_get/data_get calls.
• Doctrine-backed hydration: With 1.3.0 you can run the package's DBAL-based type conversion against doctrine/dbal 4.x. If you hydrate from a Doctrine entity/result set, add one round-trip test (entity → data object) so a future DBAL bump shows up as a test failure rather than a runtime TypeError.
• Collection processing: If the package provides filters or processors, compose them in pipelines (filter → map → validate) rather than chaining ad-hoc loops. This keeps transform logic testable in isolation.
• Laravel integration: Bind mappers/data factories in a service provider (or use the package's provided bindings). Inject them into controllers/jobs via constructor injection; avoid app() calls inside domain code.
• Validation at the edge: Hydrate from request data into a data object only after FormRequest validation, then pass the object inward. This keeps controllers thin and data objects trustworthy.
• Testing: Unit-test mappers with plain arrays; feature-test the full round trip (request → data object → persisted model → response). Use the package's own test fixtures as reference.
• Upgrade path for 1.3.0: this is a safe minor. Do it deliberately rather than opportunistically — bump the package, then immediately run your own mapper/hydration tests. If you were pinned to doctrine/dbal 3.x on purpose (e.g. a custom DBAL type registered the old way), stay on 1.2.1 until that code is ported, since allowing DBAL 4 in the constraint doesn't force it, but a future composer update will drift you there.
• Workflow suggestion: For a new endpoint, write the data class first (fields + types), then the mapper, then the controller. This surfaces missing fields early and keeps the contract explicit.

Gotchas and Tips

• Low adoption signal: 0 stars and 0 dependents means limited community examples. Read the source and tests rather than relying on blog posts; pin the version in composer.json and review changelogs before upgrading.
• Release date check: The listed last release (2026-04-14) is in the future relative to typical package metadata—verify the actual tag on Packagist/GitHub before trusting version constraints. 1.3.0 itself is small (single PR, "Allowed doctrine/dbal ^4.0"), consistent with the project's low-activity cadence.
• DBAL 4 drift: ^4.0 is now permitted alongside your existing constraint. DBAL 4 removed a number of 3.x APIs (deprecated type/getName() conventions, changed result and statement APIs). Anything in your app that touches DBAL directly — custom types, SchemaManager calls, executeUpdate/statement handling — must be verified on 4.x before you let Composer resolve to it. Lock the resolved version in composer.lock and diff it in code review.
• Config caching: If the package registers config or bindings, run php artisan config:clear after changes; stale cached config is a common source of "my mapper isn't used" bugs.
• Immutability traps: If data objects are immutable, naive $data->field = 'x' silently fails or throws. Use the documented with*/setter API and reassign the result.
• Type coercion: Hydration from arrays often coerces strings to ints/floats inconsistently. Add explicit casts in your mapper and assert types in tests.
• Debugging: dd($dataObject) can hide private/protected fields. Use the package's toArray()/jsonSerialize() if available, or reflection-based dumping.
• Extension points: Favor implementing the package's interfaces (mapper, filter, data contract) over subclassing concrete classes—this survives minor version bumps better.
• Fallback plan: Given the low dependents count, keep your integration behind a thin adapter (your own interface + one implementation wrapping fsi/data). If the package stalls, you can swap the implementation without touching domain code.
• Composer conflicts: Re-check the require block after each upgrade (1.3.0 loosened DBAL, not Laravel/Symfony). On older Laravel versions you may still need --with-all-dependencies or a version pin; if a DBAL 3.x-only dependency exists elsewhere in the tree, the resolver will simply keep you on 3.x and 1.3.0 is a no-op.