From 3cb7b87445efa64547ed5b2ef11590a1589e68b2 Mon Sep 17 00:00:00 2001
From: Christoph Michael Becker <cmb@php.net>
Date: Sat, 23 Jul 2016 13:16:11 +0000
Subject: [PATCH] Most image writing functions accept also a stream as second
 argument

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@339706 c90b9560-bf6c-de11-be94-00142212c4b1
---
 language-snippets.ent                   |  2 +-
 reference/image/functions/imagegd.xml   | 32 ++++++++++++++++++++++---
 reference/image/functions/imagegd2.xml  | 32 ++++++++++++++++++++++---
 reference/image/functions/imagegif.xml  | 32 ++++++++++++++++++++++---
 reference/image/functions/imagejpeg.xml | 15 ++++++++----
 reference/image/functions/imagepng.xml  | 11 +++++++--
 reference/image/functions/imagewbmp.xml | 30 +++++++++++++++++++++--
 reference/image/functions/imagewebp.xml | 29 ++++++++++++++++++++--
 reference/image/functions/imagexbm.xml  |  2 +-
 9 files changed, 164 insertions(+), 21 deletions(-)

diff --git a/language-snippets.ent b/language-snippets.ent
index 4b94647f79..9bdfda7931 100644
--- a/language-snippets.ent
+++ b/language-snippets.ent
@@ -554,7 +554,7 @@ own font identifiers registered with <function>imageloadfont</function>.
 
 <!ENTITY gd.source.width 'Source width.'>
 
-<!ENTITY gd.image.path 'The path to save the file to. If not set or &null;, the raw image stream will be outputted directly.'>
+<!ENTITY gd.image.path 'The path or an open stream resource (which is automatically being closed after this function returns) to save the file to. If not set or &null;, the raw image stream will be outputted directly.'>
 
 <!ENTITY gd.image.new 'Create a new image from file or URL'>
 
diff --git a/reference/image/functions/imagegd.xml b/reference/image/functions/imagegd.xml
index 53faad2ead..82a004605a 100644
--- a/reference/image/functions/imagegd.xml
+++ b/reference/image/functions/imagegd.xml
@@ -10,10 +10,10 @@
   <methodsynopsis>
    <type>bool</type><methodname>imagegd</methodname>
    <methodparam><type>resource</type><parameter>image</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>filename</parameter></methodparam>
+   <methodparam choice="opt"><type>mixed</type><parameter>to</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Outputs a GD image to the given <parameter>filename</parameter>. 
+   Outputs a GD image to the given <parameter>to</parameter>.
   </para>
  </refsect1>
  <refsect1 role="parameters">
@@ -22,7 +22,7 @@
    <variablelist>
     &gd.image.description;
     <varlistentry>
-     <term><parameter>filename</parameter></term>
+     <term><parameter>to</parameter></term>
      <listitem>
       <para>&gd.image.path;</para>
      </listitem>
@@ -36,6 +36,32 @@
    &return.success;
   </para>
  </refsect1>
+
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>5.4.0</entry>
+       <entry>
+        Added support for passing a stream <type>resource</type> to
+        <parameter>to</parameter>.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
diff --git a/reference/image/functions/imagegd2.xml b/reference/image/functions/imagegd2.xml
index 3f08c61e94..6b9fefbb0e 100644
--- a/reference/image/functions/imagegd2.xml
+++ b/reference/image/functions/imagegd2.xml
@@ -10,12 +10,12 @@
   <methodsynopsis>
    <type>bool</type><methodname>imagegd2</methodname>
    <methodparam><type>resource</type><parameter>image</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>filename</parameter></methodparam>
+   <methodparam choice="opt"><type>mixed</type><parameter>to</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>chunk_size</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>type</parameter><initializer>IMG_GD2_RAW</initializer></methodparam>
   </methodsynopsis>
   <para>
-   Outputs a GD2 image to the given <parameter>filename</parameter>. 
+   Outputs a GD2 image to the given <parameter>to</parameter>.
   </para>
  </refsect1>
  <refsect1 role="parameters">
@@ -24,7 +24,7 @@
    <variablelist>
     &gd.image.description;
     <varlistentry>
-     <term><parameter>filename</parameter></term>
+     <term><parameter>to</parameter></term>
      <listitem>
       <para>&gd.image.path;</para>
      </listitem>
@@ -56,6 +56,32 @@
    &return.success;
   </para>
  </refsect1>
+
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>5.4.0</entry>
+       <entry>
+        Added support for passing a stream <type>resource</type> to
+        <parameter>to</parameter>.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+
  <refsect1 role="examples">
  &reftitle.examples;
  <para>
diff --git a/reference/image/functions/imagegif.xml b/reference/image/functions/imagegif.xml
index 5d30cbfa4b..3976857702 100644
--- a/reference/image/functions/imagegif.xml
+++ b/reference/image/functions/imagegif.xml
@@ -10,11 +10,11 @@
   <methodsynopsis>
    <type>bool</type><methodname>imagegif</methodname>
    <methodparam><type>resource</type><parameter>image</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>filename</parameter></methodparam>
+   <methodparam choice="opt"><type>mixed</type><parameter>to</parameter></methodparam>
   </methodsynopsis>
   <para>
    <function>imagegif</function> creates the <acronym>GIF</acronym>
-   file in filename from the image <parameter>image</parameter>. The
+   file in <parameter>to</parameter> from the image <parameter>image</parameter>. The
    <parameter>image</parameter> argument is the return from the
    <function>imagecreate</function> or <literal>imagecreatefrom*</literal>
    function.
@@ -32,7 +32,7 @@
    <variablelist>
     &gd.image.description;
     <varlistentry>
-     <term><parameter>filename</parameter></term>
+     <term><parameter>to</parameter></term>
      <listitem>
       <para>&gd.image.path;</para>
      </listitem>
@@ -46,6 +46,32 @@
    &return.success;
   </para>
  </refsect1>
+
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>5.4.0</entry>
+       <entry>
+        Added support for passing a stream <type>resource</type> to
+        <parameter>to</parameter>.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
diff --git a/reference/image/functions/imagejpeg.xml b/reference/image/functions/imagejpeg.xml
index 1d82a51268..fad4ae7f81 100644
--- a/reference/image/functions/imagejpeg.xml
+++ b/reference/image/functions/imagejpeg.xml
@@ -10,7 +10,7 @@
   <methodsynopsis>
    <type>bool</type><methodname>imagejpeg</methodname>
    <methodparam><type>resource</type><parameter>image</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>filename</parameter></methodparam>
+   <methodparam choice="opt"><type>mixed</type><parameter>to</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>quality</parameter></methodparam>
   </methodsynopsis>
   <para>
@@ -24,7 +24,7 @@
    <variablelist>
     &gd.image.description;
     <varlistentry>
-     <term><parameter>filename</parameter></term>
+     <term><parameter>to</parameter></term>
      <listitem>
       <para>&gd.image.path;</para>
       <para>
@@ -120,7 +120,7 @@ imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);
 // Set the content type header - in this case image/jpeg
 header('Content-Type: image/jpeg');
 
-// Skip the filename parameter using NULL, then set the quality to 75%
+// Skip the to parameter using NULL, then set the quality to 75%
 imagejpeg($im, NULL, 75);
 
 // Free up memory
@@ -157,7 +157,14 @@ imagedestroy($im);
       <row>
        <entry>5.4.0</entry>
        <entry>
-        Disallowed passing an empty string to <parameter>filename</parameter> to
+        Added support for passing a stream <type>resource</type> to
+        <parameter>to</parameter>.
+       </entry>
+      </row>
+      <row>
+       <entry>5.4.0</entry>
+       <entry>
+        Disallowed passing an empty string to <parameter>to</parameter> to
         skip this argument.
        </entry>
       </row>
diff --git a/reference/image/functions/imagepng.xml b/reference/image/functions/imagepng.xml
index b8e5baa9f5..f9631a7504 100644
--- a/reference/image/functions/imagepng.xml
+++ b/reference/image/functions/imagepng.xml
@@ -10,7 +10,7 @@
   <methodsynopsis>
    <type>bool</type><methodname>imagepng</methodname>
    <methodparam><type>resource</type><parameter>image</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>filename</parameter></methodparam>
+   <methodparam choice="opt"><type>mixed</type><parameter>to</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>quality</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>filters</parameter></methodparam>
   </methodsynopsis>
@@ -25,7 +25,7 @@
    <variablelist>
     &gd.image.description;
     <varlistentry>
-     <term><parameter>filename</parameter></term>
+     <term><parameter>to</parameter></term>
      <listitem>
       <para>&gd.image.path;</para>
       <note>
@@ -78,6 +78,13 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>5.4.0</entry>
+       <entry>
+        Added support for passing a stream <type>resource</type> to
+        <parameter>to</parameter>.
+       </entry>
+      </row>
       <row>
        <entry>5.1.3</entry>
        <entry>
diff --git a/reference/image/functions/imagewbmp.xml b/reference/image/functions/imagewbmp.xml
index a5235f4d8c..a8435a7001 100644
--- a/reference/image/functions/imagewbmp.xml
+++ b/reference/image/functions/imagewbmp.xml
@@ -10,7 +10,7 @@
   <methodsynopsis>
    <type>bool</type><methodname>imagewbmp</methodname>
    <methodparam><type>resource</type><parameter>image</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>filename</parameter></methodparam>
+   <methodparam choice="opt"><type>mixed</type><parameter>to</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>foreground</parameter></methodparam>
   </methodsynopsis>
   <para>
@@ -24,7 +24,7 @@
    <variablelist>
     &gd.image.description;
     <varlistentry>
-     <term><parameter>filename</parameter></term>
+     <term><parameter>to</parameter></term>
      <listitem>
       <para>&gd.image.path;</para>
      </listitem>
@@ -48,6 +48,32 @@
    &return.success;
   </para>
  </refsect1>
+
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>5.4.0</entry>
+       <entry>
+        Added support for passing a stream <type>resource</type> to
+        <parameter>to</parameter>.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
diff --git a/reference/image/functions/imagewebp.xml b/reference/image/functions/imagewebp.xml
index ff37fe44e2..d86cb755ea 100644
--- a/reference/image/functions/imagewebp.xml
+++ b/reference/image/functions/imagewebp.xml
@@ -11,7 +11,7 @@
   <methodsynopsis>
    <type>bool</type><methodname>imagewebp</methodname>
    <methodparam><type>resource</type><parameter>image</parameter></methodparam>
-   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
+   <methodparam><type>mixed</type><parameter>to</parameter></methodparam>
   </methodsynopsis>
   <para>
    Outputs or save an WebP version of the given <parameter>image</parameter>. 
@@ -24,7 +24,7 @@
    <variablelist>
     &gd.image.description;
     <varlistentry>
-     <term><parameter>filename</parameter></term>
+     <term><parameter>to</parameter></term>
      <listitem>
       <para>&gd.image.path;</para>
      </listitem>
@@ -40,6 +40,31 @@
   </para>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>5.4.0</entry>
+       <entry>
+        Added support for passing a stream <type>resource</type> to
+        <parameter>to</parameter>.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
diff --git a/reference/image/functions/imagexbm.xml b/reference/image/functions/imagexbm.xml
index 2c3cae71d3..f19eb6912e 100644
--- a/reference/image/functions/imagexbm.xml
+++ b/reference/image/functions/imagexbm.xml
@@ -33,7 +33,7 @@
     <varlistentry>
      <term><parameter>filename</parameter></term>
      <listitem>
-      <para>&gd.image.path;</para>
+      <para>The path to save the file to. If not set or &null;, the raw image stream will be outputted directly.</para>
       <para>
        The <parameter>filename</parameter> (without the .xbm extension) is also
        used for the C identifiers of the <acronym>XBM</acronym>, whereby non