====== PHP RFC: Add pack()/unpack() endianness modifiers for floating-point numbers ======

  * Version: 1.0
  * Date: 2026-01-30
  * 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 with dedicated format letters:

  * <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)

The new modifier syntax using <php><</php> and <php>></php> is not supported yet. Adding the modifier support to float formats would provide consistency with [[pack-unpack-endianness-signed-integers-support|the endianness modifier syntax]], recently accepted for integers in the upcoming 8.6.

This RFC presents an evolution mentioned in the "Future scope" section of the accepted RFC.

===== 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
pack('G>', 3.14); // ValueError: Endianness modifier '>' cannot be applied to format code 'G' which already has inherent endianness
pack('e<', 3.14); // ValueError: Endianness modifier '<' cannot be applied to format code 'e' which already has inherent endianness
pack('E>', 3.14); // ValueError: Endianness modifier '>' cannot be applied to format code 'E' which already has inherent endianness

?>
</PHP>

===== Platform Consideration =====

PHP’s floating-point pack/unpack formats operate on the platform’s native floating-point representation and size. In practice this is typically IEEE 754 with 32 bits float and 64 bits double. This RFC does not introduce a new floating-point representation, only a new syntax for already existing format code.

===== Future Scope =====

A possible next step to this RFC would be to deprecate e, E, g and G format letters. These letters are not supported by Perl's <php>pack()</php> and <php>unpack()</php> functions and become useless with the introduction of the endianness modifier syntax. 

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

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

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

PHP 8.x (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
   * Abstain
</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
  * Discussion thread: https://externals.io/message/129956