PHP: rfc:pack-unpack-float-endianness-modifier

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: Add pack()/unpack() endianness modifiers for floating-point numbers ======

  * Version: 1.0
  * Date: 2026-01-16
  * Author: Alexandre Daubois, <alexandredaubois@php.net>
  * Status: Under discussion

===== Introduction =====

This RFC proposes extending the endianness modifier syntax (<php><</php> and <php>></php>) to floating-point format codes in PHP's <php>pack()</php> and <php>unpack()</php> functions.

Currently, PHP's pack/unpack functions support floating-point numbers only with machine-dependent byte order:

  * <php>f</php> - single-precision float (4 bytes, machine byte order)
  * <php>d</php> - double-precision float (8 bytes, machine byte order)
  * <php>g</php>/<php>G</php> - single-precision float (little/big endian)
  * <php>e</php>/<php>E</php> - double-precision float (little/big endian)

While PHP already has endian-specific letters for floats (<php>g</php>/<php>G</php>/<php>e</php>/<php>E</php>), the modifier syntax (<php>f<</php>/<php>f></php>/<php>d<</php>/<php>d></php>) provides consistency with [[pack-unpack-endianness-signed-integers-support|the endianness modifier syntax]] introduced in PHP 8.6.

===== Perl Specification Reference =====

According to the Perl documentation (https://perldoc.perl.org/functions/pack), Perl supports endianness modifiers on floating-point format codes:

<code>
f<   single-precision float, little-endian byte order
f>   single-precision float, big-endian byte order
d<   double-precision float, little-endian byte order
d>   double-precision float, big-endian byte order
</code>

===== Proposed Solution =====

This RFC proposes adding endianness modifiers to floating-point format codes:

  * <php>f<</php>/<php>f></php> for single-precision float (4-byte, little/big endian)
  * <php>d<</php>/<php>d></php> for double-precision float (8-byte, little/big endian)

**Example usage:**

<PHP>
<?php
// little endian
$data = pack('f<d<', 3.14159, 2.71828);

// big endian
$data = pack('f>d>', 3.14159, 2.71828);

// Unpacking
[$float, $double] = array_values(unpack('f<a/d<b', $data));
?>
</PHP>

**Equivalence with Existing Formats:**

<PHP>
<?php
pack('f<', 3.14) === pack('g', 3.14);
pack('f>', 3.14) === pack('G', 3.14);
pack('d<', 3.14) === pack('e', 3.14);
pack('d>', 3.14) === pack('E', 3.14);
?>
</PHP>

===== Error Handling =====

Modifiers on formats with inherent endianness (<php>g</php>/<php>G</php> and <php>e</php>/<php>E</php>) will emit a <php>ValueError</php>, for example:

<PHP>
<?php

pack('g<', 3.14); // ValueError: Endianness modifier '<' cannot be applied to format code 'g' which already has inherent endianness
</PHP>

===== Backward Incompatible Changes =====

None. The modifier syntax is opt-in and does not affect existing format strings.

===== Proposed PHP Version(s) =====

PHP 8.6 (next minor)

===== Voting Choices =====

Yes / No vote requiring 2/3 Yes votes to pass.

<doodle title="Add endianness modifiers to pack()/unpack() for floating-point numbers?" voteType="single" closed="false">
   * Yes
   * No
</doodle>

===== References =====

  * Integer endianness modifiers RFC: https://wiki.php.net/rfc/pack-unpack-endianness-signed-integers-support
  * Perl pack documentation: https://perldoc.perl.org/functions/pack
  * PHP pack documentation: https://www.php.net/manual/en/function.pack.php
Page Tools
