Skip to content

[Sync EN] Phar::setStub: Add a description of the $length parameter (#5592) #323

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lacatoire wants to merge 1 commit into
base: master
Choose a base branch
from
+309 −0
Open

[Sync EN] Phar::setStub: Add a description of the $length parameter (#5592) #323

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
199 changes: 199 additions & 0 deletions reference/phar/Phar/setStub.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,199 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: d7056bd0948e3dd9316708247933026bd3d560b1 Maintainer: lacatoire Status: ready -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="phar.setstub">
<refnamediv>
<refname>Phar::setStub</refname>
<refpurpose>Setzt den PHP-Loader oder Bootstrap-Stub eines Phar-Archivs</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis role="Phar">
<modifier>public</modifier> <type>true</type><methodname>Phar::setStub</methodname>
<methodparam><type class="union"><type>resource</type><type>string</type></type><parameter>stub</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>length</parameter><initializer>-1</initializer></methodparam>
</methodsynopsis>
&phar.write;

<para>
Diese Methode wird verwendet, um einem neuen Phar-Archiv einen PHP-Bootstrap-Loader-Stub
hinzuzufügen oder um den Loader-Stub in einem bestehenden Phar-Archiv zu ersetzen.
</para>
<para>
Der Loader-Stub eines Phar-Archivs wird immer dann verwendet, wenn ein Archiv direkt
eingebunden wird, wie in diesem Beispiel:
<programlisting role="php">
<![CDATA[
<?php
include 'myphar.phar';
?>
]]>
</programlisting>
oder durch einfache Ausführung:
<screen>
<![CDATA[
php myphar.phar
]]>
</screen>
</para>
<para>
Der Loader wird nicht verwendet, wenn eine Datei über den <literal>phar</literal>
Stream-Wrapper eingebunden wird, wie hier:
</para>
<programlisting role="php">
<![CDATA[
<?php
include 'phar://myphar.phar/somefile.php';
?>
]]>
</programlisting>

</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>stub</parameter></term>
<listitem>
<para>
Eine Zeichenkette oder ein offenes Stream-Handle, das als ausführbarer Stub für
dieses Phar-Archiv verwendet werden soll.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>length</parameter></term>
<listitem>
<simpara>
Länge des <parameter>stub</parameter> in Bytes.
</simpara>
<warning>
<simpara>
Die Übergabe des Arguments <parameter>length</parameter> mit einer &resource;
im ersten Argument ist seit PHP 8.3.0 <emphasis>VERALTET</emphasis>.
Stattdessen sollte <literal>$phar->setStub(stream_get_contents($resource))</literal>
verwendet werden.
</simpara>
</warning>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
&return.true.always;
</simpara>
</refsect1>

<refsect1 role="errors">
&reftitle.errors;
<para>
Es wird eine <classname>UnexpectedValueException</classname> ausgelöst, wenn
<link linkend="ini.phar.readonly">phar.readonly</link> in der php.ini
aktiviert ist.
Es wird eine <classname>PharException</classname> ausgelöst, wenn beim Schreiben
der Änderungen auf die Festplatte Probleme auftreten.
</para>
</refsect1>

<refsect1 role="changelog">
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
&return.type.true.84;
<row>
<entry>8.3.0</entry>
<entry>
Der Aufruf von <methodname>Phar::setStub</methodname> mit einer
<type>resource</type> und einem <parameter>length</parameter>
ist nun veraltet. Solche Aufrufe sollten ersetzt werden durch:
<code>$phar->setStub(stream_get_contents($resource));</code>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Ein <function>Phar::setStub</function>-Beispiel</title>
<para>
</para>
<programlisting role="php">
<![CDATA[
<?php
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['a.php'] = '<?php var_dump("Hello");';
$p->setStub('<?php var_dump("First"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>');
include 'phar://brandnewphar.phar/a.php';
var_dump($p->getStub());
$p['b.php'] = '<?php var_dump("World");';
$p->setStub('<?php var_dump("Second"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>');
include 'phar://brandnewphar.phar/b.php';
var_dump($p->getStub());
} catch (Exception $e) {
echo 'Write operations failed on brandnewphar.phar: ', $e;
}
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
string(5) "Hello"
string(82) "<?php var_dump("First"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>"
string(5) "World"
string(83) "<?php var_dump("Second"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>"
]]>
</screen>
</example>
</para>
</refsect1>

<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>Phar::getStub</function></member>
<member><function>Phar::createDefaultStub</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
-->
110 changes: 110 additions & 0 deletions reference/phar/PharData/setStub.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: d7056bd0948e3dd9316708247933026bd3d560b1 Maintainer: lacatoire Status: ready -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="phardata.setstub">
<refnamediv>
<refname>PharData::setStub</refname>
<refpurpose>Dummy-Funktion (Phar::setStub ist für PharData nicht gültig)</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis role="PharData">
<modifier>public</modifier> <type>true</type><methodname>PharData::setStub</methodname>
<methodparam><type class="union"><type>resource</type><type>string</type></type><parameter>stub</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>length</parameter><initializer>-1</initializer></methodparam>
</methodsynopsis>


<para>
Nicht ausführbare tar-/zip-Archive können keinen Stub haben, daher löst diese Methode
einfach eine Exception aus.
</para>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>stub</parameter></term>
<listitem>
<simpara>
Formal eine Zeichenkette oder ein offenes Stream-Handle, das als ausführbarer Stub für
dieses Phar-Archiv verwendet werden soll. Dieser Parameter wird ignoriert.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>length</parameter></term>
<listitem>
<simpara>
<parameter>stub</parameter> in Bytes. Dieser Parameter wird ignoriert.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>

</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
&return.true.always;
</simpara>
</refsect1>

<refsect1 role="errors">
&reftitle.errors;
<para>
Löst bei allen Methodenaufrufen eine <classname>PharException</classname> aus
</para>
</refsect1>

<refsect1 role="changelog">
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
&return.type.true.84;
</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>Phar::setStub</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
-->
Loading