mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-19 02:18:56 +00:00
d523e78ea9
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@34204 c90b9560-bf6c-de11-be94-00142212c4b1
547 lines
18 KiB
XML
547 lines
18 KiB
XML
<reference id="ref.curl">
|
|
<title>CURL, Client URL Library Functions</title>
|
|
<titleabbrev>CURL</titleabbrev>
|
|
|
|
<partintro id="curl.partintro">
|
|
<para>
|
|
PHP supports libcurl, a library, created by Daniel Stenberg, that
|
|
allows you to connect and communicate to many different types of
|
|
servers with many different types of protocols. libcurl currently
|
|
supports the http, https, ftp, gopher, telnet, dict, file, and
|
|
ldap protocols. libcurl also supports HTTPS certificates, HTTP
|
|
POST, HTTP PUT, FTP uploading (this can also be done with PHP's
|
|
ftp extension), HTTP form based upload, proxies, cookies and
|
|
user+password authentication.
|
|
</para>
|
|
<para>
|
|
In order to use the CURL functions you need to install the <ulink
|
|
url="&url.curl;">CURL</ulink> package. PHP requires that you use
|
|
CURL 7.0.2-beta or higher. PHP will not work with any version of
|
|
CURL below version 7.0.2-beta.
|
|
</para>
|
|
<para>
|
|
To use PHP's CURL support you must also compile PHP <option
|
|
role="configure">--with-curl[=DIR]</option> where DIR is the
|
|
location of the directory containing the lib and include
|
|
directories. In the "include" directory there should be a folder
|
|
named "curl" which should contain the easy.h and curl.h files.
|
|
There should be a file named "libcurl.a" located in the "lib"
|
|
directory.
|
|
</para>
|
|
<para>
|
|
These functions have been added in PHP 4.0.2.
|
|
</para>
|
|
<para>
|
|
Once you've compiled PHP with CURL support, you can begin using
|
|
the curl functions. The basic idea behind the CURL functions is
|
|
that you initialize a CURL session using the
|
|
<function>curl_init</function>, then you can set all your
|
|
options for the transfer via the <function>curl_exec</function>
|
|
and then you finish off your session using the
|
|
<function>curl_close</function>. Here is an example that uses
|
|
the CURL functions to fetch the PHP homepage into a file:
|
|
<example>
|
|
<title>Using PHP's CURL module to fetch the PHP homepage</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
|
|
$ch = curl_init ("http://www.php.net/");
|
|
$fp = fopen ("php_homepage.txt", "w");
|
|
|
|
curl_setopt ($ch, CURLOPT_FILE, $fp);
|
|
curl_setopt ($ch, CURLOPT_HEADER, 0);
|
|
|
|
curl_exec ($ch);
|
|
curl_close ($ch);
|
|
fclose ($fp);
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</partintro>
|
|
|
|
<refentry id="function.curl-init">
|
|
<refnamediv>
|
|
<refname>curl_init</refname>
|
|
<refpurpose>Initialize a CURL session</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int
|
|
<function>curl_init</function>
|
|
</funcdef>
|
|
<paramdef>string
|
|
<parameter>
|
|
<optional>url</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
The <function>curl_init</function> will initialize a new session
|
|
and return a CURL handle for use with the
|
|
<function>curl_setopt</function>, <function>curl_exec</function>,
|
|
and <function>curl_close</function> functions. If the optional
|
|
<parameter>url</parameter> parameter is supplied then the
|
|
CURLOPT_URL option will be set to the value of the parameter.
|
|
You can manually set this using the
|
|
<function>curl_setopt</function> function.
|
|
<example>
|
|
<title>
|
|
Initializing a new CURL session and fetching a webpage
|
|
</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
$ch = curl_init();
|
|
|
|
curl_setopt ($ch, CURLOPT_URL, "http://www.zend.com/");
|
|
curl_setopt ($ch, CURLOPT_HEADER, 0);
|
|
|
|
curl_exec ($ch);
|
|
|
|
curl_close ($ch);
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also: <function>curl_close</function>,
|
|
<function>curl_setopt</function>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.curl-setopt">
|
|
<refnamediv>
|
|
<refname>curl_setopt</refname>
|
|
<refpurpose>Set an option for a CURL transfer</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool
|
|
<function>curl_setopt</function>
|
|
</funcdef>
|
|
<paramdef>int
|
|
<parameter>ch</parameter>
|
|
</paramdef>
|
|
<paramdef>string
|
|
<parameter>option</parameter>
|
|
</paramdef>
|
|
<paramdef>mixed
|
|
<parameter>value</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
The <function>curl_setopt</function> function will set options
|
|
for a CURL session identified by the <parameter>ch</parameter>
|
|
parameter. The <parameter>option</parameter> parameter is the
|
|
option you want to set, and the <parameter>value</parameter> is
|
|
the value of the option given by the
|
|
<parameter>option</parameter>.
|
|
</para>
|
|
<para>
|
|
The <parameter>value</parameter> should be a long for the
|
|
following options (specified in the <parameter>option</parameter>
|
|
parameter):
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_INFILESIZE</parameter>: When you are
|
|
uploading a file to a remote site, this option should be used
|
|
to tell PHP what the expected size of the infile will be.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_VERBOSE</parameter>: Set this option to a
|
|
non-zero value if you want CURL to report everything that is
|
|
happening.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_HEADER</parameter>: Set this option to a
|
|
non-zero value if you want the header to be included in the
|
|
output.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<parameter>CURLOPT_NOPROGRESS</parameter>: Set this option to
|
|
a non-zero value if you don't want PHP to display a progress
|
|
meter for CURL transfers
|
|
<note>
|
|
<simpara>
|
|
PHP automatically sets this option to a non-zero parameter,
|
|
this should only be changed for debugging purposes.
|
|
</simpara>
|
|
</note>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_NOBODY</parameter>: Set this option to a
|
|
non-zero value if you don't want the body included with the
|
|
output.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_FAILONERROR</parameter>: Set this option to
|
|
a non-zero value if you want PHP to fail silently if the HTTP
|
|
code returned is greater than 300. The default behaviour is
|
|
to return the page normally, ignoring the code.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_UPLOAD</parameter>: Set this option to a
|
|
non-zero value if you want PHP to prepare for an upload.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_POST</parameter>: Set this option to a
|
|
non-zero value if you want PHP to do a regular HTTP POST.
|
|
This POST is a normal application/x-www-from-urlencoded kind,
|
|
most commonly used by HTML forms.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_FTPLISTONLY</parameter>: Set this option to
|
|
a non-zero value and PHP will just list the names of an FTP
|
|
directory.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_FTPAPPEND</parameter>: Set this option to a
|
|
non-zero value and PHP will append to the remote file instead
|
|
of overwriting it.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_NETRC</parameter>: Set this option to a
|
|
non-zero value and PHP will scan your ~./netrc file to find
|
|
your username and password for the remote site that you're
|
|
establishing a connection with.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_FOLLOWLOCATION</parameter>: Set this option
|
|
to a non-zero value to follow any "Location: " header that the
|
|
server sends as a part of the HTTP header (note this is
|
|
recursive, PHP will follow as many "Location: " headers that
|
|
it is sent.)
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_PUT</parameter>: Set this option a non-zero
|
|
value to HTTP PUT a file. The file to PUT must be set with
|
|
the CURLOPT_INFILE and CURLOPT_INFILESIZE.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_MUTE</parameter>: Set this option to a
|
|
non-zero value and PHP will be completely silent with regards
|
|
to the CURL functions.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_TIMEOUT</parameter>: Pass a long as a
|
|
parameter that contains the maximum time, in seconds, that
|
|
you'll allow the curl functions to take.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_LOW_SPEED_LIMIT</parameter>: Pass a long as
|
|
a parameter that contains the transfer speed in bytes per
|
|
second that the transfer should be below during
|
|
CURLOPT_LOW_SPEED_TIME seconds for PHP to consider it too slow
|
|
and abort.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_LOW_SPEED_TIME</parameter>: Pass a long as
|
|
a parameter that contains the time in seconds that the
|
|
transfer should be below the CURLOPT_LOW_SPEED_LIMIT for PHP
|
|
to consider it too slow and abort.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_RESUME_FROM</parameter>: Pass a long as a
|
|
parameter that contains the offset, in bytes, that you want
|
|
the transfer to start from.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_SSLVERSION</parameter>: Pass a long as a
|
|
parameter that contains the SSL version (2 or 3) to use. By
|
|
default PHP will try and determine this by itself, although,
|
|
in some cases you must set this manually.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_TIMECONDITION</parameter>: Pass a long as a
|
|
parameter that defines how the CURLOPT_TIMEVALUE is treated.
|
|
You can set this parameter to TIMECOND_IFMODSINCE or
|
|
TIMECOND_ISUNMODSINCE. This is a HTTP-only feature.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_TIMEVALUE</parameter>: Pass a long as a
|
|
parameter that is the time in seconds since January 1st, 1970.
|
|
The time will be used as specified by the CURLOPT_TIMEVALUE
|
|
option, or by default the TIMECOND_IFMODSINCE will be used.
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
The <parameter>value</parameter> parameter should be a string for
|
|
the following values of the <parameter>option</parameter>
|
|
parameter:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_URL</parameter>: This is the URL that you
|
|
want PHP to fetch. You can also set this option when
|
|
initializing a session with the <function>curl_init</function>
|
|
function.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_USERPWD</parameter>: Pass a string
|
|
formatted in the [username]:[password] manner, for PHP to use
|
|
for the connection. connection.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_PROXYUSERPWD</parameter>: Pass a string
|
|
formatted in the [username]:[password] format for connection
|
|
to the HTTP proxy.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_RANGE</parameter>: Pass the specified range
|
|
you want. It should be in the "X-Y" format, where X or Y may
|
|
be left out. The HTTP transfers also support several
|
|
intervals, seperated with commas as in X-Y,N-M.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_POSTFIELDS</parameter>: Pass a string
|
|
containing the full data to post in an HTTP "POST" operation.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_REFERER</parameter>: Pass a string
|
|
containing the "referer" header to be used in an HTTP request.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_USERAGENT</parameter>: Pass a string
|
|
containing the "user-agent" header to be used in an HTTP
|
|
request.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_FTPPORT</parameter>: Pass a string
|
|
containing the which will be used to get the IP address to use
|
|
for the ftp "POST" instruction. The POST instruction tells
|
|
the remote server to connect to our specified IP address. The
|
|
string may be a plain IP address, a hostname, a network
|
|
interface name (under UNIX), or just a plain '-' to use the
|
|
systems default IP address.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_COOKIE</parameter>: Pass a string
|
|
containing the content of the cookie to be set in the HTTP
|
|
header.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_SSLCERT</parameter>: Pass a string
|
|
containing the filename of PEM formatted certificate.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_SSLCERTPASSWD</parameter>: Pass a string
|
|
containing the password required to use the CURLOPT_SSLCERT
|
|
certificate.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_COOKIEFILE</parameter>: Pass a string
|
|
containing the name of the file containing the cookiee data.
|
|
The cookie file can be in Netscape format, or just plain
|
|
HTTP-style headers dumped into a file.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<parameter>CURLOPT_CUSTOMREQUEST</parameter>: Pass a string to
|
|
be used instead of GET or HEAD when doing an HTTP request.
|
|
This is useful for doing DELETE or another, more obscure, HTTP
|
|
request.
|
|
<note>
|
|
<simpara>
|
|
Don't do this without making sure your server supports the
|
|
command first.
|
|
</simpara>
|
|
</note>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
The following options expect a file descriptor that is obtained
|
|
by using the <function>fopen</function> function:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_FILE</parameter>: The file where the output
|
|
of your transfer should be placed, the default is STDOUT.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_INFILE</parameter>: The file where the
|
|
input of your transfer comes from.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_WRITEHEADER</parameter>: The file to write
|
|
the header part of the output into.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>CURLOPT_STDERR</parameter>: The file to write
|
|
errors to instead of stderr.
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.curl-exec">
|
|
<refnamediv>
|
|
<refname>curl_exec</refname>
|
|
<refpurpose>Perform a CURL session</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool
|
|
<function>curl_exec</function>
|
|
</funcdef>
|
|
<paramdef>int
|
|
<parameter>ch</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function is should be called after you initialize a CURL
|
|
session and all the options for the session are set. Its purpose
|
|
is simply to execute the predefined CURL session (given by the
|
|
<parameter>ch</parameter>).
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.curl-close">
|
|
<refnamediv>
|
|
<refname>curl_close</refname>
|
|
<refpurpose>Close a CURL session</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void
|
|
<function>curl_close</function>
|
|
</funcdef>
|
|
<paramdef>int
|
|
<parameter>ch</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This functions closes a CURL session and frees all ressources.
|
|
The CURL handle, <parameter>ch</parameter>, is also deleted.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.curl-version">
|
|
<refnamediv>
|
|
<refname>curl_version</refname>
|
|
<refpurpose>Return the current CURL version</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string
|
|
<function>curl_version</function>
|
|
</funcdef>
|
|
<void/>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
The <function>curl_version</function> function returns a string
|
|
containing the current CURL version.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
</reference>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../../manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
-->
|