cURL wrapper
************

.[perex]
Pokročilý cURL wrapper usnadňují práci s "cURL":http://cz.php.net/curl

|* Verze | 0.6
|* Download | http://github.com/HosipLan/cURL-wrapper
|* Forum thread | http://forum.nette.org/cs/3054-curl-wrapper
|* Autor | Filip Procházka
|* Homepage | http://curl.kdyby.org/

Instalace
=========

Doplněk nepotřebuje žádnou instalaci, stačí jen rozbalit soubory ze složky `libs` z balíčku ke své aplikaci a naincludovat. V případě použítí RobotLoaderu se třídy includují automaticky.

Výchozí nastavení v config.ini
==============================

Wrapper umožňuje nastavení výchozích hodnot do vašeho configu, jako například výchozí hlavičky, složku pro cookies, cestu pro ukládání stažených souborů, nebo třeba protokol pro thread-safe ukládání [Nette\IO\SafeStream | doc:]

/-- code config
[common]
curl.cookieFile = %appDir%/temp/cookies.tmp
curl.downloadFolder = %appDir%/download
curl.followRedirects = True
curl.fileProtocol = safe
curl.userAgent = "Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.0.15) Gecko/2009102814 Firefox/3.0.15"
curl.headers.HTTP_ACCEPT = "text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5"
curl.headers.HTTP_ACCEPT_LANGUAGE = "cs,en-us;q=0.7,en;q=0.3"
curl.headers.HTTP_ACCEPT_ENCODING = "gzip,deflate"
curl.headers.HTTP_ACCEPT_CHARSET = "windows-1250,utf-8;q=0.7,*;q=0.7"
curl.headers.HTTP_KEEP_ALIVE = 300
curl.headers.HTTP_CONNECTION = "keep-alive"
\--


Příklady použití
===============

Základní inicializace
---------------------

Jelikož byl doplněk přepsán do php5.3 a změnilo se API, je nyní možné inicializovaat jedním z následujících způsobů

Bez konfigurace
/--php
$request = new Curl\Request();
\--

S adresou (v takovém případě se pak url vynechává ve funkcích `->get()`, `->post()`, ...)
/--php
$request = new Curl\Request("http://curl.kdyby.org/prevodnik.asm.zdrojak");
\--

S konfigurací
/--php
$config = Nette\Environment::getConfig('curl');
$config['downloadFolder'] = realpath("download");
$config['cookieFile'] = $config['downloadFolder'].'/cookies.tmp';

$request = new Curl\Request("http://curl.kdyby.org/prevodnik.asm.zdrojak", $config);
\--

Pozdější konfigurace
/--php
$config = Nette\Environment::getConfig('curl');
$config['downloadFolder'] = realpath("download");
$config['cookieFile'] = $config['downloadFolder'].'/cookies.tmp';

$request = new Curl\Request();
$request->configure($config);
\--

.[note]
Metodě `configure` je možné předat i pole


Inicializace a základní funkce
------------------------------

Inicializaci a jednoduchou žádost lze provést více způsoby, pokaždé však třída vrací objekt CurlResponse nebo v případě chyby vyhodí vyjímku CurlException

/--php
// první způsob
$test1 = new Curl\Request;
try {
	$odpoved = $test1->get("http://curl.kdyby.org/prevodnik.asm.zdrojak");

	echo $odpoved->getBody();
	var_dump($odpoved->getHeaders()); // vrací pole hlaviček
} catch ( Curl\CurlException $e ){
	echo $e->getMessage();
}

// druhý způsob
$test2 = new Curl\Request("http://curl.kdyby.org/prevodnik.asm.zdrojak");
try {
	$odpoved = $test2->get();

	echo $odpoved->getBody();
	var_dump($odpoved->getHeaders()); // vrací pole hlaviček
} catch ( Curl\CurlException $e ){
	echo $e->getMessage();
}
\--

.[caution]
Pokud specifikujete URL už v konstruktoru, bude wrapper ignorovat parametr url ve všech ostatních funkcích, tento parametr se potom vynechává při jejich volání. Místo `$curl->get($url, $query)` se volá jen `$curl->get($query)` pro resetování nebo nastavení jiné url se v tomto případě používá `$curl->setUrl($url)`

V balíčku jsou přibalené tři jednoduché testy, první je zjednodušeně předveden v ukázce inicializace, druhý je poslání POST požadavku

/-- php
$test = new Curl\Request("http://curl.kdyby.org/dump_post.php");

try {
	$odpoved =  $test->post(array(
		'var1' => 'Lorem ipsum dot sit amet',
		'var2' => 0,
		'var3' => 23,
		'var4' => True,
		'var5' => False,
	));

	echo $odpoved->getBody();
	var_dump($odpoved->getHeaders()); // vrací pole hlaviček
} catch ( Curl\CurlException $e ){
	echo $e->getMessage();
}
\--

Také je možné stahovat soubory pokud nadefinujete downloadFolder čili složku pro uložení stažených souborů

/-- php
$test = new Curl\Request("http://curl.kdyby.org/prevodnik.asm.zdrojak");
$test->setDownloadFolder(realpath('./download'));

try {
	$odpoved =  $test->download();

	var_dump($odpoved->getHeaders()); // vrací pole hlaviček

	// zde je možné získat cestu k souboru
	echo $odpoved->getRequest()->getDownloadPath();

	// nebo si rovnou otevřít stream
	$fp = $odpoved->openFile();

	echo fread($fp, $odpoved->getHeader('Content-Length'));

	$odpoved->closeFile();
} catch ( Curl\CurlException $e ){
	echo $e->getMessage();
}
\--

Pokud neuvedete v konstruktoru třídy url, můžete potom snadněji načíst větší množství adres, nebo poslat více požadavků na různé adresy
/-- php
$test = new Curl\Request;
try {
	$urls[] = "http://curl.kdyby.org/prevodnik.asm.zdrojak";
	$urls[] = "http://curl.kdyby.org/dump_post.php";

	foreach( $urls AS $url ){
		$odpoved = $test->get($url);

		echo $odpoved->getBody();
		var_dump($odpoved->getHeaders()); // vrací pole hlaviček
	}
} catch ( Curl\CurlException $e ){
	echo $e->getMessage();
}
\--

Typy HTTP požadavků
-------------------

Třída umožňuje poslat 6 typů HTTP požadavků

/-- php
$curl = new Curl\Request;

$url = "http://curl.kdyby.org/";

$odpoved1 = $curl->get($url, array(
	'var1' => 'value1',
	'var2' => 'value2'
)); # pošle žádost na http://curl.kdyby.org/?var1=value1&var2=value2

$odpoved2 = $curl->post($url, $post);
$odpoved3 = $curl->head($url, $query);
$odpoved4 = $curl->put($url, $query);
$odpoved5 = $curl->delete($url, $query);

# pokud nespecifikujete jméno souboru, wrapper se ho pokusí získat z url
$url = "http://curl.kdyby.org/prevodnik.asm.zdrojak";
$odpoved6 = $curl->download($url, 'moje_jmeno_souboru.asm');
\--

Není ovšem problém poslat vlastní typ http požadavku
/-- php
$odpoved = $curl->request('VAS_VLASTNI_TYP_ZADOSTI', $url, $query);
\--

Proxy
-----

Wrapper podporuje i proxy, čili je možné přidat libovolný počet proxy serverů a wrapper je zkouší tak dlouho dokud žádost přes jednu neprojde v pořádku v nastaveném timeoutu

/-- php
# poslední tři parametry jsou volitelné
$curl->addProxy('192.168.1.160', 3128 [, $username = Null [, $password = Null [, $timeout = 15]]]);
\--

Vlastní hlavičky
----------------

Hlavičky jde přidávat jednotlivě

/-- php
$curl->setHeader('Host', '12.345.678.90');
$curl->setHeader('Some-Custom-Header', 'Some Custom Value');
\--

nebo jako pole

/-- php
$curl->setHeaders(array(
	'Host' => '12.345.678.90',
	'Some-Custom-Header' => 'Some Custom Value'
));
\--

Nastavení vlastních možností žádosti
------------------------------------

Ve výchozím nastavení bude wrapper následovat přesměrování, takhle jdou zakázat
/-- php
$curl->setFollowRedirects(False);
\--

Můžete snadno nastavit referera nebo jméno prohlížeče. V třídě je pár přednastavených tzn. že nemusíte vypisovat celé jejich jméno

|* FireFox3 | `Mozilla/5.0 (Windows; U; Windows NT 5.1; pl; rv:1.9) Gecko/2008052906 Firefox/3.0`
|* GoogleBot | `Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)`
|* IE7 | `Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.0)`
|* Netscape | `Mozilla/4.8 [en] (Windows NT 6.0; U)`
|* Opera | `Opera/9.25 (Windows NT 6.0; U; en)`

/-- php
$curl->setReferer('http://google.com');
$curl->setUserAgent('FireFox3');
\--

Můžete nastavit, nebo změnit všechny volby jejichž seznam je na adrese [curl_setopt | php:].
Všechny z následujících způsobů budou fungovat

/-- php
$curl->setOption('AUTOREFERER', True);
$curl->setOption('autoreferer', True);
$curl->setOption('CURLOPT_AUTOREFERER', True);
$curl->setOption('curlopt_autoreferer', True);
\--

Nebo je můžete nastavit pomocí pole
/-- php
$curl->setOptions($array);
\--