Compatibility Notes#

PHP#

Note

Random Extension doc on the PHP website: https://www.php.net/manual/en/book.random.php

The library aims to be compatible with ext-random as released in PHP 8.2.0 and subsequent patch releases. The library will not be a full replacement for ext-random and total compatibility does not seem to be achievable.

Available classes:

Version 1.99.0#

Version 1.99.0 is an empty package for PHP >= 8.2. It ensures that no overhead or extra code will be used for PHP 8.2+ apps.

Known differences#

These differences are considered to be permanent features. However if you know how to fix them, ideas are welcome.

Serialization#

  • Serialization is only compatible if done in PHP 7.4 and later.

  • Serializable entities implement \Serializable for controlled serialization in PHP 7.1 - 7.3.

  • Entities serialized in PHP 7.1 - 7.3 can be unserialized with the polyfill under any version of PHP but will not be unserializable by the native extension.

  • Serialization in PHP 7.1 - 7.3 will trigger a warning. Silence it with @ if you don’t care.

  • Does not throw in GH-9186 case but also does not create a dynamic property (PHP 7.4+) Undefined behavior for PHP <7.4 (returns false with a warning for the given code)

Randomizer#

  • pickArrayKeys() messes a lot with the internal structure of the PHP hash tables and therefore may produce different results in the userland. Example from Tim Düsterhus:

    <?php
    
    $r1 = new Random\Randomizer(new Random\Engine\Xoshiro256StarStar(1));
    $r2 = new Random\Randomizer(new Random\Engine\Xoshiro256StarStar(1));
    
    $a = [ 'a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5, 'f' => 6, ];
    unset($a['b']);
    
    $b = [ 'a' => 1, 'c' => 3, 'd' => 4, 'e' => 5, 'f' => 6, ];
    
    var_dump($a === $b); // bool(true)
    
    var_dump(
        $r1->pickArrayKeys($a, 1), // native: [ 0 => 'e' ], lib: [ 0 => 'd' ]
        $r2->pickArrayKeys($b, 1), // [ 0 => 'd' ]
    );
    

    The interpreter operates on the actual hash table that looks different for these arrays. The lib “repacks” arrays and therefore returns ['d'] in both cases.

  • using pickArrayKeys() will trigger a warning if the engine is not CryptoSafeEngine. Silence it with @ if you don’t care.

Mt19937#

  • Generating integers with $max - $min >= mt_getrandmax() with MT_RAND_PHP is considered undefined behavior. This library is consistent with PHP 8.2 behavior, not the version it runs under.

Warnings#

For obvious reasons, native extension produces E_WARNING and the library produces E_USER_WARNING.