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:03] – [Changelog] 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 33: Line 33:
 The curl API will be modified to look for objects of type CurlFile and treat them as entries with @ were previously treated.  The curl API will be modified to look for objects of type CurlFile and treat them as entries with @ were previously treated. 
  
-===== CurlFile API =====+The file given to CurlFile will not be opened/read until curl_setopt() call.  
 +===== CURLFile API =====
  
 <code php> <code php>
-class CurlFile+class CURLFile
 { {
     /**     /**
Line 87: Line 88:
 } }
 </code> </code>
 +
 +Also, the functional API to creating CURLFile is provided by request:
 +
 +<code php>
 +    /**
 +     * 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>
 +
 +This will create a new ```CURLFile``` object just as ```new CURLFile()``` would.
 ===== Backward compatibility ===== ===== 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+A new option is introduced: ''CURLOPT_SAFE_UPLOAD''. By default, 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 order to disable it''CURLOPT_SAFE_UPLOAD'' can be used:
  
 <code php> <code php>
-curl_setopt($curl_handle, CURLOPT_UNSAFE_UPLOAD, true);+curl_setopt($curl_handle, CURLOPT_SAFE_UPLOAD, true);
 </code> </code>
  
-In future versionsthis capability may be removed completely.+In 5.6@ option will be switched off by default, but can still be enabled by explicit curl_setopt setting, such as: 
  
 +<code php>
 +curl_setopt($curl_handle, CURLOPT_SAFE_UPLOAD, false);
 +</code>
 +
 +In future versions, this capability may be removed completely.
 ===== Optional ===== ===== 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. +  * 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