File: UPGRADE-v3.md

Recommend this page to a friend!

UPGRADE-v3.md

File:	`UPGRADE-v3.md`
Role:	Auxiliary data
Content type:	`text/markdown`
Description:	Auxiliary data
Class:	PHP Binary Flags Manage a group of boolean flags using integers
Author:	By Reinder Reinders
Last change:	Binary Flags v3 (#16) # Release Notes - v3.0.0 ## Changed - Numeric `BinaryFlags` APIs now accept `int` values only. - Passing `float` values to numeric mask/flag methods now raises `TypeError` for `strict_types=1` callers. - Non-strict callers should still cast or validate external values before calling the API because PHP scalar coercion can convert `float` to `int` at the call boundary. - The numeric iterator and JSON serialization contracts are now documented as `int`-based. ## Removed - `Bits::BIT_64`. - The v2.x float-normalization/deprecation path in `Traits\InteractsWithNumericFlags`. ## BIT_64 Notice `Bits::BIT_64` was removed because PHP numbers for bitwise flags are signed. The 64th bit is the sign bit, so it cannot be used reliably as a normal flag. Using integer-compatible bits avoids these issues.
Date:	2 days ago
Size:	`1,383 bytes`

Download

Upgrade Guide for v3.0.0

Summary

v3.0.0 removes support for float values in masks and flags. v3.0.0 also removes Bits::BIT_64.

What Changed

`v2.x`: `int|float` accepted in mask/flag methods.
`v3.0.0`: only `int` is accepted.
`v2.x`: `Bits::BIT_64` exists but is not reliable in real bitwise usage.
`v3.0.0`: `Bits::BIT_64` is removed. Use `BIT_1` through `BIT_63`.

How to Migrate

Find every call that passes mask/flag values into BinaryFlags methods.
Ensure values are cast or validated as `int` before passing them.
Ensure database or external sources provide integer-compatible values.

Example

Before:

$flags->setMask($legacyValue);
$flags->addFlag($legacyFlag);

After:

$flags->setMask((int) $legacyValue);
$flags->addFlag((int) $legacyFlag);

Runtime Impact

Code paths that still pass float values into numeric flag APIs now fail with TypeError when called from strict_types=1 code. For non-strict callers, PHP scalar coercion can still convert float to int at the call boundary, so external values should be validated or cast before calling the API.