Document --FLAKY-- section of PHPTs (GH-43)

The given example might not be the best one, since it actually wouldn't
need the `--FLAKY--` section, but it's the only one we currently have.

We also document the "flaky" convention for SKIPIF sections,

Author: cmb69

phpt_details.php

@@ -33,6 +33,7 @@
 <a href="#file_section">--FILE--</a> | <a href="#fileeof_section">--FILEEOF--</a> | <a href="#file_external_section">--FILE_EXTERNAL--</a> | <a href="#redirecttest_section">--REDIRECTTEST--</a><br/>
 [<a href="#cgi_section">--CGI--</a>]<br/>
 [<a href="#xfail_section">--XFAIL--</a>]<br/>
+[<a href="#flaky_section">--FLAKY--</a>]<br/>
 [<a href="#expectheaders_section">--EXPECTHEADERS</a>--]<br/>
 <a href="#expect_section">--EXPECT--</a> | <a href="#expectf_section">--EXPECTF--</a> | <a href="#expectregex_section">--EXPECTREGEX--</a>
 | <a href="#expect_external_section">--EXPECT_EXTERNAL--</a> | <a href="#expectf_external_section">--EXPECTF_EXTERNAL--</a> | <a href="#expectregex_external_section">--EXPECTREGEX_EXTERNAL--</a>
@@ -116,7 +117,10 @@
 <p><b>Format:</b><br/>
 PHP code enclosed by PHP tags. If the output of this scripts starts with "skip",
 the test is skipped. If the output starts with "xfail", the test is marked as
-expected failure. The "xfail" convention is supported as of PHP 7.2.0.</p>
+<a href="#xfail_section">expected failure</a>. If the output starts with "flaky",
+the test is marked as <a href="#flaky_section">flaky test</a>.
+The "xfail" convention is supported as of PHP 7.2.0.
+The "flaky" convention is supported as of PHP 8.2.25 and PHP 8.3.13, respectively.</p>
 <p><b>Example 1 (snippet):</b><br/>
 <pre>--SKIPIF--
 &lt;?php if (!extension_loaded("filter")) die("Skipped: filter extension required."); ?&gt;</pre>
@@ -132,6 +136,15 @@
 &lt;?php if (getenv('SKIP_ASAN')) die('xfail Startup failure leak'); ?&gt;</pre>
 </p>
 <p><b>Example 3 (full):</b> <a href="sample_tests/xfailif.php">xfailif.phpt</a></p>
+<p><b>Example 4 (snippet):</b><br/>
+<pre>--SKIPIF--
+&lt;?php
+if (getenv("GITHUB_ACTIONS") &amp;&amp; PHP_OS_FAMILY === "Darwin") {
+    die("flaky Occasionally segfaults on macOS for unknown reasons");
+}
+&gt;></pre>
+</p>
+<p><b>Example 4 (full):</b> <a href="sample_tests/flakyif.php">flakyif.phpt</a></p>
 </dd>
 
 <dt id="conflicts_section">--CONFLICTS--</dt>
@@ -666,6 +679,28 @@
 <p><b>Example 1 (full):</b> <a href="sample_tests/sample017.php">sample017.phpt</a></p>
 </dd>
 
+<dt id="flaky_section">--FLAKY--</dt>
+<dd>
+<p><b>Description:</b><br/>
+This section identifies this test as one that occassionally fails. If the test
+actually fails, it will be retried one more time, and that result will be reported.
+The section should include a brief description of why the test is flaky. Reasons for
+this include tests that rely on relatively precise timing, or
+temporary disc states. Available as of PHP 8.1.22 and 8.2.9, respectively.</p>
+<p>Please do NOT include a --FLAKY-- section without providing a text description for
+the reason it is being used.</p>
+<p><b>Required:</b><br/>
+No.</p>
+<p><b>Test Script Support:</b><br/>
+run-tests.php</p>
+<p><b>Format:</b><br/>
+A short plain text description of why this test is flaky.</p>
+<p><b>Example 1 (snippet):</b><br/>
+<pre>--FLAKY--
+This test frequently fails in CI</pre></p>
+<p><b>Example 1 (full):</b> <a href="sample_tests/flaky.php">flaky.phpt</a></p>
+</dd>
+
 <dt id="expectheaders_section">--EXPECTHEADERS--</dt>
 <dd>
 <p><b>Description:</b><br/>

sample_tests/flaky.php

@@ -0,0 +1,47 @@
+<?php
+include("../include/functions.php");
+
+$TITLE = "Sample Test [PHP-QAT: Quality Assurance Team]";
+$SITE_UPDATE = date("D M d H:i:s Y T", filectime(__FILE__));
+
+common_header();
+?>
+
+<div style="padding: 10px">
+<h1>Sample Test: sample001.phpt</h1>
+<p>Back to &quot;<a href="../phpt_details.php">PHPT Test File Layout</a>&quot;</p>
+<pre>--TEST--
+Test hrtime() aligns with microtime()
+--FLAKY--
+This test frequently fails in CI
+--FILE--
+&lt;?php
+
+$m0 = microtime(true);
+$h0 = hrtime(true);
+for ($i = 0; $i &lt; 1024*1024; $i++);
+$h1 = hrtime(true);
+$m1 = microtime(true);
+
+$d0 = ($m1 - $m0)*1000000000.0;
+$d1 = $h1 - $h0;
+
+/* Relative uncertainty. */
+$d = abs($d0 - $d1)/$d1;
+
+if ($d &gt; 0.05) {
+    print "FAIL, $d";
+} else {
+    print "OK, $d";
+}
+
+?&gt;
+--EXPECTF--
+OK, %f
+</pre>
+<p>Back to &quot;<a href="../phpt_details.php">PHPT Test File Layout</a>&quot;</p>
+</div>
+
+<?php
+common_footer();
+?>

sample_tests/flakyif.php

@@ -0,0 +1,59 @@
+<?php
+include("../include/functions.php");
+
+$TITLE = "Sample Test [PHP-QAT: Quality Assurance Team]";
+$SITE_UPDATE = date("D M d H:i:s Y T", filectime(__FILE__));
+
+common_header();
+?>
+
+<div style="padding: 10px">
+<h1>Sample Test: sample001.phpt</h1>
+<p>Back to &quot;<a href="../phpt_details.php">PHPT Test File Layout</a>&quot;</p>
+<pre>--TEST--
+Phar::chmod
+--EXTENSIONS--
+phar
+--INI--
+phar.readonly=1
+phar.require_hash=0
+--SKIPIF--
+&lt;?php
+if (getenv("GITHUB_ACTIONS") &amp;&amp; PHP_OS_FAMILY === "Darwin") {
+    die("flaky Occasionally segfaults on macOS for unknown reasons");
+}
+?&gt;
+--FILE--
+&lt;?php
+$fname = __DIR__ . '/' . basename(__FILE__, '.php') . '.1.phar.php';
+$pname = 'phar://hio';
+$file = '&lt;?php include "' . $pname . '/a.php"; __HALT_COMPILER(); ?&gt;';
+
+$files = array();
+$files['a.php']   = '&lt;?php echo "This is a\n"; include "'.$pname.'/b.php"; ?&gt;';
+include 'files/phar_test.inc';
+try {
+    $a = new Phar($fname);
+    var_dump($a['a.php']-&gt;isExecutable());
+    $a['a.php']-&gt;chmod(0777);
+    var_dump($a['a.php']-&gt;isExecutable());
+    $a['a.php']-&gt;chmod(0666);
+    var_dump($a['a.php']-&gt;isExecutable());
+} catch (Exception $e) {
+    echo $e-&gt;getMessage() . "\n";
+}
+?&gt;
+--CLEAN--
+&lt;?php
+unlink(__DIR__ . '/' . basename(__FILE__, '.clean.php') . '.1.phar.php');
+?&gt;
+--EXPECTF--
+bool(false)
+Cannot modify permissions for file "a.php" in phar "%s033a.1.phar.php", write operations are prohibited
+</pre>
+<p>Back to &quot;<a href="../phpt_details.php">PHPT Test File Layout</a>&quot;</p>
+</div>
+
+<?php
+common_footer();
+?>