nyx-solutions / yii2-nyx-curl
Yii2 NYX cUrl
Requires
- php: >=8.1.0 <8.2
- nyx-solutions/yii2-nyx: ~5.0.0
- nyx-solutions/yii2-nyx-helpers: ~5.0.0
- php-curl-class/php-curl-class: ~9.6.0
README
NYX cUrl is an object-oriented wrapper of the PHP cURL extension that makes it easy to send HTTP requests and integrate with web APIs. This build targets the Yii Framework version 2 and curretly does not adds any functionality to the main library (PHP Curl Class), but adds the \nyx\request\helpers\CurlHelper
which extends Yii2 Base URL Helper and implements methods to verify and manage URLs.
This extension uses the PHP Curl Class 7.* by Zach Borboa. For more details about the PHP Curl Class please refer to php-curl-class/php-curl-class or www.phpcurlclass.com.
Requirements
PHP 5.4+.
Installation
The preferred way to install this extension is through composer.
Either run
php composer.phar require --prefer-dist nyx-solutions/yii2-nyx-curl "*"
or add
"nyx-solutions/yii2-nyx-curl": "*"
to the require section of your composer.json
file.
Usage
Basic Example
$request = new \nyx\request\Curl(); $request->get('https://www.example.com/');
GET Example
$request = new \nyx\request\Curl(); $request->get('https://www.example.com/search', ['q' => 'keyword']);
POST Example
$request = new \nyx\request\Curl(); $request->post('https://www.example.com/login/', ['username' => 'myusername', 'password' => 'mypassword']);
Basic Authentication with Error Handle Example
$request = new \nyx\request\Curl(); $request->setBasicAuthentication('username', 'password'); $request->setUserAgent('MyUserAgent/0.0.1 (+https://www.example.com/bot.html)'); $request->setReferrer('https://www.example.com/url?url=https%3A%2F%2Fwww.example.com%2F'); $request->setHeader('X-Requested-With', 'XMLHttpRequest'); $request->setCookie('key', 'value'); $request->get('https://www.example.com/'); if ($request->error) { echo "Error: {$request->errorCode}: {$request->errorMessage}"; } else { echo "Response: \n"; var_dump($request->response); } var_dump($request->requestHeaders); var_dump($request->responseHeaders);
setOpt method Example
$request = new \nyx\request\Curl(); $request->setOpt(CURLOPT_FOLLOWLOCATION, true); $request->get('https://shortn.example.com/bHbVsP');
PUT Example
$request = new \nyx\request\Curl(); $request->put('https://api.example.com/user/', ['first_name' => 'Zach', 'last_name' => 'Borboa']);
PATCH Example
$request = new \nyx\request\Curl(); $request->patch('https://api.example.com/profile/', ['image' => '@path/to/file.jpg']);
$request = new \nyx\request\Curl(); $request->patch('https://api.example.com/profile/', ['image' => new CURLFile('path/to/file.jpg')]);
DELETE Example
$request = new \nyx\request\Curl(); $request->delete('https://api.example.com/user/', ['id' => '1234']);
Download with GZIP Compression Example
// Enable gzip compression and download a file. $request = new \nyx\request\Curl(); $request->setOpt(CURLOPT_ENCODING , 'gzip'); $request->download('https://www.example.com/image.png', '/tmp/myimage.png');
// Case-insensitive access to headers. $request = new \nyx\request\Curl(); $request->download('https://www.example.com/image.png', '/tmp/myimage.png'); echo $request->responseHeaders['Content-Type'] . "\n"; // image/png echo $request->responseHeaders['CoNTeNT-TyPE'] . "\n"; // image/png
$request->close();
\nyx\request\Curl Available Methods
Curl::__construct($base_url = null) Curl::__destruct() Curl::__get($name) Curl::beforeSend($callback) Curl::buildPostData($data) Curl::call() Curl::close() Curl::complete($callback) Curl::delete($url, $query_parameters = array(), $data = array()) Curl::download($url, $mixed_filename) Curl::error($callback) Curl::exec($ch = null) Curl::get($url, $data = array()) Curl::getCookie($key) Curl::getInfo($opt) Curl::getOpt($option) Curl::getResponseCookie($key) Curl::head($url, $data = array()) Curl::headerCallback($ch, $header) Curl::options($url, $data = array()) Curl::patch($url, $data = array()) Curl::post($url, $data = array(), $follow_303_with_post = false) Curl::progress($callback) Curl::put($url, $data = array()) Curl::removeHeader($key) Curl::search($url, $data = array()) Curl::setBasicAuthentication($username, $password = '') Curl::setConnectTimeout($seconds) Curl::setCookie($key, $value) Curl::setCookieFile($cookie_file) Curl::setCookieJar($cookie_jar) Curl::setCookieString($string) Curl::setDefaultDecoder($decoder = 'json') Curl::setDefaultJsonDecoder() Curl::setDefaultTimeout() Curl::setDefaultUserAgent() Curl::setDefaultXmlDecoder() Curl::setDigestAuthentication($username, $password = '') Curl::setHeader($key, $value) Curl::setHeaders($headers) Curl::setJsonDecoder($function) Curl::setMaxFilesize($bytes) Curl::setOpt($option, $value) Curl::setOpts($options) Curl::setPort($port) Curl::setReferer($referer) Curl::setReferrer($referrer) Curl::setTimeout($seconds) Curl::setUrl($url, $data = array()) Curl::setUserAgent($user_agent) Curl::setXmlDecoder($function) Curl::success($callback) Curl::unsetHeader($key) Curl::verbose($on = true, $output = STDERR) Curl::array_flatten_multidim($array, $prefix = false) Curl::is_array_assoc($array) Curl::is_array_multidim($array)
\nyx\request\MultiCurl Available Methods
MultiCurl::__construct($base_url = null) MultiCurl::__destruct() MultiCurl::addCurl(Curl $curl) MultiCurl::addDelete($url, $query_parameters = array(), $data = array()) MultiCurl::addDownload($url, $mixed_filename) MultiCurl::addGet($url, $data = array()) MultiCurl::addHead($url, $data = array()) MultiCurl::addOptions($url, $data = array()) MultiCurl::addPatch($url, $data = array()) MultiCurl::addPost($url, $data = array(), $follow_303_with_post = false) MultiCurl::addPut($url, $data = array()) MultiCurl::addSearch($url, $data = array()) MultiCurl::beforeSend($callback) MultiCurl::close() MultiCurl::complete($callback) MultiCurl::error($callback) MultiCurl::getOpt($option) MultiCurl::removeHeader($key) MultiCurl::setBasicAuthentication($username, $password = '') MultiCurl::setConcurrency($concurrency) MultiCurl::setConnectTimeout($seconds) MultiCurl::setCookie($key, $value) MultiCurl::setCookieFile($cookie_file) MultiCurl::setCookieJar($cookie_jar) MultiCurl::setCookieString($string) MultiCurl::setDigestAuthentication($username, $password = '') MultiCurl::setHeader($key, $value) MultiCurl::setHeaders($headers) MultiCurl::setJsonDecoder($function) MultiCurl::setOpt($option, $value) MultiCurl::setOpts($options) MultiCurl::setPort($port) MultiCurl::setReferer($referer) MultiCurl::setReferrer($referrer) MultiCurl::setTimeout($seconds) MultiCurl::setUrl($url) MultiCurl::setUserAgent($user_agent) MultiCurl::setXmlDecoder($function) MultiCurl::start() MultiCurl::success($callback) MultiCurl::unsetHeader($key) MultiCurl::verbose($on = true, $output = STDERR)
You can find more examples at https://github.com/php-curl-class/php-curl-class/tree/master/examples.
Security Considerations
Url may point to system files
- Don't blindly accept urls from users as they may point to system files. Curl supports many protocols including
FILE
. The following would show the contents offile:///etc/passwd
.
# Attacker. $ curl https://www.example.com/display_webpage.php?url=file%3A%2F%2F%2Fetc%2Fpasswd
// display_webpage.php $url = $_GET['url']; // DANGER! $request = new \nyx\request\Curl(); $request->get($url); echo $request->response;
Safer:
$url = $_GET['url']; if (!\nyx\request\helpers\CurlHelper::isValidUrl($url)) { die('Unsafe url detected.'); }
Url may point to internal urls
- Url may point to internal urls including those behind a firewall (e.g. http://192.168.0.1/ or ftp://192.168.0.1/). Use a whitelist to allow certain urls rather than a blacklist.
Request data may refer to system files
- Request data prefixed with the
@
character may have special interpretation and read from system files.
# Attacker. $ curl https://www.example.com/upload_photo.php --data "photo=@/etc/passwd"
// upload_photo.php $request = new \nyx\request\Curl(); $request->post('http://www.anotherwebsite.com/', ['photo' => $_POST['photo']]); // DANGER!
Unsafe response with redirection enabled
- Requests with redirection enabled may return responses from unexpected sources. Downloading https://www.example.com/image.png may redirect and download https://www.evil.com/virus.exe
$request = new \nyx\request\Curl(); $request->setOpt(CURLOPT_FOLLOWLOCATION, true); // DANGER! $request->download('https://www.example.com/image.png', 'my_image.png');
Keep SSL protections enabled.
- Do not disable SSL protections.
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE); // DANGER! curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE); // DANGER!
Based on the following document: https://github.com/php-curl-class/php-curl-class/tree/master/SECURITY.md.
License
yii2-nyx-curl is released under the BSD 3-Clause License. See the bundled LICENSE.md
for details.
To find more informations about the PHP Curl Class Licence, please refer to php-curl-class/php-curl-class.