Build coverage for tags

.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

@@ -26,10 +26,6 @@ cache:
     - composer config -g cache-dir "$(pwd)/.composer-cache"
   script:
     - composer update
-    # native + unsigned
-    - vendor/bin/phpunit
-    - docker-php-ext-install gmp
-    # native + gmp
     - vendor/bin/phpunit
 
 # coverage
@@ -40,6 +36,7 @@ coverage:
   stage: report
   only:
     - master
+    - tags
   image: php:8.1
   script:
     - composer update
@@ -48,43 +45,46 @@ coverage:
     - 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
+  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

@@ -3,7 +3,15 @@
 [gh@TimWolla]: https://github.com/TimWolla
 [gh@nicolas-grekas]: https://github.com/nicolas-grekas
 
-## 1.0.1
+## 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*
 
@@ -15,7 +23,7 @@
 [PHP#9839]: https://github.com/php/php-src/pull/9839
 [gh#5]: https://github.com/arokettu/php-random-polyfill/pull/5
 
-## 1.0.0
+### 1.0.0
 
 *Oct 26, 2022*
 
@@ -24,13 +32,13 @@ RC2 is re-released as stable.
 
 * No user facing changes since RC2
 
-## 1.0.0-rc2
+### 1.0.0-rc2
 
 *Oct 1, 2022*
 
 * Speed up 32 bit calculations in 64 bit envs
 
-## 1.0.0-rc1
+### 1.0.0-rc1
 
 *Sep 14, 2022*
 
@@ -39,13 +47,15 @@ RC2 is re-released as stable.
 * Generated data is truncated to 64 bits in `Randomizer::getBytes()`
 * Fixed integer overflow in the upstream math lib
 
-## 1.0.0-beta1
+### 1.0.0-beta1
 
 *Sep 2, 2022*
 
 * Fix incompatibility with PHP 8.2.0 RC1
 
-## 0.5.0
+## 0.x
+
+### 0.5.0
 
 *Sep 1, 2022*
 
@@ -55,7 +65,7 @@ Hopefully the last alpha
 * Full coverage
 * GMP is now an optional dependency (but highly recommended)
 
-## 0.4.0
+### 0.4.0
 
 *Aug 19, 2022*
 
@@ -64,7 +74,7 @@ Hopefully the last alpha
 * Various compatibility fixes
 * Exceptions compatibility (mostly)
 
-## 0.3.0
+### 0.3.0
 
 *Aug 5, 2022*
 
@@ -73,7 +83,7 @@ Hopefully the last alpha
 * `Xoshiro256StarStar`
 * Split `nextInt()` and `getInt($min, $max)` like in beta 2
 
-## 0.2.1
+### 0.2.1
 
 *Jul 31, 2022*
 
@@ -87,7 +97,7 @@ Hopefully the last alpha
 
 [gh#1]: https://github.com/arokettu/php-random-polyfill/issues/1
 
-## 0.2.0
+### 0.2.0
 
 *Jul 27, 2022*
 
@@ -106,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*
 

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,16 +1,11 @@
 # Random Extension Polyfill for PHP
 
 [![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)](https://opensource.org/licenses/BSD-3-Clause)
+[![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
 
@@ -29,6 +24,12 @@ The library aims to be compatible with `ext-random` as released in PHP 8.2.0 and
 
 ## 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/>
@@ -42,5 +43,5 @@ Please file issues on our main repo at GitHub: <https://github.com/arokettu/php-
 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

@@ -37,15 +37,15 @@
     },
     "require": {
         "php": "^7.1 | ^8.0",
-        "arokettu/unsigned": "^1.0.1",
+        "arokettu/unsigned": "^1.2.1",
         "symfony/polyfill-php80": "^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"
     },

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,9 +4,28 @@ 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:
+
+* This polyfill:
+
+  * `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
 ==============
 

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,12 +3,7 @@ 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
 ============
@@ -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
 =============
 

docs/performance.rst

@@ -12,7 +12,7 @@ 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 is approximately 400 times slower than native
+  * 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:

docs/requirements.txt

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

tests/EngineMt19937Test.php

@@ -168,6 +168,11 @@ class EngineMt19937Test extends TestCase
 
     public function testVerySpecialRange32Branch(): void
     {
+        // @see https://www.php.net/manual/en/migration72.incompatible.php#migration72.incompatible.rand-mt_rand-output
+        if (\PHP_VERSION_ID < 70200) {
+            $this->markTestSkipped('PHP 7.1 has glitchy mt_rand');
+        }
+
         \mt_srand(123456);
         $r = new Randomizer(new Mt19937(123456));