Butler Service Laravel Package

Getting Started

glesys/butler-service is a pre-1.0 package (v0.31.1), so treat minor bumps as potentially breaking and pin an exact version in composer.json until it reaches 1.0.

composer require glesys/butler-service:0.31.1

Where to look first:

1. src/ scalar definitions — the release note (Long scalar for 64-bit integers) confirms the package exposes a scalar/type layer. Read the existing scalar classes before adding your own; Long is the newest addition and the best template for how a scalar is declared, validated, and converted.
2. tests/ — pre-1.0 packages are usually better documented by their test suite than by READMEs. Grep for Long, Int, and Scalar to see the intended call sites.
3. CHANGELOG.md / GitHub compare links — with this release cadence, the diff between tags is your real upgrade guide.

First use case: anywhere you currently hold an identifier, epoch-millisecond timestamp, byte count, or external system ID (Snowflake, Twitter/X-style IDs, ULIDs stored numerically) in a plain Int. Swap those fields to Long and verify round-tripping through your own persistence and JSON layers — that's the one change v0.31.1 unblocks.

Implementation Patterns

Declare 64-bit fields as Long, not Int. The whole point of the new scalar is that Int presumably maps to a narrower or platform-native integer. Audit your existing definitions for fields whose realistic value exceeds 2³¹ and migrate them explicitly rather than widening everything — keeping Int where it's semantically correct preserves validation strictness.

Cast at the boundaries, not in the domain. Accept string|int on input, coerce once at the edge ((int) $value after validation), then pass native int through the domain. PHP's int is a signed 64-bit type on 64-bit builds, which is exactly the range Long is designed around.

Serialise large values as strings on the wire. A Long above Number.MAX_SAFE_INTEGER (2⁵³−1) will silently lose precision in any JavaScript consumer, including an Inertia/Livewire front end. Emit (string) $id from your API resources and document the contract; let Long govern the server-side type, not the transport encoding.

Pair with Eloquent casts. If you persist these values, use 'bigint'-backed columns and an explicit cast so the package type and the database agree:

protected $casts = ['external_id' => 'integer']; // BIGINT column required

Test at the edges. Add cases at PHP_INT_MAX, 2⁵³−1, 2⁵³, and 2³¹ for any field you migrate. These are the values where Int/Long behaviour actually diverges, and they're cheap to assert.

Keep custom scalars alongside. If you already register project-specific scalars, follow the Long implementation's shape (declaration, validation, conversion) so upgrade diffs stay mechanical.

Gotchas and Tips

• 32-bit PHP breaks the premise. Long maps to a 64-bit integer, but PHP's int is 32-bit on 32-bit builds and on Windows before PHP 7.0-era 64-bit builds. If any deploy target is 32-bit, Long values will overflow silently. Check PHP_INT_SIZE in CI.
• filter_var($v, FILTER_VALIDATE_INT) is not a range check for the full 64-bit space — it validates against the platform's int size. For values near PHP_INT_MAX, validate as a numeric string with an explicit bounds check first.
• JSON precision loss is the most common production failure with this feature: it won't show up in PHP tests or in Postman, only in a browser or JS SDK.
• Database mismatch is silent. A Long field backed by a plain INT column will truncate on write. Confirm BIGINT (and UNSIGNED semantics) whenever you adopt Long.
• Pre-1.0 semver. v0.31.0 → v0.31.1 is a patch, so this addition should be non-breaking — but the same project has shipped 0.x minors before. Always read the compare link before bumping a locked minor.
• Debugging tip: when a Long value looks wrong, dump gettype(), the raw string from the source, and var_export() of the value at each hop (input → validation → persistence → serialisation). Precision loss at any single hop produces the same symptom.
• Extension points: the scalar layer is the natural place to add project-specific types; register them next to Long rather than building parallel conversion logic in your application code, so a future 1.0 migration touches one directory.