curl_escape
This function URL encodes the given string according to » RFC 3986.
Parameters
A cURL handle returned by curl_init() .
Return Values
Returns escaped string or false on failure.
Changelog
Examples
Example #1 curl_escape() example
// Create a curl handle
$ch = curl_init ();
// Escape a string used as a GET parameter
$location = curl_escape ( $ch , ‘Hofbräuhaus / München’ );
// Result: Hofbr%C3%A4uhaus%20%2F%20M%C3%BCnchen
// Compose an URL with the escaped string
$url = «http://example.com/add_location.php?location= < $location >» ;
// Result: http://example.com/add_location.php?location=Hofbr%C3%A4uhaus%20%2F%20M%C3%BCnchen
// Send HTTP request and close the handle
curl_setopt ( $ch , CURLOPT_URL , $url );
curl_setopt ( $ch , CURLOPT_RETURNTRANSFER , true );
curl_exec ( $ch );
curl_close ( $ch );
?>
See Also
- curl_unescape() — Decodes the given URL encoded string
- urlencode() — URL-encodes string
- rawurlencode() — URL-encode according to RFC 3986
- » RFC 3986
User Contributed Notes 3 notes
Please someone add an example for escaping ampersands between parameters.
E.g. what is the correct approach for using this URL with curl:
https://example.com/?p1=1&p2=2&p3=3
This is not obvious, and needs explanation.
This function is strictly equivalent to rawurlencode().
Internally it uses curl_easy_escape() from libcurl, whose doc says: «This function converts the given input string to an URL encoded string (…). All input characters that are not a-z, A-Z, 0-9, ‘-‘, ‘.’, ‘_’ or ‘~’ are converted to their «URL escaped» version (%NN where NN is a two-digit hexadecimal number).»
- cURL Functions
- curl_close
- curl_copy_handle
- curl_errno
- curl_error
- curl_escape
- curl_exec
- curl_getinfo
- curl_init
- curl_multi_add_handle
- curl_multi_close
- curl_multi_errno
- curl_multi_exec
- curl_multi_getcontent
- curl_multi_info_read
- curl_multi_init
- curl_multi_remove_handle
- curl_multi_select
- curl_multi_setopt
- curl_multi_strerror
- curl_pause
- curl_reset
- curl_setopt_array
- curl_setopt
- curl_share_close
- curl_share_errno
- curl_share_init
- curl_share_setopt
- curl_share_strerror
- curl_strerror
- curl_unescape
- curl_upkeep
- curl_version
curl_setopt
true to disable the progress meter for cURL transfers.
Note:
PHP automatically sets this option to true , this should only be changed for debugging purposes.
The HTTP authentication method(s) to use. The options are: CURLAUTH_BASIC , CURLAUTH_DIGEST , CURLAUTH_GSSNEGOTIATE , CURLAUTH_NTLM , CURLAUTH_ANY , and CURLAUTH_ANYSAFE .
The bitwise | (or) operator can be used to combine more than one method. If this is done, cURL will poll the server to see what methods it supports and pick the best one.
CURLAUTH_ANY is an alias for CURLAUTH_BASIC | CURLAUTH_DIGEST | CURLAUTH_GSSNEGOTIATE | CURLAUTH_NTLM .
CURLAUTH_ANYSAFE is an alias for CURLAUTH_DIGEST | CURLAUTH_GSSNEGOTIATE | CURLAUTH_NTLM .
Bitmask of CURLPROTO_* values. If used, this bitmask limits what protocols libcurl may use in the transfer. This allows you to have a libcurl built to support a wide range of protocols but still limit specific transfers to only be allowed to use a subset of them. By default libcurl will accept all protocols it supports. See also CURLOPT_REDIR_PROTOCOLS .
Valid protocol options are: CURLPROTO_HTTP , CURLPROTO_HTTPS , CURLPROTO_FTP , CURLPROTO_FTPS , CURLPROTO_SCP , CURLPROTO_SFTP , CURLPROTO_TELNET , CURLPROTO_LDAP , CURLPROTO_LDAPS , CURLPROTO_DICT , CURLPROTO_FILE , CURLPROTO_TFTP , CURLPROTO_ALL
The SOCKS5 authentication method(s) to use. The options are: CURLAUTH_BASIC , CURLAUTH_GSSAPI , CURLAUTH_NONE .
The bitwise | (or) operator can be used to combine more than one method. If this is done, cURL will poll the server to see what methods it supports and pick the best one.
CURLAUTH_BASIC allows username/password authentication.
CURLAUTH_GSSAPI allows GSS-API authentication.
CURLAUTH_NONE allows no authentication.
Defaults to CURLAUTH_BASIC|CURLAUTH_GSSAPI . Set the actual username and password with the CURLOPT_PROXYUSERPWD option.
Note:
Your best bet is to not set this and let it use the default. Setting it to 2 or 3 is very dangerous given the known vulnerabilities in SSLv2 and SSLv3.
Note:
Your best bet is to not set this and let it use the default CURL_SSLVERSION_DEFAULT which will attempt to figure out the remote SSL protocol version.
A custom request method to use instead of «GET» or «HEAD» when doing a HTTP request. This is useful for doing «DELETE» or other, more obscure HTTP requests. Valid values are things like «GET» , «POST» , «CONNECT» and so on; i.e. Do not enter a whole HTTP request line here. For instance, entering «GET /index.html HTTP/1.0\r\n\r\n» would be incorrect.
Note:
Don’t do this without making sure the server supports the custom request method first.
The default protocol to use if the URL is missing a scheme name.
Set the name of the network interface that the DNS resolver should bind to. This must be an interface name (not an address).
Set the local IPv4 address that the resolver should bind to. The argument should contain a single numerical IPv4 address as a string.
Set the local IPv6 address that the resolver should bind to. The argument should contain a single numerical IPv6 address as a string.
Note:
Secure Remote Password (SRP) authentication for TLS provides mutual authentication if both sides have a shared secret. To use TLS-SRP, you must also set the CURLOPT_PROXY_TLSAUTH_USERNAME and CURLOPT_PROXY_TLSAUTH_PASSWORD options.
The secret password needed to use the private SSL key specified in CURLOPT_SSLKEY .
Note:
Since this option contains a sensitive password, remember to keep the PHP script it is contained within safe.
value should be an array for the following values of the option parameter:
Option Set value to Notes CURLOPT_CONNECT_TO Connect to a specific host and port instead of the URL’s host and port. Accepts an array of strings with the format HOST:PORT:CONNECT-TO-HOST:CONNECT-TO-PORT . Added in cURL 7.49.0. Available since PHP 7.0.7. CURLOPT_HTTP200ALIASES An array of HTTP 200 responses that will be treated as valid responses and not as errors. Added in cURL 7.10.3. CURLOPT_HTTPHEADER An array of HTTP header fields to set, in the format array(‘Content-type: text/plain’, ‘Content-length: 100’) CURLOPT_POSTQUOTE An array of FTP commands to execute on the server after the FTP request has been performed. CURLOPT_PROXYHEADER An array of custom HTTP headers to pass to proxies. Added in cURL 7.37.0. Available since PHP 7.0.7. CURLOPT_QUOTE An array of FTP commands to execute on the server prior to the FTP request. CURLOPT_RESOLVE Provide a custom address for a specific host and port pair. An array of hostname, port, and IP address strings, each element separated by a colon. In the format: array(«example.com:80:127.0.0.1») Added in cURL 7.21.3. value should be a stream resource (using fopen() , for example) for the following values of the option parameter:
Option Set value to CURLOPT_FILE The file that the transfer should be written to. The default is STDOUT (the browser window). CURLOPT_INFILE The file that the transfer should be read from when uploading. CURLOPT_STDERR An alternative location to output errors to instead of STDERR . CURLOPT_WRITEHEADER The file that the header part of the transfer is written to. A callback accepting five parameters. The first is the cURL resource, the second is the total number of bytes expected to be downloaded in this transfer, the third is the number of bytes downloaded so far, the fourth is the total number of bytes expected to be uploaded in this transfer, and the fifth is the number of bytes uploaded so far.
Note:
The callback is only called when the CURLOPT_NOPROGRESS option is set to false .
Return a non-zero value to abort the transfer. In which case, the transfer will set a CURLE_ABORTED_BY_CALLBACK error.
Other values:
Option Set value to CURLOPT_SHARE A result of curl_share_init() . Makes the cURL handle to use the data from the shared handle. Return Values
Returns true on success or false on failure.
Changelog
Version Description 8.0.0 handle expects a CurlHandle instance now; previously, a resource was expected. 7.3.15, 7.4.3 Introduced CURLOPT_HTTP09_ALLOWED . 7.3.0 Introduced CURLOPT_ABSTRACT_UNIX_SOCKET , CURLOPT_KEEP_SENDING_ON_ERROR , CURLOPT_PRE_PROXY , CURLOPT_PROXY_CAINFO , CURLOPT_PROXY_CAPATH , CURLOPT_PROXY_CRLFILE , CURLOPT_PROXY_KEYPASSWD , CURLOPT_PROXY_PINNEDPUBLICKEY , CURLOPT_PROXY_SSLCERT , CURLOPT_PROXY_SSLCERTTYPE , CURLOPT_PROXY_SSL_CIPHER_LIST , CURLOPT_PROXY_SSLKEY , CURLOPT_PROXY_SSLKEYTYPE , CURLOPT_PROXY_SSL_OPTIONS , CURLOPT_PROXY_SSL_VERIFYHOST , CURLOPT_PROXY_SSL_VERIFYPEER , CURLOPT_PROXY_SSLVERSION , CURLOPT_PROXY_TLSAUTH_PASSWORD , CURLOPT_PROXY_TLSAUTH_TYPE , CURLOPT_PROXY_TLSAUTH_USERNAME , CURLOPT_SOCKS5_AUTH , CURLOPT_SUPPRESS_CONNECT_HEADERS , CURLOPT_DISALLOW_USERNAME_IN_URL , CURLOPT_DNS_SHUFFLE_ADDRESSES , CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS , CURLOPT_HAPROXYPROTOCOL , CURLOPT_PROXY_TLS13_CIPHERS , CURLOPT_SSH_COMPRESSION , CURLOPT_TIMEVALUE_LARGE and CURLOPT_TLS13_CIPHERS . 7.0.7 Introduced CURL_HTTP_VERSION_2 , CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE , CURL_HTTP_VERSION_2TLS , CURL_REDIR_POST_301 , CURL_REDIR_POST_302 , CURL_REDIR_POST_303 , CURL_REDIR_POST_ALL , CURL_VERSION_KERBEROS5 , CURL_VERSION_PSL , CURL_VERSION_UNIX_SOCKETS , CURLAUTH_NEGOTIATE , CURLAUTH_NTLM_WB , CURLFTP_CREATE_DIR , CURLFTP_CREATE_DIR_NONE , CURLFTP_CREATE_DIR_RETRY , CURLHEADER_SEPARATE , CURLHEADER_UNIFIED , CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE , CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE , CURLMOPT_MAX_HOST_CONNECTIONS , CURLMOPT_MAX_PIPELINE_LENGTH , CURLMOPT_MAX_TOTAL_CONNECTIONS , CURLOPT_CONNECT_TO , CURLOPT_DEFAULT_PROTOCOL , CURLOPT_DNS_INTERFACE , CURLOPT_DNS_LOCAL_IP4 , CURLOPT_DNS_LOCAL_IP6 , CURLOPT_EXPECT_100_TIMEOUT_MS , CURLOPT_HEADEROPT , CURLOPT_LOGIN_OPTIONS , CURLOPT_PATH_AS_IS , CURLOPT_PINNEDPUBLICKEY , CURLOPT_PIPEWAIT , CURLOPT_PROXY_SERVICE_NAME , CURLOPT_PROXYHEADER , CURLOPT_SASL_IR , CURLOPT_SERVICE_NAME , CURLOPT_SSL_ENABLE_ALPN , CURLOPT_SSL_ENABLE_NPN , CURLOPT_SSL_FALSESTART , CURLOPT_SSL_VERIFYSTATUS , CURLOPT_STREAM_WEIGHT , CURLOPT_TCP_FASTOPEN , CURLOPT_TFTP_NO_OPTIONS , CURLOPT_UNIX_SOCKET_PATH , CURLOPT_XOAUTH2_BEARER , CURLPROTO_SMB , CURLPROTO_SMBS , CURLPROXY_HTTP_1_0 , CURLSSH_AUTH_AGENT and CURLSSLOPT_NO_REVOKE . Examples
Example #1 Initializing a new cURL session and fetching a web page
// create a new cURL resource
$ch = curl_init ();// set URL and other appropriate options
curl_setopt ( $ch , CURLOPT_URL , «http://www.example.com/» );
curl_setopt ( $ch , CURLOPT_HEADER , false );// grab URL and pass it to the browser
curl_exec ( $ch );// close cURL resource, and free up system resources
curl_close ( $ch );
?>Notes
Note:
Passing an array to CURLOPT_POSTFIELDS will encode the data as multipart/form-data, while passing a URL-encoded string will encode the data as application/x-www-form-urlencoded.
See Also