Download the PHP package gladehq/php-coerce without Composer

php-coerce

Safe, predictable type coercion for PHP. If it cannot convert meaningfully, it returns null. Never guess.

PHP's native type juggling is unpredictable. (int)"abc" returns 0. empty(0) returns true. BackedEnum::from() throws on invalid values. Data arrives in many formats: HTML forms, JSON APIs, CSV files, .env files, and database rows. Each source has its own quirks.

php-coerce provides a single, consistent interface to handle all of it. The rule is simple: if a conversion is ambiguous, lossy, or meaningless, it returns null. Never guess.

Table of Contents

• Requirements
• Installation
• Quick Start
  • Static API
  • Fluent API
• API Reference
  • Boolean Coercion
  • Integer Coercion
  • Positive & Unsigned Integer
  • Float Coercion
  • Rounded Float
  • Decimal String (BC Math safe)
  • Percent
  • String Coercion
  • Array Coercion
  • Array Transform
  • DateTime Coercion
  • Enum Coercion
  • Comparison
  • Blank Detection
  • Format Validation
• Configuration
  • Number Format
  • Date Format
  • Boolean Values
  • Float Epsilon
  • Bulk Configuration
  • Reset
• Real-World Examples
• Architecture
• Design Principles
• Edge Cases & Gotchas
• Testing
• Contributing
• Security
• Changelog
• License

Requirements

Framework-agnostic. Works with Laravel, Symfony, Slim, or plain PHP.

Installation

No service providers, no configuration files, no bootstrapping required. Import the class and use it.

Quick Start

Static API

The simplest way to use the package. All methods are static, zero setup required.

Fluent API

Chain from a single value with Coerce::from(). Use *Or($default) methods for guaranteed non-null returns.

API Reference

Boolean Coercion

• String matching is case-insensitive: "TRUE", "True", and "true" all resolve to true.
• Only integers 0 and 1 map to booleans. 2, -1, and other integers return null.
• Truthy and falsy string sets are configurable.

Fluent:

Integer Coercion

Fluent:

Positive & Unsigned Integer

Thin guards built on top of toInteger().

Fluent:

Float Coercion

Fluent:

Rounded Float

Coerces to float then rounds to the requested number of decimal places. Returns null if the value cannot be coerced.

Fluent:

Decimal String (BC Math safe)

Returns a fixed-point decimal string suitable for bcmath functions or financial display. The result has exactly $scale digits after the decimal point. Returns null for values that cannot be coerced, INF, or NAN.

Throws \InvalidArgumentException if $scale < 0.

Fluent:

Percent

Normalises a percentage value to a decimal ratio (0–1 range). Two input conventions are supported:

• Percent string ('50%'): strips the % suffix and divides by 100
• Numeric value: if the value is within [-1, 1] it is returned as-is (already a ratio); otherwise it is divided by 100

Note: An integer 1 is treated as within [-1, 1] and returned as 1.0 (100%). If you mean 1%, pass '1%'.

Fluent:

String Coercion

toStringOrEmpty() returns '' instead of null for unconvertible values.

Fluent:

Array Coercion

Conversion is attempted in this priority order:

1. Already an array: returned as-is
2. Traversable (Iterator, Generator): converted via iterator_to_array()
3. JSON string (starts with [ or {): decoded with json_decode()
4. String with separator: split by separator, each part trimmed
5. Scalar string (no JSON, no separator): wrapped in a single-element array
6. int, float, bool: wrapped in a single-element array
7. null, non-traversable objects: null

JSON takes priority over separator splitting:

Fluent:

Array Transform

Coerces the value to an array (using the same logic as toArray()) then applies $fn to every element. Returns null if the value cannot be converted to an array. Keys are preserved.

Fluent:

DateTime Coercion

Always returns DateTimeImmutable or null. Never DateTime.

Important: Numeric strings are intentionally rejected in auto mode. To handle a timestamp stored as a string, cast it first:

Custom date format enforces strict matching. Trailing garbage is rejected:

Auto mode accepts PHP's relative date strings.

In auto mode, toDateTime() delegates to PHP's native \DateTimeImmutable constructor, which accepts the full range of formats that strtotime() understands. This includes relative expressions:

This is not a bug. It is PHP's documented behavior, and it is intentionally preserved so that toDateTime() in auto mode is as permissive as PHP itself.

However, if your input comes from untrusted sources (user form fields, API payloads, CSV rows) and you expect a concrete date, relative strings passing through silently may be surprising. For example, an API field that should contain a birth date would silently accept 'next monday' and produce a future date with no error.

The fix is to set an explicit format. When a format is configured, the native fallback is bypassed entirely and only strings that match the format exactly are accepted:

Use setDateFormat() whenever you are processing external input that must represent a real, absolute date.

Fluent:

Enum Coercion

Works with PHP 8.1+ backed enums (string-backed and int-backed). Returns null instead of throwing.

Cross-type coercion: a string "2" will match an int-backed enum with value 2. An int 1 will try string "1" against string-backed enums. Unit enums (enums without a backing type) safely return null. No crash.

Fluent:

Comparison

Semantic equality that respects types. Comparison layers are applied in this priority order:

1. Same type: strict === for non-floats; epsilon comparison for floats
2. One side is native bool: coerce both to boolean and compare
3. Both coercible to float: epsilon comparison
4. Both coercible to string: compare as strings
5. None match: false

The boolean layer only activates when at least one operand is a native bool. Two strings like "1" and "true" are never compared as booleans. They fall through to string comparison.

Float comparisons use a relative epsilon (|a - b| ≤ ε × max(|a|, |b|, 1)). The default epsilon is PHP_FLOAT_EPSILON. See Float Epsilon to customise it.

Blank Detection

Unlike PHP's empty(), the values 0 and false are not blank. They are valid, meaningful values.

Fluent:

toNullIfBlank() is useful for normalising optional form fields before persistence:

Format Validation

Thin wrappers over PHP's filter_var. Non-string values always return false.

Fluent:

Configuration

All configuration is optional. The package works out of the box with sensible defaults.

Number Format

Controls how numeric strings with separators are interpreted.

Auto-detection rules:

Date Format

Boolean Values

Customize which strings are considered truthy or falsy:

Float Epsilon

Controls the tolerance used by equals() when comparing float values.

The comparison formula is relative, not absolute: |a - b| ≤ ε × max(|a|, |b|, 1). This prevents epsilon from becoming meaninglessly small for large numbers or inappropriately large for numbers near zero.

Throws \InvalidArgumentException if epsilon is <= 0.

Bulk Configuration

Reset

Real-World Examples

Form Input Processing

Environment Variables

CSV / Spreadsheet Data

API Response Normalization

Safe Defaults with Fluent API

Blank vs Empty Checks

Cross-Type Enum Matching

Financial / Decimal Arithmetic

Validated User Input

Batch Array Coercion

Positive / Unsigned Guards

Architecture

All coercers and detectors are @internal. The public API surface consists of Coerce and CoerceValue only. Internal classes may change between minor versions without a semver break.

Design Principles

Edge Cases & Gotchas

Testing

The test suite covers 282 tests and 410 assertions, including:

• All coercion methods with valid, invalid, and boundary inputs
• Auto-detection logic for US/EU number formats
• DateTime parsing: timestamps, strings, custom formats, edge cases
• Enum coercion: backed enums, cross-type, unit enum safety
• IEEE-754 float comparison regression (equals(0.1 + 0.2, 0.3) === true)
• Comparison semantics: boolean layer activation rules, custom epsilon
• toBcDecimal, toPercent, toRoundedFloat, toPositiveInt, toUnsignedInt
• isEmail, isUrl, toNullIfBlank, coerceEach
• Configuration mutations and reset (including float_epsilon)
• Full fluent API coverage with default fallbacks

Contributing

Contributions are welcome. Please follow these guidelines:

1. Fork the repository and create a feature branch from main
2. Write tests for all new behaviour. The test suite must pass.
3. Ensure PHPStan level 9 reports no errors: vendor/bin/phpstan analyse
4. Follow PSR-12 coding style: vendor/bin/php-cs-fixer fix --dry-run --diff
5. Open a pull request with a clear description of the change and its rationale

For significant changes or new coercion domains, open an issue first to discuss the approach.

Security

If you discover a security vulnerability, please do not open a public GitHub issue. Report it privately via the repository's Security Advisories tab on GitHub.

All security reports will be acknowledged within 48 hours.

Changelog

All notable changes are documented in Semantic Versioning.

License

The MIT License (MIT). See LICENSE for full details.

Made with care by Dulitha Rajapaksha