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
rfc:curl-file-upload [2013/01/06 05:06] – [CurlFile proposal] stasrfc:curl-file-upload [2018/07/03 19:16] (current) stas
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 19: Line 19:
 </code> </code>
  
-This API is both invonvenient and insecure, it is impossible to send data starting with '@' to the POST, and any user data that is being re-sent via cURL need to be sanitized so that the data value does not start with @. In general, in-bound signalling usually vulnerable to all sorts of injections and better not done in this way.+This API is both inconvenient and insecure, it is impossible to send data starting with '@' to the POST, and any user data that is being re-sent via cURL need to be sanitized so that the data value does not start with @. In general, in-bound signalling usually vulnerable to all sorts of injections and better not done in this way.
  
 ===== CurlFile proposal ===== ===== CurlFile proposal =====
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 buffersstream 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 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>
  
-But currently I do not think it is necessary+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. 
 +   
 ===== References ===== ===== References =====
     * CURL form API: http://curl.haxx.se/libcurl/c/curl_formadd.html     * CURL form API: http://curl.haxx.se/libcurl/c/curl_formadd.html
     * 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
 +
 +===== 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