[doc-en] master: Fix Phar examples that fail on every PHP version (#6052)

Author: Tim Bond (cookieguru) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-11-10T09:46:44+01:00 Commit: https://github.com/php/doc-en/commit/76e420706b6f54cdca08416d1ecdc4d1a7dd69e4 Raw diff: https://github.com/php/doc-en/commit/76e420706b6f54cdca08416d1ecdc4d1a7dd69e4.diff Fix Phar examples that fail on every PHP version (#6052) Each of these examples failed on its documented minimum version and still fails on PHP 8.5: * Add the required mode parameter to fopen() in the Phar and PharData addFromString examples. Calling fopen() with only a filename throws an ArgumentCountError on PHP 8, which the example's catch (Exception $e) does not catch, so the script stops with a fatal error. On PHP 7 it was a warning and the large file was never added. * Add the missing colon in "phar://" in Phar::copy. Without it the stream wrapper treats "phar//myphar.phar/c" as a relative local path, so copy() fails with "No such file or directory" and the file_get_contents() call that follows cannot find the copy. * Make the Phar::decompress example decompress a compressed archive. It called decompress() on $p2, which was never defined. It now compresses the archive first, as the Phar::compress example does, then decompresses that copy. The copy is given a new extension because decompress() writes next to the original archive and throws if a phar with the default name (here /path/to/my.phar) already exists. The alias changes from "my.phar.gz" to "my.phar" because the archive it names is not compressed. * Document on the Phar::decompress page that the method writes a new archive next to the original rather than decompressing it in place, how the new filename is derived from the extension parameter, and that it throws when that file already exists. Also refer to the extension parameter by name; the page called it "the second parameter", but the method has only one. * Replace PharFileInfo::setCompressedGZ(), which does not exist, with PharFileInfo::compress(Phar::GZ) in the Phar::startBuffering and PharFileInfo::isCompressed examples. The undefined method was a fatal error. * In the Phar::isCompressed example, check the archive that Phar::compress() returns. compress() leaves the original untouched and returns a new, compressed Phar, so checking the original printed bool(false) instead of the documented bool(true). * Escape $class in the Phar::startBuffering stub. The stub is a double-quoted string, so $class was interpolated (as an undefined variable) while building the stub instead of being written into it. Also register the autoloader with spl_autoload_register(), because declaring __autoload() is a fatal error since PHP 8.0, so the stub could not run. Changed paths: M reference/phar/Phar/addFromString.xml M reference/phar/Phar/copy.xml M reference/phar/Phar/decompress.xml M reference/phar/Phar/isCompressed.xml M reference/phar/Phar/startBuffering.xml M reference/phar/PharData/addFromString.xml M reference/phar/PharFileInfo/isCompressed.xml Diff: diff --git a/reference/phar/Phar/addFromString.xml b/reference/phar/Phar/addFromString.xml index 2d1d5ea483fa..126736abbb5a 100644 --- a/reference/phar/Phar/addFromString.xml +++ b/reference/phar/Phar/addFromString.xml @@ -67,7 +67,7 @@ try { $b = $a['path/to/file.txt']->getContent(); // to add contents from a stream handle for large files, use offsetSet() - $c = fopen('/path/to/hugefile.bin'); + $c = fopen('/path/to/hugefile.bin', 'rb'); $a['largefile.bin'] = $c; fclose($c); } catch (Exception $e) { diff --git a/reference/phar/Phar/copy.xml b/reference/phar/Phar/copy.xml index a3875fef7b83..caa2dd5cb59d 100644 --- a/reference/phar/Phar/copy.xml +++ b/reference/phar/Phar/copy.xml @@ -89,7 +89,7 @@ try { // The stream wrapper equivalent of the above code. // E_WARNING are triggered on error rather than exceptions -copy('phar://myphar.phar/a', 'phar//myphar.phar/c'); +copy('phar://myphar.phar/a', 'phar://myphar.phar/c'); echo file_get_contents('phar://myphar.phar/c'); // Outputs "hi" ?> diff --git a/reference/phar/Phar/decompress.xml b/reference/phar/Phar/decompress.xml index a4a76addee8c..0eae68d87073 100644 --- a/reference/phar/Phar/decompress.xml +++ b/reference/phar/Phar/decompress.xml @@ -14,9 +14,12 @@ </methodsynopsis> &phar.write; - <para> + <simpara> For tar-based and phar-based phar archives, this method decompresses the entire archive. - </para> + The decompressed archive is written as a new file in the same directory as the + original archive, and is returned as a new <classname>Phar</classname> object. + The original archive is not modified. + </simpara> <para> For Zip-based phar archives, this method fails with an exception. The <link linkend="ref.zlib">zlib</link> extension must be enabled to decompress @@ -27,13 +30,15 @@ <link linkend="ini.phar.readonly">phar.readonly</link> INI variable must be off in order to succeed. </para> - <para> - In addition, this method automatically changes the file extension of the archive, + <simpara> + In addition, this method automatically changes the file extension of the new archive, <literal>.phar</literal> by default for phar archives, or <literal>.phar.tar</literal> for tar-based phar archives. - Alternatively, a file extension may be specified with the second - parameter. - </para> + For example, decompressing <filename>/path/to/my.phar.gz</filename> creates + <filename>/path/to/my.phar</filename>. + Alternatively, a file extension may be specified with the + <parameter>extension</parameter> parameter. + </simpara> </refsect1> <refsect1 role="parameters"> @@ -50,6 +55,12 @@ that all executable phar archives must contain <literal>.phar</literal> in their filename. </para> + <simpara> + The extension replaces the archive's own extension (such as <literal>.phar.gz</literal> + or <literal>.tar.gz</literal>), so passing <literal>decompressed.phar</literal> + when decompressing <filename>/path/to/my.phar.gz</filename> creates + <filename>/path/to/my.decompressed.phar</filename>. + </simpara> </listitem> </varlistentry> </variablelist> @@ -66,13 +77,13 @@ <refsect1 role="errors"> &reftitle.errors; - <para> + <simpara> Throws <classname>BadMethodCallException</classname> if the <link linkend="ini.phar.readonly">phar.readonly</link> INI variable is on, the <link linkend="ref.zlib">zlib</link> - extension is not available, or the <link linkend="ref.bzip2">bzip2</link> extension - is not enabled. - </para> + extension is not available, the <link linkend="ref.bzip2">bzip2</link> extension + is not enabled, or a phar with the new filename already exists. + </simpara> </refsect1> <refsect1 role="changelog"> @@ -105,10 +116,11 @@ <programlisting role="php"> <![CDATA[ <?php -$p = new Phar('/path/to/my.phar', 0, 'my.phar.gz'); +$p = new Phar('/path/to/my.phar', 0, 'my.phar'); $p['myfile.txt'] = 'hi'; $p['myfile2.txt'] = 'hi'; -$p3 = $p2->decompress(); // creates /path/to/my.phar +$p2 = $p->compress(Phar::GZ); // creates /path/to/my.phar.gz +$p3 = $p2->decompress('decompressed.phar'); // creates /path/to/my.decompressed.phar ?> ]]> </programlisting> diff --git a/reference/phar/Phar/isCompressed.xml b/reference/phar/Phar/isCompressed.xml index b6a84e39262e..f14d8451cd95 100644 --- a/reference/phar/Phar/isCompressed.xml +++ b/reference/phar/Phar/isCompressed.xml @@ -48,8 +48,8 @@ try { var_dump($phar1->isCompressed()); $phar2 = new Phar('myuncompressed.tar.phar'); var_dump($phar2->isCompressed()); - $phar2->compress(Phar::GZ); - var_dump($phar2->isCompressed() == Phar::GZ); + $phar3 = $phar2->compress(Phar::GZ); + var_dump($phar3->isCompressed() == Phar::GZ); } catch (Exception $e) { } ?> diff --git a/reference/phar/Phar/startBuffering.xml b/reference/phar/Phar/startBuffering.xml index 1f4c7184725c..03b74280406c 100644 --- a/reference/phar/Phar/startBuffering.xml +++ b/reference/phar/Phar/startBuffering.xml @@ -69,14 +69,13 @@ echo 'The new phar has ' . $p->count() . " entries\n"; $p->startBuffering(); $p['file.txt'] = 'hi'; $p['file2.txt'] = 'there'; -$p['file2.txt']->setCompressedGZ(); +$p['file2.txt']->compress(Phar::GZ); $p['file3.txt'] = 'babyface'; $p['file3.txt']->setMetadata(42); $p->setStub("<?php -function __autoload($class) -{ - include 'phar://myphar.phar/' . str_replace('_', '/', $class) . '.php'; -} +spl_autoload_register(function (\$class) { + include 'phar://myphar.phar/' . str_replace('_', '/', \$class) . '.php'; +}); Phar::mapPhar('myphar.phar'); include 'phar://myphar.phar/startup.php'; __HALT_COMPILER();"); diff --git a/reference/phar/PharData/addFromString.xml b/reference/phar/PharData/addFromString.xml index 3430e8112d65..25dde7043394 100644 --- a/reference/phar/PharData/addFromString.xml +++ b/reference/phar/PharData/addFromString.xml @@ -66,7 +66,7 @@ try { $b = $a['path/to/file.txt']->getContent(); // to add contents from a stream handle for large files, use offsetSet() - $c = fopen('/path/to/hugefile.bin'); + $c = fopen('/path/to/hugefile.bin', 'rb'); $a['largefile.bin'] = $c; fclose($c); } catch (Exception $e) { diff --git a/reference/phar/PharFileInfo/isCompressed.xml b/reference/phar/PharFileInfo/isCompressed.xml index 3336afb57ba0..ab8ab31c8ce7 100644 --- a/reference/phar/PharFileInfo/isCompressed.xml +++ b/reference/phar/PharFileInfo/isCompressed.xml @@ -76,7 +76,7 @@ try { $p = new Phar('/path/to/my.phar', 0, 'my.phar'); $p['myfile.txt'] = 'hi'; $p['myfile2.txt'] = 'hi'; - $p['myfile2.txt']->setCompressedGZ(); + $p['myfile2.txt']->compress(Phar::GZ); $file = $p['myfile.txt']; $file2 = $p['myfile2.txt']; var_dump($file->isCompressed());