Build coverage for tags

readonly.phpt
serialize.phpt

.gitattributes

@@ -1,8 +1,13 @@
+# template
 /docs/*.py          export-ignore
 /docs/*.txt         export-ignore
 /docs/_*            export-ignore
 /tests              export-ignore
-/debug              export-ignore
 /.git*              export-ignore
 /*.yml              export-ignore
+/*.yaml             export-ignore
 /*.xml              export-ignore
+/*.xml.dist         export-ignore
+
+# project
+/debug              export-ignore

.gitlab-ci.yml

@@ -14,7 +14,6 @@ cache:
     # install system packages
     - apt-get update && apt-get install -y git unzip libgmp-dev
     # install extensions
-    - docker-php-ext-install gmp
     - if [ "$INSTALL_XDEBUG" -eq 1 ]; then pecl install xdebug; docker-php-ext-enable xdebug; fi
     # install composer
     - php -r "copy('https://composer.github.io/installer.sig', '/tmp/composer.sig');"
@@ -37,53 +36,55 @@ coverage:
   stage: report
   only:
     - master
+    - tags
   image: php:8.1
   script:
     - composer update
+    - docker-php-ext-install gmp
     - XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-clover coverage.xml
     - bash <(curl -s https://codecov.io/bash)
 
 # test in every version
-test-7.1:
+test:
   extends: .test
   stage: test
-  image: php:7.1
+  image: ${ARCH}/php:${PHP_VERSION}
+  parallel:
+    matrix:
+      - PHP_VERSION:
+          - '7.1'
+          - '7.2'
+          - '7.3'
+          - '7.4'
+          - '8.0'
+          - '8.1'
+        ARCH:
+          - amd64
+          - i386
 
-test-7.2:
+test-gmp:
   extends: .test
   stage: test
-  image: php:7.2
-
-test-7.3:
-  extends: .test
-  stage: test
-  image: php:7.3
-
-test-7.4:
-  extends: .test
-  stage: test
-  image: php:7.4
-
-test-8.0:
-  extends: .test
-  stage: test
-  image: php:8.0
-
-test-8.1:
-  extends: .test
-  stage: test
-  image: php:8.1
+  image: ${ARCH}/php:${PHP_VERSION}
+  parallel:
+    matrix:
+      - PHP_VERSION:
+          - '7.4'
+          - '8.0'
+          - '8.1'
+        ARCH:
+          - amd64
+          - i386
+  script:
+    - docker-php-ext-install gmp
+    - composer update
+    - vendor/bin/phpunit
 
 # control that our tests are valid
 test-8.2-control:
   extends: .test
   stage: test
-  image: php:8.2-rc
-  # current version is compatible with current master, not any existing PHP 8.2 release
-  # todo: disallow failure after 8.2.0 is released
-  allow_failure: true
+  image: php:8.2
   script:
-    # fake the version for some dependencies
-    - composer config platform.php '8.1.0'
     - composer update
     - vendor/bin/phpunit

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: 'ubuntu-22.04'
+  tools:
+    python: '3.11'
+
+sphinx:
+  configuration: 'docs/conf.py'
+
+python:
+  install:
+  - requirements: 'docs/requirements.txt'

CHANGELOG.md

@@ -1,6 +1,80 @@
 # Changelog
 
-## 0.3.0
+[gh@TimWolla]: https://github.com/TimWolla
+[gh@nicolas-grekas]: https://github.com/nicolas-grekas
+
+## 1.x
+
+### 1.0.2
+
+*Sep 7, 2023*
+
+* Bump arokettu/unsigned to 1.2.1, previous versions may cause invalid results in Mersenne Twister on 32-bit systems.
+
+### 1.0.1
+
+*Nov 12, 2022*
+
+* Rely on symfony/polyfill-php82 for interface implementations and Random\Engine\Secure ([#6][gh#6]),
+  thanks to [Nicolas Grekas][gh@nicolas-grekas]
+* Added compatibility with PHP regression fix: [PHP#9839] ([#5][gh#5])
+
+[gh#6]: https://github.com/arokettu/php-random-polyfill/pull/6
+[PHP#9839]: https://github.com/php/php-src/pull/9839
+[gh#5]: https://github.com/arokettu/php-random-polyfill/pull/5
+
+### 1.0.0
+
+*Oct 26, 2022*
+
+Since RC1/RC2 are compatible with last 4 release candidates of PHP 8.2 (RC2-RC5),
+RC2 is re-released as stable.
+
+* No user facing changes since RC2
+
+### 1.0.0-rc2
+
+*Oct 1, 2022*
+
+* Speed up 32 bit calculations in 64 bit envs
+
+### 1.0.0-rc1
+
+*Sep 14, 2022*
+
+* `Secure` engine throws `RandomException` instead of `Exception`
+* Added verification of the number of elements in serialized data
+* Generated data is truncated to 64 bits in `Randomizer::getBytes()`
+* Fixed integer overflow in the upstream math lib
+
+### 1.0.0-beta1
+
+*Sep 2, 2022*
+
+* Fix incompatibility with PHP 8.2.0 RC1
+
+## 0.x
+
+### 0.5.0
+
+*Sep 1, 2022*
+
+Hopefully the last alpha
+
+* Exceptions are now compatible in most known cases
+* Full coverage
+* GMP is now an optional dependency (but highly recommended)
+
+### 0.4.0
+
+*Aug 19, 2022*
+
+* Verified compatibility with PHP 8.2.0 beta 3
+* Tests ported from the PHP engine
+* Various compatibility fixes
+* Exceptions compatibility (mostly)
+
+### 0.3.0
 
 *Aug 5, 2022*
 
@@ -9,7 +83,7 @@
 * `Xoshiro256StarStar`
 * Split `nextInt()` and `getInt($min, $max)` like in beta 2
 
-## 0.2.1
+### 0.2.1
 
 *Jul 31, 2022*
 
@@ -18,13 +92,12 @@
 * ``arrayPickKeys()`` throws a warning because full compatibility is not achievable.
   Thanks to [Tim Düsterhus][gh@TimWolla] for [the explanation][gh#1]
   * No warning if the engine is ``CryptoSafeEngine``
-* Fixed incorrect range function selection [[#1][gh#1]], thanks to [Tim Düsterhus][gh@TimWolla]
+* Fixed incorrect range function selection ([#1][gh#1]), thanks to [Tim Düsterhus][gh@TimWolla]
 * Fixed byte selection in range64
 
 [gh#1]: https://github.com/arokettu/php-random-polyfill/issues/1
-[gh@TimWolla]: https://github.com/TimWolla
 
-## 0.2.0
+### 0.2.0
 
 *Jul 27, 2022*
 
@@ -43,13 +116,13 @@ This will be fixed in 0.3.0 after PHP 8.2.0 beta 2 is released with some critica
   * Serialization and unserialization are now compatible with PHP 8.2
     if performed in PHP 7.4+
 
-## 0.1.1
+### 0.1.1
 
 *Jul 23, 2022*
 
 * Fixed Mt not generating enough data sometimes
 
-## 0.1.0
+### 0.1.0
 
 *Jul 23, 2022*
 

COPYING.adoc

@@ -34,7 +34,7 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ....
 
-## PHP
+== PHP
 
 The library includes code taken from the PHP 8.1.0 beta 1 and rewritten from C to PHP.
 
@@ -111,9 +111,9 @@ PHP includes the Zend Engine, freely available at
 <http://www.zend.com>.
 ....
 
-## Mersenne Twister
+== Mersenne Twister
 
-Mersenne Twister code is adapted from C++ code distributed under the 3-Clause BSD License.
+Mersenne Twister code in PHP is adapted from C++ code distributed under the 3-Clause BSD License.
 
 ....
 Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura,

LICENSE.md

@@ -1,7 +1,5 @@
 # BSD 3-Clause "New" or "Revised" License
 
-_This is a license for the product as a whole, see `COPYING.adoc` for additional licenses._
-
 Copyright © 2022 Anton Smirnov
 
 Redistribution and use in source and binary forms, with or without

README.md

@@ -1,22 +1,16 @@
 # Random Extension Polyfill for PHP
 
-[![Packagist](https://img.shields.io/packagist/v/arokettu/random-polyfill.svg?style=flat-square)](https://packagist.org/packages/arokettu/random-polyfill)
-[![PHP](https://img.shields.io/packagist/php-v/arokettu/random-polyfill.svg?style=flat-square)](https://packagist.org/packages/arokettu/random-polyfill)
-[![Packagist](https://img.shields.io/packagist/l/arokettu/random-polyfill.svg?style=flat-square)](https://opensource.org/licenses/BSD-3-Clause)
+[![PHP](https://img.shields.io/packagist/php-v/arokettu/random-polyfill/dev-master.svg?style=flat-square)](https://packagist.org/packages/arokettu/random-polyfill)
+[![Packagist](https://img.shields.io/packagist/l/arokettu/random-polyfill.svg?style=flat-square)][COPYING]
 [![Gitlab pipeline status](https://img.shields.io/gitlab/pipeline/sandfox/php-random-polyfill/master.svg?style=flat-square)](https://gitlab.com/sandfox/php-random-polyfill/-/pipelines)
 [![Codecov](https://img.shields.io/codecov/c/gl/sandfox/php-random-polyfill?style=flat-square)](https://codecov.io/gl/sandfox/php-random-polyfill/)
 
-This is a polyfill for the new `ext-random` extension that will be released with PHP 8.2.
-
-RFC:
-
-* https://wiki.php.net/rfc/rng_extension
-* https://wiki.php.net/rfc/random_extension_improvement
+This is a polyfill for the new `ext-random` extension that was released with PHP 8.2.
 
 ## Requirements
 
 * PHP 7.1
-* GMP extension
+* GMP extension is strongly recommended on PHP 7
 
 ## Installation
 
@@ -26,39 +20,28 @@ composer require 'arokettu/random-polyfill'
 
 ## Compatibility
 
-The library is compatible with `ext-random` as released in PHP 8.2.0 beta 1.
-
-## What works
-
-* `Random\Randomizer`
-* Engines
-  * `Random\Engine` interface
-  * `Random\CryptoSafeEngine` interface
-  * Secure Engine: `Random\Engine\Secure`
-  * Mersenne Twister: `Random\Engine\Mt19937`
-  * PCG64: `Random\Engine\PcgOneseq128XslRr64`
-  * xoshiro256**: `Random\Engine\Xoshiro256StarStar`
-
-## TODO
-
-* Keep updating with fixes from the upcoming betas and release 1.0.0 around PHP 8.2.0 rc 1
-* Empty `arokettu/random-polyfill` v1.99 for PHP 8.2.0 users
-* Spin-off without extension dependencies?
+The library aims to be compatible with `ext-random` as released in PHP 8.2.0 and subsequent patch releases.
 
 ## Documentation
 
+### Random Extension
+
+Read the official PHP doc: https://www.php.net/manual/en/book.random.php
+
+### The Polyfill
+
 Read full documentation here: <https://sandfox.dev/php/random-polyfill.html>
 
 Also on Read the Docs: <https://php-random-polyfill.readthedocs.io/>
 
 ## Support
 
-Please file issues on our main repo at GitLab: <https://gitlab.com/sandfox/php-random-polyfill/-/issues>
+Please file issues on our main repo at GitHub: <https://github.com/arokettu/php-random-polyfill/issues>
 
 ## License
 
 The library is available as open source under the terms of the [3-Clause BSD License].
 See [COPYING.adoc][COPYING] for additional licenses.
 
-[3-Clause BSD License]: https://opensource.org/licenses/BSD-3-Clause
+[3-Clause BSD License]: LICENSE.md
 [COPYING]: COPYING.adoc

composer.json

@@ -6,8 +6,8 @@
     "license": "BSD-3-Clause",
     "homepage": "https://sandfox.dev/php/random-polyfill.html",
     "support": {
-        "issues": "https://gitlab.com/sandfox/php-random-polyfill/-/issues",
-        "source": "https://gitlab.com/sandfox/php-random-polyfill",
+        "issues": "https://github.com/arokettu/php-random-polyfill/issues",
+        "source": "https://github.com/arokettu/php-random-polyfill",
         "docs": "https://php-random-polyfill.readthedocs.io/",
         "chat": "https://gitter.im/arokettu/community"
     },
@@ -37,18 +37,22 @@
     },
     "require": {
         "php": "^7.1 | ^8.0",
-        "ext-gmp": "*",
+        "arokettu/unsigned": "^1.2.1",
         "symfony/polyfill-php80": "^1.22",
-        "symfony/polyfill-php81": "^1.22"
+        "symfony/polyfill-php81": "^1.22",
+        "symfony/polyfill-php82": "^1.27"
     },
     "require-dev": {
-        "phpunit/phpunit": "^7.5 | ^8.5 | ^9.5",
+        "phpunit/phpunit": "^7.5 | ^8.5 | 9.5.*",
         "psy/psysh": "*",
-        "sandfox.dev/code-standard": "^10@dev",
+        "sandfox.dev/code-standard": "^1",
         "squizlabs/php_codesniffer": "*",
         "vimeo/psalm": "^4.24"
     },
     "provide": {
-        "ext-random": "8.1.0"
+        "ext-random": "8.2.0"
+    },
+    "suggest": {
+        "ext-gmp": "For significantly faster calculation"
     }
 }

debug/gh-9186.php

@@ -0,0 +1,11 @@
+<?php
+
+require __DIR__ . '/../vendor/autoload.php';
+
+var_dump(
+    unserialize(
+        'O:17:"Random\Randomizer":1:{i:0;a:2:{s:3:"foo";N;s:6:"engine";O:32:"Random\Engine\Xoshiro256StarStar":2:' .
+        '{i:0;a:0:{}i:1;a:4:{i:0;s:16:"7520fbc2d6f8de46";i:1;s:16:"84d2d2b9d7ba0a34";i:2;s:16:"d975f36db6490b32";i:3;' .
+        's:16:"c19991ee16785b94";}}}}'
+    )
+);

debug/shuffle.php

@@ -3,7 +3,7 @@
 require __DIR__ . '/../vendor/autoload.php';
 
 //$rnd = new \Random\Randomizer(new \Random\Engine\Secure());
-//$rnd = new \Random\Randomizer(new \Arokettu\Random\Tests\DevEngines\Xorshift32(123)); // TODO: different results
+//$rnd = new \Random\Randomizer(new \Arokettu\Random\Tests\DevEngines\Xorshift32(123));
 //$rnd = new \Random\Randomizer(new \Random\Engine\Mt19937(123, MT_RAND_MT19937));
 $rnd = new \Random\Randomizer(new \Random\Engine\Mt19937(123, MT_RAND_PHP));
 //$rnd = new \Random\Randomizer(new \Arokettu\Random\Tests\DevEngines\Zeros());

docs/_templates/rtd-version.html

@@ -0,0 +1,3 @@
+{%- if current_version -%}
+    <div class="sidebar-brand">{{ current_version }}</div>
+{%- endif -%}

docs/_templates/sidebar/brand.html

@@ -1,22 +0,0 @@
-<a class="sidebar-brand{% if logo %} centered{% endif %}" href="{{ pathto(master_doc) }}">
-    {% block brand_content %}
-    {%- if logo_url %}
-    <div class="sidebar-logo-container">
-        <img class="sidebar-logo" src="{{ logo_url }}" alt="Logo"/>
-    </div>
-    {%- endif %}
-    {%- if theme_light_logo and theme_dark_logo %}
-    <div class="sidebar-logo-container">
-        <img class="sidebar-logo only-light" src="{{ pathto('_static/' + theme_light_logo, 1) }}" alt="Light Logo"/>
-        <img class="sidebar-logo only-dark" src="{{ pathto('_static/' + theme_dark_logo, 1) }}" alt="Dark Logo"/>
-    </div>
-    {%- endif %}
-    {% if not theme_sidebar_hide_name %}
-    <span class="sidebar-brand-text">{{ docstitle if docstitle else project }}</span>
-    {%- endif %}
-    {% endblock brand_content %}
-</a>
-
-{%- if current_version -%}
-    <div class="sidebar-brand">{{ current_version }}</div>
-{%- endif -%}

docs/compatibility.rst

@@ -4,38 +4,33 @@ Compatibility Notes
 PHP
 ===
 
-The library is aimed to be compatible with ``ext-random`` from PHP 8.1.
-
-* Version 0.1 is compatible with PHP 8.2.0 beta 1
-* Version 1.0 will be compatible with PHP 8.2.0 rc 1
-
-Performance
-===========
-
-Well, it uses GMP, it's guaranteed to be slow.
-According to my tests, Randomizer + Mersenne Twister is 20 times slower than native.
-Good enough if you need a dozen numbers or so.
-
-What works
-==========
+.. 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.
 
-* ``Random\Randomizer``
+Available classes:
 
-* Engines
+* This polyfill:
 
-  * ``Random\Engine`` interface
-  * ``Random\CryptoSafeEngine`` interface
-  * Secure Engine: ``Random\Engine\Secure``
-  * Mersenne Twister: ``Random\Engine\Mt19937``
-  * PCG64: ``Random\Engine\PcgOneseq128XslRr64``
-  * xoshiro256**: ``Random\Engine\Xoshiro256StarStar``
+  * `Random\\Randomizer <https://www.php.net/manual/en/class.random-randomizer.php>`__
+  * `Random\\Engine\\Mt19937 <https://www.php.net/manual/en/class.random-engine-mt19937.php>`__
+  * `Random\\Engine\\PcgOneseq128XslRr64 <https://www.php.net/manual/en/class.random-engine-pcgoneseq128xslrr64.php>`__
+  * `Random\\Engine\\Xoshiro256StarStar <https://www.php.net/manual/en/class.random-engine-xoshiro256starstar.php>`__
+
+* From `symfony/polyfill-php82 <https://packagist.org/packages/symfony/polyfill-php82>`__:
+
+  * `Random\\Engine <https://www.php.net/manual/en/class.random-engine.php>`__
+  * `Random\\Engine\\CryptoSafeEngine <https://www.php.net/manual/en/class.random-cryptosafeengine.php>`__
+  * `Random\\Engine\\Secure <https://www.php.net/manual/en/class.random-engine-secure.php>`__
 
 Version 1.99.0
 ==============
 
-Version 1.99.0 will be released as an empty package for PHP >= 8.2.
+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
 =================
@@ -52,6 +47,10 @@ Serialization
   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)
+
+.. _GH-9186: https://github.com/php/php-src/issues/9186
 
 Randomizer
 ----------
@@ -92,3 +91,8 @@ 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``.

docs/conf.py

@@ -1,6 +1,10 @@
 from datetime import datetime
 
-project = 'Random Extension Polyfill'
+# import specific project config
+import os, sys
+sys.path.append(os.curdir)
+from conf_project import *
+
 author = 'Anton Smirnov'
 copyright = '{} {}'.format(datetime.now().year, author)
 language = 'en'
@@ -8,3 +12,17 @@ language = 'en'
 html_title = project
 html_theme = 'furo'
 templates_path = ["_templates"]
+html_sidebars = {
+    "**": [
+        "sidebar/brand.html",
+        "rtd-version.html",
+        "sidebar/search.html",
+        "sidebar/scroll-start.html",
+        "sidebar/navigation.html",
+        "sidebar/ethical-ads.html",
+        "sidebar/scroll-end.html",
+        "sidebar/variant-selector.html",
+    ]
+}
+
+exclude_patterns = ['venv/*']

docs/conf_project.py

@@ -0,0 +1 @@
+project = 'Random Extension Polyfill'

docs/index.rst

@@ -3,18 +3,13 @@ Random Extension Polyfill
 
 |Packagist| |GitLab| |GitHub| |Bitbucket| |Gitea|
 
-This is a polyfill for the new ``ext-random`` extension that will be released with PHP 8.2.
-
-RFC:
-
-* https://wiki.php.net/rfc/rng_extension
-* https://wiki.php.net/rfc/random_extension_improvement
+This is a polyfill for the new ``ext-random`` extension that was released with PHP 8.2.
 
 Requirements
 ============
 
 * PHP 7.1
-* GMP extension
+* GMP extension is strongly recommended on PHP 7 and somewhat recommended on PHP 8
 
 Installation
 ============
@@ -23,6 +18,11 @@ Installation
 
     composer require 'arokettu/random-polyfill'
 
+Random Extension Documentation
+==============================
+
+On the PHP website: https://www.php.net/manual/en/book.random.php
+
 Documentation
 =============
 
@@ -30,27 +30,17 @@ Documentation
    :maxdepth: 2
 
    compatibility
-
-TODO
-====
-
-* Keep updating with fixes from the upcoming betas and release 1.0.0 around PHP 8.2.0 rc 1
-* Empty ``arokettu/random-polyfill`` v1.99 for PHP 8.2.0 users
-* Other engines
-
-  * Maybe
-  * Some day
-  * If I have time
-  * Don't count on it
+   performance
+   license
+   thanks
 
 License
 =======
 
 The library is available as open source under the terms of the `3-Clause BSD License`__.
-See `COPYING.adoc`__ for additional licenses.
+See :ref:`license` for additional licenses.
 
 .. __: https://opensource.org/licenses/BSD-3-Clause
-.. __: https://gitlab.com/sandfox/php-random-polyfill/-/blob/master/COPYING.adoc
 
 .. |Packagist|  image:: https://img.shields.io/packagist/v/arokettu/random-polyfill.svg?style=flat-square
    :target:     https://packagist.org/packages/arokettu/random-polyfill

docs/license.rst

@@ -0,0 +1,156 @@
+.. _license:
+
+License
+#######
+
+The library itself is distributed under the 3-Clause BSD License but it also uses some code under other licenses.
+Here are all the terms on one page.
+
+Random Extension Polyfill for PHP
+=================================
+
+The library itself.
+
+    Copyright © 2022 Anton Smirnov
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice, this
+       list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright notice,
+       this list of conditions and the following disclaimer in the documentation
+       and/or other materials provided with the distribution.
+
+    3. Neither the name of the copyright holder nor the names of its
+       contributors may be used to endorse or promote products derived from
+       this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+PHP
+===
+
+The library includes code taken from the PHP 8.1.0 beta 1 and rewritten from C to PHP.
+
+PHP is distributed under the PHP License.
+
+.. code-block:: text
+
+    --------------------------------------------------------------------
+                      The PHP License, version 3.01
+    Copyright (c) 1999 - 2019 The PHP Group. All rights reserved.
+    --------------------------------------------------------------------
+
+    Redistribution and use in source and binary forms, with or without
+    modification, is permitted provided that the following conditions
+    are met:
+
+      1. Redistributions of source code must retain the above copyright
+         notice, this list of conditions and the following disclaimer.
+
+      2. Redistributions in binary form must reproduce the above copyright
+         notice, this list of conditions and the following disclaimer in
+         the documentation and/or other materials provided with the
+         distribution.
+
+      3. The name "PHP" must not be used to endorse or promote products
+         derived from this software without prior written permission. For
+         written permission, please contact group@php.net.
+
+      4. Products derived from this software may not be called "PHP", nor
+         may "PHP" appear in their name, without prior written permission
+         from group@php.net.  You may indicate that your software works in
+         conjunction with PHP by saying "Foo for PHP" instead of calling
+         it "PHP Foo" or "phpfoo"
+
+      5. The PHP Group may publish revised and/or new versions of the
+         license from time to time. Each version will be given a
+         distinguishing version number.
+         Once covered code has been published under a particular version
+         of the license, you may always continue to use it under the terms
+         of that version. You may also choose to use such covered code
+         under the terms of any subsequent version of the license
+         published by the PHP Group. No one other than the PHP Group has
+         the right to modify the terms applicable to covered code created
+         under this License.
+
+      6. Redistributions of any form whatsoever must retain the following
+         acknowledgment:
+         "This product includes PHP software, freely available from
+         <http://www.php.net/software/>".
+
+    THIS SOFTWARE IS PROVIDED BY THE PHP DEVELOPMENT TEAM ``AS IS'' AND
+    ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+    THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+    PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE PHP
+    DEVELOPMENT TEAM OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+    INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+    STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+    OF THE POSSIBILITY OF SUCH DAMAGE.
+
+    --------------------------------------------------------------------
+
+    This software consists of voluntary contributions made by many
+    individuals on behalf of the PHP Group.
+
+    The PHP Group can be contacted via Email at group@php.net.
+
+    For more information on the PHP Group and the PHP project,
+    please see <http://www.php.net>.
+
+    PHP includes the Zend Engine, freely available at
+    <http://www.zend.com>.
+
+Mersenne Twister
+================
+
+Mersenne Twister code in PHP is adapted from C++ code distributed under the 3-Clause BSD License.
+
+.. code-block:: text
+
+    Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura,
+    Copyright (C) 2000 - 2003, Richard J. Wagner
+
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    1. Redistributions of source code must retain the above copyright
+       notice, this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
+
+    3. The names of its contributors may not be used to endorse or promote
+       products derived from this software without specific prior written
+       permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+    A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

docs/performance.rst

@@ -0,0 +1,22 @@
+Performance Notes
+#################
+
+Well, even with GMP, it's guaranteed to be slow.
+Good enough if you need a dozen numbers or so.
+
+Performance test
+================
+
+https://github.com/arokettu/random-polyfill-perf
+
+* Secure engine is mostly unaffected by the choice of backend (except for nextInt() case)
+* PHP 7:
+
+  * With GMP installed, all engines are approximately 400 times slower than native
+  * Mersenne Twister is consistently 400 times slower than native, whether you use GMP or not
+  * PCG is 100 times slower without GMP and xoshiro256** is 50 times slower without GMP
+* PHP 8:
+
+  * 100-150 times slower than native
+  * GMP presence does not affect performance that much, but PCG will run twice as fast
+  * JIT helps almost as much as GMP (use both for max performance)

docs/requirements.txt

@@ -1 +1,2 @@
+sphinx>=7
 furo

docs/thanks.rst

@@ -0,0 +1,7 @@
+Thanks
+######
+
+* Random extension developers:
+  Go Kudo, Tim Düsterhus, Guilliam Xavier, Christoph M. Becker, Jakub Zelenka, Bob Weinand, Máté Kocsis,
+  and Original RNG implementators
+* Tim Düsterhus for reviews, issue reports and useful advices

phpcs.xml

@@ -4,11 +4,18 @@
 -->
 <ruleset name="Custom Standard" namespace="MyProject\CS\Standard">
     <rule ref="SandFox_PHP71">
-        <!-- all functions are imported -->
-        <exclude name="SlevomatCodingStandard.Namespaces.FullyQualifiedGlobalFunctions"/>
         <!-- crashes -->
         <exclude name="Security.BadFunctions.CallbackFunctions"/>
     </rule>
+    <rule ref="SlevomatCodingStandard.Namespaces.FullyQualifiedGlobalFunctions">
+        <properties>
+            <!-- Reset to default (include all functions) -->
+            <property name="includeSpecialFunctions" value="0"/>
+        </properties>
+    </rule>
+    <rule ref="SlevomatCodingStandard.Namespaces.FullyQualifiedGlobalConstants"/>
+    <!-- no need to cover 8.2 and later -->
+    <config name="testVersion" value="7.1-8.1"/>
     <file>src</file>
-<!--    <file>tests</file>-->
+    <file>tests</file>
 </ruleset>

src/Arokettu/Random/BigIntExportImport.php

@@ -1,102 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Arokettu\Random;
-
-use GMP;
-
-use function gmp_export;
-use function gmp_import;
-use function gmp_init;
-use function str_pad;
-use function substr;
-
-use const GMP_LITTLE_ENDIAN;
-use const GMP_LSW_FIRST;
-
-/**
- * @internal
- */
-trait BigIntExportImport
-{
-    /**
-     * @var int
-     * @psalm-var positive-int
-     */
-    private static $SIZEOF_UINT32_T = 4;
-    /**
-     * @var int
-     * @psalm-var positive-int
-     */
-    private static $SIZEOF_UINT64_T = 8;
-    /**
-     * @var int
-     * @psalm-var positive-int
-     */
-    private static $SIZEOF_UINT128_T = 16;
-
-    /** @var GMP|null 32-bit bitmask aka max 32-bit uint */
-    private static $UINT32_MASK = null;
-    /** @var GMP|null 64-bit bitmask aka max 64-bit uint */
-    private static $UINT64_MASK = null;
-    /** @var GMP|null 128-bit bitmask aka max 128-bit uint */
-    private static $UINT128_MASK = null;
-
-    private function initGmpConst(): void
-    {
-        if (self::$UINT32_MASK === null) {
-            self::$UINT32_MASK = gmp_init('ffffffff', 16);
-        }
-        if (self::$UINT64_MASK === null) {
-            self::$UINT64_MASK = gmp_init('ffffffffffffffff', 16);
-        }
-        if (self::$UINT128_MASK === null) {
-            self::$UINT128_MASK = gmp_init('ffffffffffffffffffffffffffffffff', 16);
-        }
-    }
-
-    private function importGmp32(string $value): GMP
-    {
-        $value = substr($value, 0, self::$SIZEOF_UINT32_T);
-        $value = str_pad($value, self::$SIZEOF_UINT32_T, "\0");
-        return gmp_import($value, self::$SIZEOF_UINT32_T, GMP_LITTLE_ENDIAN | GMP_LSW_FIRST);
-    }
-
-    private function importGmp64(string $value): GMP
-    {
-        $value = substr($value, 0, self::$SIZEOF_UINT64_T);
-        $value = str_pad($value, self::$SIZEOF_UINT64_T, "\0");
-        return gmp_import($value, self::$SIZEOF_UINT64_T, GMP_LITTLE_ENDIAN | GMP_LSW_FIRST);
-    }
-
-    private function importGmp128hilo(string $hi, string $lo): GMP
-    {
-        $value = $lo . $hi;
-        $value = substr($value, 0, self::$SIZEOF_UINT128_T);
-        $value = str_pad($value, self::$SIZEOF_UINT128_T, "\0");
-        return gmp_import($value, self::$SIZEOF_UINT128_T, GMP_LITTLE_ENDIAN | GMP_LSW_FIRST);
-    }
-
-    private function exportGmp32(GMP $value): string
-    {
-        $value = $value & self::$UINT32_MASK;
-        $value = gmp_export($value, self::$SIZEOF_UINT32_T, GMP_LITTLE_ENDIAN | GMP_LSW_FIRST);
-        return str_pad($value, self::$SIZEOF_UINT32_T, "\0");
-    }
-
-    private function exportGmp64(GMP $value): string
-    {
-        $value = $value & self::$UINT64_MASK;
-        $value = gmp_export($value, self::$SIZEOF_UINT64_T, GMP_LITTLE_ENDIAN | GMP_LSW_FIRST);
-        return str_pad($value, self::$SIZEOF_UINT64_T, "\0");
-    }
-
-    private function exportGmp128hilo(GMP $value): array
-    {
-        $value = $value & self::$UINT128_MASK;
-        $value = gmp_export($value, self::$SIZEOF_UINT128_T, GMP_LITTLE_ENDIAN | GMP_LSW_FIRST);
-        $value = str_pad($value, self::$SIZEOF_UINT128_T, "\0");
-        return array_reverse(str_split($value, self::$SIZEOF_UINT64_T));
-    }
-}

src/Arokettu/Random/Math.php

@@ -0,0 +1,160 @@
+<?php
+
+/**
+ * @copyright Copyright © 2022 Anton Smirnov
+ * @license BSD-3-Clause https://spdx.org/licenses/BSD-3-Clause.html
+ *
+ * @noinspection PhpComposerExtensionStubsInspection
+ */
+
+declare(strict_types=1);
+
+namespace Arokettu\Random;
+
+use GMP;
+
+/**
+ * @codeCoverageIgnore We don't care about math that was not used
+ */
+abstract class Math
+{
+    public const SIZEOF_UINT32_T = 4;
+    public const SIZEOF_UINT64_T = 8;
+    public const SIZEOF_UINT128_T = 16;
+
+    /** @var Math[] */
+    private static $maths = [];
+
+    public static function create(int $sizeof): self
+    {
+        return self::$maths[$sizeof] ?? self::$maths[$sizeof] = self::build($sizeof);
+    }
+
+    protected static function build(int $sizeof): self
+    {
+        // only less because PHP int is always signed
+        if ($sizeof < \PHP_INT_SIZE) {
+            return new MathNative($sizeof);
+        }
+
+        if (\extension_loaded('gmp')) {
+            return new MathGMP($sizeof);
+        }
+
+        return new MathUnsigned($sizeof);
+    }
+
+    /**
+     * @param int $sizeof
+     */
+    abstract protected function __construct(int $sizeof);
+
+    /**
+     * @param int|string|GMP $value
+     * @param int $shift
+     * @return int|string|GMP
+     */
+    abstract public function shiftLeft($value, int $shift);
+
+    /**
+     * @param int|string|GMP $value
+     * @param int $shift
+     * @return int|string|GMP
+     */
+    abstract public function shiftRight($value, int $shift);
+
+    /**
+     * @param int|string|GMP $value1
+     * @param int|string|GMP $value2
+     * @return int|string|GMP
+     */
+    abstract public function add($value1, $value2);
+
+    /**
+     * @param int|string|GMP $value1
+     * @param int $value2
+     * @return int|string|GMP
+     */
+    abstract public function addInt($value1, int $value2);
+
+    /**
+     * @param int|string|GMP $value1
+     * @param int|string|GMP $value2
+     * @return int|string|GMP
+     */
+    abstract public function sub($value1, $value2);
+
+    /**
+     * @param int|string|GMP $value1
+     * @param int $value2
+     * @return int|string|GMP
+     */
+    abstract public function subInt($value1, int $value2);
+
+    /**
+     * @param int|string|GMP $value1
+     * @param int|string|GMP $value2
+     * @return int|string|GMP
+     */
+    abstract public function mul($value1, $value2);
+
+    /**
+     * @param int|string|GMP $value1
+     * @param int $value2
+     * @return int|string|GMP
+     */
+    abstract public function mulInt($value1, int $value2);
+
+    /**
+     * @param int|string|GMP $value1
+     * @param int|string|GMP $value2
+     * @return int|string|GMP
+     */
+    abstract public function mod($value1, $value2);
+
+    /**
+     * @param int|string|GMP $value1
+     * @param int|string|GMP $value2
+     * @return int
+     */
+    abstract public function compare($value1, $value2): int;
+
+    /**
+     * @param string $value
+     * @return int|string|GMP
+     */
+    abstract public function fromHex(string $value);
+
+    /**
+     * @param int $value
+     * @return int|string|GMP
+     */
+    abstract public function fromInt(int $value);
+
+    /**
+     * @param string $value
+     * @return int|string|GMP
+     */
+    abstract public function fromBinary(string $value);
+
+    /**
+     * @param int|string|GMP $value
+     */
+    abstract public function toInt($value): int;
+
+    /**
+     * @param int|string|GMP $value
+     */
+    abstract public function toSignedInt($value): int;
+
+    /**
+     * @param int|string|GMP $value
+     */
+    abstract public function toBinary($value): string;
+
+    /**
+     * @param int|string|GMP $value
+     * @return int[]|string[]|GMP[]
+     */
+    abstract public function splitHiLo($value): array;
+}

src/Arokettu/Random/MathGMP.php

@@ -0,0 +1,222 @@
+<?php
+
+/**
+ * @copyright Copyright © 2022 Anton Smirnov
+ * @license BSD-3-Clause https://spdx.org/licenses/BSD-3-Clause.html
+ *
+ * @noinspection PhpComposerExtensionStubsInspection
+ * @noinspection PhpReturnDocTypeMismatchInspection
+ * @noinspection PhpIncompatibleReturnTypeInspection
+ */
+
+declare(strict_types=1);
+
+namespace Arokettu\Random;
+
+use GMP;
+
+/**
+ * @internal
+ * @psalm-suppress MoreSpecificImplementedParamType
+ * @codeCoverageIgnore We don't care about math that was not used
+ */
+// phpcs:disable SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
+// phpcs:disable SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingNativeTypeHint
+final class MathGMP extends Math
+{
+    /** @var GMP */
+    private $mask;
+    /** @var int */
+    private $sizeof;
+
+    /**
+     * @param int $sizeof
+     */
+    public function __construct(int $sizeof)
+    {
+        $this->mask = \gmp_pow(2, $sizeof * 8) - 1;
+        $this->sizeof = $sizeof;
+    }
+
+    /**
+     * @param GMP $value