Comuni Bundle Laravel Package

Getting Started

This release (1.0.9) is a small but behavior-affecting change: the lat, lon, and superficieKmq attributes are now cast to string rather than a numeric/decimal type. Start by checking the package's model casts (and any published config) to confirm where these casts live, then run your test suite before upgrading.

Minimal steps:

1. composer require the package (or bump to ^1.0.9) and run php artisan vendor:publish if the package ships migrations/config.
2. Inspect the model(s) that expose lat, lon, and superficieKmq — look for $casts entries such as 'lat' => 'decimal:7' that were changed to 'string'.
3. Verify the underlying database columns (e.g. decimal(10,7) vs varchar) — the cast change does not alter schema, so string casts over decimal columns are expected.
4. First use case: retrieve a record and confirm $model->lat, $model->lon, and $model->superficieKmq come back as strings (e.g. "45.4642000"), including in toArray()/JSON responses.

Implementation Patterns

• Treat the new string casts as the source of truth for transport: pass lat/lon/superficieKmq straight into API resources, forms, and views without re-casting.
• When you need arithmetic (distance calculations, area aggregation), explicitly cast at the call site: (float) $model->lat, (float) $model->superficieKmq, or use bcmul/bcadd for precision-sensitive math.
• For form round-trips, bind the string values directly to inputs and validate with numeric rules rather than decimal casts, since the model now returns strings.
• For persistence, let the model/DB handle the conversion — assign numeric or string values; avoid manually formatting decimals before save, as the column precision governs storage.
• In API resources, decide on an explicit contract: either emit strings (preserving the package behavior and avoiding float precision surprises) or convert with (float) and document it. Consistency across endpoints matters more than the choice.
• If you compare coordinates (e.g. deduplication, geo lookups), normalize both sides to the same type first — e.g. bccomp((string) $a, (string) $b, 7) — rather than relying on loose ==.

Gotchas and Tips

• Breaking behavior in a patch release: string casts change strict comparisons (===) and is_numeric-adjacent logic. Any code doing $model->lat === 45.46 or $model->superficieKmq > 0 may now behave differently; audit comparisons and assertions in tests.
• JSON/serialization: attributes now serialize as strings ("45.4642000"), which can surprise front-end consumers expecting numbers. Update TypeScript types, OpenAPI schemas, and JS parsers accordingly.
• Precision artifacts: decimal columns padded with trailing zeros (e.g. "45.4642000") will surface in output. Trim with rtrim($v, '0') or format explicitly if the UI expects clean values.
• Sorting and aggregation: ordering by these columns still happens in SQL (fine), but in-memory sort/sum on string values will misbehave — cast before collection operations.
• Validation mismatch: decimal validation rules are aimed at numeric strings and remain workable, but numeric plus between is usually clearer now; ensure your FormRequests accept strings.
• Debugging: use $model->getCasts() and dd($model->getAttributes(), $model->toArray()) to see raw vs. cast values when output looks wrong.
• Extension point: if you need numeric semantics back without touching the package, override casts in a subclass or accessor (getLatAttribute) rather than patching vendor code, so future releases don't clobber your change.
• Pin the version in composer.json if downstream consumers depend on numeric serialization until you've migrated them.