From 788dd5d574eb9a50df3ce7891346c4b6ac3ea7b5 Mon Sep 17 00:00:00 2001
From: lacatoire <la.catoire@gmail.com>
Date: Tue, 9 Jun 2026 10:27:37 +0200
Subject: [PATCH] [Sync EN] Phar::setStub: Add a description of the $length
 parameter (#5592)

Refs: php/doc-en@d7056bd0948e3dd9316708247933026bd3d560b1
Closes: #322
---
 reference/phar/Phar/setStub.xml     | 199 ++++++++++++++++++++++++++++
 reference/phar/PharData/setStub.xml | 110 +++++++++++++++
 2 files changed, 309 insertions(+)
 create mode 100644 reference/phar/Phar/setStub.xml
 create mode 100644 reference/phar/PharData/setStub.xml

diff --git a/reference/phar/Phar/setStub.xml b/reference/phar/Phar/setStub.xml
new file mode 100644
index 000000000..4519c5a9b
--- /dev/null
+++ b/reference/phar/Phar/setStub.xml
@@ -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
+-->
diff --git a/reference/phar/PharData/setStub.xml b/reference/phar/PharData/setStub.xml
new file mode 100644
index 000000000..d622de21e
--- /dev/null
+++ b/reference/phar/PharData/setStub.xml
@@ -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
+-->