rfc:curl-file-upload

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
Last revisionBoth sides next revision
rfc:curl-file-upload [2013/01/07 06:36] – [References] stasrfc:curl-file-upload [2017/09/22 13:28] – external edit 127.0.0.1
Line 3: Line 3:
   * Date: 2013-01-06   * Date: 2013-01-06
   * Author: Stas Malyshev <stas@php.net>   * Author: Stas Malyshev <stas@php.net>
-  * Status: Under Discussion+  * Status: Implemented in PHP 5.5
   * First Published at: http://wiki.php.net/rfc/curl-file-upload   * First Published at: http://wiki.php.net/rfc/curl-file-upload
   * See also: https://bugs.php.net/bug.php?id=46439   * See also: https://bugs.php.net/bug.php?id=46439
 +  * Implementation: https://github.com/php/php-src/pull/255
  
 This RFC discusses improvement for CURL file uploading option. This RFC discusses improvement for CURL file uploading option.
- 
 ===== Introduction ===== ===== Introduction =====
  
Line 34: Line 34:
  
 The file given to CurlFile will not be opened/read until curl_setopt() call.  The file given to CurlFile will not be opened/read until curl_setopt() call. 
-===== CurlFile API =====+===== CURLFile API =====
  
 <code php> <code php>
-class CurlFile+class CURLFile
 { {
     /**     /**
Line 88: Line 88:
 } }
 </code> </code>
-===== Backward compatibility ===== 
  
-In order to assure orderly transition to the use of the new API, the proposal is in 5.5 to leave the @ option working, but make it produce E_DEPRECATED error referring the user to the use of the new API. In 5.6, @ option will be switched off by default, but can still be enabled by explicit curl_setopt setting, such as+Also, the functional API to creating CURLFile is provided by request:
  
 <code php> <code php>
-curl_setopt($curl_handleCURLOPT_UNSAFE_UPLOADtrue);+    /** 
 +     * Create CURLFile object 
 +     * @param string $name File name 
 +     * @param string $mimetype Mime type, optional 
 +     * @param string $postfilename Post filename, defaults to actual filename 
 +     */ 
 +    function curl_file_create($name$mimetype = ''$postfilename = '') 
 +    {}
 </code> </code>
  
-In future versions, this capability may be removed completely.+This will create a new ```CURLFile``` object just as ```new CURLFile()``` would. 
 +===== Backward compatibility =====
  
-===== Optional ===== +A new option is introduced: ''CURLOPT_SAFE_UPLOAD''. By default, in order to assure orderly transition to the use of the new APIthe proposal is in 5.5 to leave the option working,  but make it produce E_DEPRECATED error referring the user to the use of the new API. In order to disable it''CURLOPT_SAFE_UPLOAD'' can be used:
-  * If upstream cURL API permitswe could add in the future uploading files from string buffers, stream namesstream resources and such, which is now impossible with existing @-based API. The CurlFile API above will then be extended with required functions to support thesesuch as "setUploadData()", "setUploadStream()" etc. +
  
-  * For people that are not comfortable with "new" operatorwe could also add duplicate function-only API like+<code php> 
 +curl_setopt($curl_handleCURLOPT_SAFE_UPLOAD, true); 
 +</code> 
 + 
 +In 5.6, @ option will be switched off by default, but can still be enabled by explicit curl_setopt setting, such as
  
 <code php> <code php>
-$data['file'] = curl_file_upload($filename$mime);+curl_setopt($curl_handleCURLOPT_SAFE_UPLOAD, false);
 </code> </code>
 +
 +In future versions, this capability may be removed completely.
 +===== Optional =====
 +  * If upstream cURL API permits, we could add in the future uploading files from string buffers, stream names, stream resources and such, which is now impossible with existing @-based API. The CurlFile API above will then be extended with required functions to support these, such as "setUploadData()", "setUploadStream()" etc. 
  
    * It is possible to include validation of the file resource given in the constructor, so that appropriate error message can be produced if this file can not be read.     * It is possible to include validation of the file resource given in the constructor, so that appropriate error message can be produced if this file can not be read. 
Line 113: Line 127:
     * curl_setopt: http://php.net/manual/en/function.curl-setopt.php     * curl_setopt: http://php.net/manual/en/function.curl-setopt.php
     * Pull request: https://github.com/php/php-src/pull/255     * Pull request: https://github.com/php/php-src/pull/255
 +
 +===== Vote =====
 +
 +Voting ended on Monday, January 28th 2013. In order to pass, the requirement is 50%+1 vote, since PHP core language is not changed. The result is: **ACCEPTED**.
 +
 +<doodle 
 +title="Accept the CURLFile API as preferred solution for file uploads in CURL?" auth="stas" voteType="single" closed="True">
 +   * Yes
 +   * No
 +</doodle>
 +
 ===== Changelog ===== ===== Changelog =====
   * 2013-01-05 First draft   * 2013-01-05 First draft
 +  * 2013-01-06 Added pull req
 +  * 2013-01-07 Added CURLOPT_SAFE_UPLOAD description
 +  * 2013-01-12 Added curl_file_create()
  
  
rfc/curl-file-upload.txt · Last modified: 2018/07/03 19:16 by stas