Value Object Bundle Laravel Package

Getting Started

• Install with Composer: composer require marvin255/value-object-bundle. Check composer.json first for PHP, framework, and dependency constraints.
• Look first at the README, src/, and tests. Identify the public API: base value-object class/interface, factory methods, equality helpers, and any framework integration points.
• Confirm whether this is a Symfony-style bundle, a Laravel package with auto-discovery, or framework-agnostic PHP. The “bundle” naming and early 0.x version mean you should verify Laravel compatibility before designing around it.
• First use case: model a small domain concept such as Email, UserId, or Money as an immutable value object, validate it in the constructor/static factory, and use it at application boundaries instead of passing raw scalars everywhere.
• v0.2.1 is a patch release: it updates the dev-only infection/infection dependency and fixes a deprecated interface issue. There are no advertised new features or breaking changes, so no migration is expected.

Implementation Patterns

• Define one value object per domain concept, with a private constructor and static factories such as Email::fromString($value) or Money::fromCents($amount, $currency).
• Keep value objects immutable. Expose equals() for value comparison, __toString()/toNative() for presentation, and JsonSerializable or Laravel casts for serialization.
• In Laravel request flows, validate raw input in Form Requests, then map validated data to value objects in actions/services. Do not let controllers pass unvalidated arrays into domain objects.
• For Eloquent, use custom casts when the package or your implementation supports it; otherwise map between database scalars and value objects in repositories/model accessors.
• Use dependency injection for services that create or consume value objects, not for value objects themselves. Value objects should be created from data, not resolved from the container.
• Test value objects as pure units: validation failures, equality, normalization, and serialization. The package’s use of Infection for mutation testing is a good signal; mirror that discipline in your own domain tests.
• When integrating with existing Laravel code, introduce value objects at boundaries first—request validation, API resources, queue payloads, and domain service inputs—rather than rewriting every scalar at once.

Gotchas and Tips

• Treat 0.x releases as unstable. Pin the version in composer.json and review changelogs before upgrading, even for patch releases.
• v0.2.1 includes a deprecated-interface fix. If you implement package interfaces or extend internal classes, re-run static analysis and tests after upgrading; check for signature or type-hint changes.
• The Infection dependency update is development-only and should not affect production runtime. If you use Infection yourself, confirm version compatibility in CI.
• “Bundle” naming may imply Symfony conventions. In Laravel, verify whether service provider auto-discovery exists; if not, register manually or avoid framework-specific integration.
• Avoid overusing value objects for every scalar. They add the most value where validation, normalization, or domain meaning matters—IDs, emails, money, phone numbers, statuses.
• Serialization is a common pitfall. Decide explicitly whether APIs expose the native scalar or a structured object, and implement JsonSerializable, casts, or API resources accordingly.
• Equality must be value-based, not object identity. Be careful with floats, money precision, case normalization, and timezone-sensitive dates.
• Decide how validation failures surface: domain exceptions, Laravel validation exceptions, or result objects. Mixing approaches makes error handling inconsistent.
• Debugging tips: use composer show marvin255/value-object-bundle, composer why-not, and composer outdated; clear Laravel caches after provider/config changes; run focused unit tests plus static analysis after upgrades.
• Extension points are likely the provided base class/interface and your own factories/casts. Keep custom behavior in your application layer rather than forking the package for small changes.