[DOC-CVS] [doc-en] master: Phar::setStub: Add a description of the `$length` parameter (#5592)

Author: Mikhail Alferov (mmalferov)
Committer: GitHub (web-flow)
Pusher: jordikroon
Date: 2026-06-08T13:42:45+02:00

Commit: https://github.com/php/doc-en/commit/d7056bd0948e3dd9316708247933026bd3d560b1
Raw diff: https://github.com/php/doc-en/commit/d7056bd0948e3dd9316708247933026bd3d560b1.diff

Phar::setStub: Add a description of the `$length` parameter (#5592)

* setStub.xml Add a description of the `$length` parameter

Co-authored-by: Louis-Arnaud <[email protected]>
Co-authored-by: Jordi Kroon <[email protected]>

Changed paths:
  M  reference/phar/Phar/setStub.xml
  M  reference/phar/PharData/setStub.xml


Diff:

diff --git a/reference/phar/Phar/setStub.xml b/reference/phar/Phar/setStub.xml
index 240d34dce6e6..84b7598a8c1d 100644
--- a/reference/phar/Phar/setStub.xml
+++ b/reference/phar/Phar/setStub.xml
@@ -14,7 +14,6 @@
   </methodsynopsis>
   &phar.write;
 
-
   <para>
    This method is used to add a PHP bootstrap loader stub to a new Phar archive, or
    to replace the loader stub in an existing Phar archive.
@@ -22,14 +21,20 @@
   <para>
    The loader stub for a Phar archive is used whenever an archive is included directly
    as in this example:
-  </para>
-  <programlisting role="php">
-   <![CDATA[
+   <programlisting role="php">
+    <![CDATA[
 <?php
 include 'myphar.phar';
 ?>
-   ]]>
-  </programlisting>
+    ]]>
+   </programlisting>
+   or by simple execution:
+   <screen>
+    <![CDATA[
+php myphar.phar
+    ]]>
+   </screen>
+  </para>
   <para>
    The loader is not accessed when including a file through the <literal>phar</literal>
    stream wrapper like so:
@@ -60,9 +65,16 @@ include 'phar://myphar.phar/somefile.php';
     <varlistentry>
      <term><parameter>length</parameter></term>
      <listitem>
-      <para>
-       
-      </para>
+      <simpara>
+       Length of <parameter>stub</parameter> in bytes.
+      </simpara>
+      <warning>
+       <simpara>
+        Passing the <parameter>length</parameter> argument with a &resource; in
+        the first argument is <emphasis>DEPRECATED</emphasis> as of PHP 8.3.0.
+        Use <literal>$phar->setStub(stream_get_contents($resource))</literal> instead.
+       </simpara>
+      </warning>
      </listitem>
     </varlistentry>
    </variablelist>
@@ -123,12 +135,14 @@ include 'phar://myphar.phar/somefile.php';
     <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';
diff --git a/reference/phar/PharData/setStub.xml b/reference/phar/PharData/setStub.xml
index e6ac8624c47a..0b7c38ae0ef7 100644
--- a/reference/phar/PharData/setStub.xml
+++ b/reference/phar/PharData/setStub.xml
@@ -27,18 +27,18 @@
     <varlistentry>
      <term><parameter>stub</parameter></term>
      <listitem>
-      <para>
-       A string or an open stream handle to use as the executable stub for this
-       phar archive.  This parameter is ignored.
-      </para>
+      <simpara>
+       Formally, a string or an open stream handle to use as the executable stub for this
+       phar archive. This parameter is ignored.
+      </simpara>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>length</parameter></term>
      <listitem>
-      <para>
-       
-      </para>
+      <simpara>
+       <parameter>stub</parameter> in bytes. This parameter is ignored.
+      </simpara>
      </listitem>
     </varlistentry>
    </variablelist>