matroz Fri Mar 8 10:28:54 2002 EDT
Added files:
/phpdoc/he/functions curl.xml
Log:
started
]
Index: phpdoc/he/functions/curl.xml
+++ phpdoc/he/functions/curl.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- EN-Revision: 1.0 Maintainer: matty Status: working -->
<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">
<![CDATA[
<?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>
<methodsynopsis>
<type>int</type><methodname>curl_init</methodname>
<methodparam choice="opt"><type>string</type><parameter>
url
</parameter></methodparam>
</methodsynopsis>
<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">
<![CDATA[
<?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>
<methodsynopsis>
<type>bool</type><methodname>curl_setopt</methodname>
<methodparam><type>int</type><parameter>ch</parameter></methodparam>
<methodparam><type>string</type><parameter>option</parameter></methodparam>
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
</methodsynopsis>
<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 behavior 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-form-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
esta
