php-doc-en/reference/phar/Phar/compress.xml
Máté Kocsis 28046efaba
Generate ext/phar methodsynopsis based on stubs
Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>

Closes GH-626.
2021-09-03 14:35:53 +02:00

171 lines
5.5 KiB
XML

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="phar.compress" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>Phar::compress</refname>
<refpurpose>Compresses the entire Phar archive using Gzip or Bzip2 compression</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type class="union"><type>Phar</type><type>null</type></type><methodname>Phar::compress</methodname>
<methodparam><type>int</type><parameter>compression</parameter></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>extension</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
&phar.write;
<para>
For tar-based and phar-based phar archives, this method compresses the entire archive using
gzip compression or bzip2 compression. The resulting file can be processed with the
gunzip command/bunzip command, or accessed directly and transparently with the Phar
extension.
</para>
<para>
For Zip-based phar archives, this method fails with an exception.
The <link linkend="ref.zlib">zlib</link> extension must be enabled to compress
with gzip compression, the <link linkend="ref.bzip2">bzip2</link> extension must be
enabled in order to compress with bzip2 compression.
As with all functionality that modifies the contents of a phar, the
<link linkend="ini.phar.readonly">phar.readonly</link> INI variable must be off
in order to succeed.
</para>
<para>
In addition, this method automatically renames the archive, appending <literal>.gz</literal>,
<literal>.bz2</literal> or removing the extension if passed <literal>Phar::NONE</literal> to
remove compression. Alternatively, a file extension may be specified with the second
parameter.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>compression</parameter></term>
<listitem>
<para>
Compression must be one of <literal>Phar::GZ</literal>,
<literal>Phar::BZ2</literal> to add compression, or <literal>Phar::NONE</literal>
to remove compression.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>extension</parameter></term>
<listitem>
<para>
By default, the extension is <literal>.phar.gz</literal>
or <literal>.phar.bz2</literal> for compressing phar archives, and
<literal>.phar.tar.gz</literal> or <literal>.phar.tar.bz2</literal> for
compressing tar archives. For decompressing, the default file extensions
are <literal>.phar</literal> and <literal>.phar.tar</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a <classname>Phar</classname> object, or &null; on failure.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
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>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>8.0.0</entry>
<entry>
<parameter>extension</parameter> is now nullable.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>Phar::compress</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p1 = $p->compress(Phar::GZ); // copies to /path/to/my.phar.gz
$p2 = $p->compress(Phar::BZ2); // copies to /path/to/my.phar.bz2
$p3 = $p2->compress(Phar::NONE); // exception: /path/to/my.phar already exists
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>PharFileInfo::getCompressedSize</function></member>
<member><function>PharFileInfo::isCompressed</function></member>
<member><function>PharFileInfo::compress</function></member>
<member><function>PharFileInfo::decompress</function></member>
<member><function>PharData::compress</function></member>
<member><function>Phar::canCompress</function></member>
<member><function>Phar::isCompressed</function></member>
<member><function>Phar::decompress</function></member>
<member><function>Phar::getSupportedCompression</function></member>
<member><function>Phar::compressFiles</function></member>
<member><function>Phar::decompressFiles</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->