README

NYX cUrl 是 PHP cURL 扩展的对象封装，简化了发送 HTTP 请求和与 Web API 集成的过程。此版本针对 Yii 框架 2 开发，目前不对主库（PHP cURL 类）添加任何功能，但添加了 \nyx\request\helpers\CurlHelper，它扩展了 Yii2 Base URL Helper 并实现了验证和管理 URL 的方法。

此扩展使用 Zach Borboa 的 PHP cURL 类 7.*。有关 PHP cURL 类的更多详细信息，请参阅 php-curl-class/php-curl-class 或 www.phpcurlclass.com。

要求

PHP 5.4+

安装

安装此扩展的首选方式是通过 composer。

运行以下命令之一：

php composer.phar require --prefer-dist nyx-solutions/yii2-nyx-curl "*"

或

"nyx-solutions/yii2-nyx-curl": "*"

将以下内容添加到您的 composer.json 文件的 require 部分。

用法

基本示例

$request = new \nyx\request\Curl();

$request->get('https://www.example.com/');

GET 示例

$request = new \nyx\request\Curl();

$request->get('https://www.example.com/search', ['q' => 'keyword']);

POST 示例

$request = new \nyx\request\Curl();

$request->post('https://www.example.com/login/', ['username' => 'myusername', 'password' => 'mypassword']);

带有错误处理的简单认证示例

$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 方法示例

$request = new \nyx\request\Curl();

$request->setOpt(CURLOPT_FOLLOWLOCATION, true);

$request->get('https://shortn.example.com/bHbVsP');

PUT 示例

$request = new \nyx\request\Curl();

$request->put('https://api.example.com/user/', ['first_name' => 'Zach', 'last_name' => 'Borboa']);

PATCH 示例

$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 示例

$request = new \nyx\request\Curl();

$request->delete('https://api.example.com/user/', ['id' => '1234']);

使用 GZIP 压缩下载示例

// 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 可用方法

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 可用方法

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)

您可以在 https://github.com/php-curl-class/php-curl-class/tree/master/examples 找到更多示例。

安全注意事项

URL 可能指向系统文件

不要盲目接受用户提供的 URL，因为它们可能指向系统文件。cURL 支持许多协议，包括 FILE。以下将显示 file:///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;

更安全的做法

$url = $_GET['url'];

if (!\nyx\request\helpers\CurlHelper::isValidUrl($url)) {
    die('Unsafe url detected.');
}

URL 可能指向内部 URL

URL 可能指向包括防火墙后面的内部 URL（例如 http://192.168.0.1/ 或 ftp://192.168.0.1/）。使用白名单允许某些 URL 而不是黑名单。

请求数据可能引用系统文件

以 @ 字符前缀的请求数据可能具有特殊含义，并从系统文件中读取。

# 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!

启用重定向的响应不安全

启用重定向的请求可能返回来自意外来源的响应。下载 https://www.example.com/image.png 可能会重定向并下载 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');

保持 SSL 保护开启。

不要禁用 SSL 保护。

curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE); // DANGER!
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE); // DANGER!

基于以下文档： https://github.com/php-curl-class/php-curl-class/tree/master/SECURITY.md。

许可证

yii2-nyx-curl 采用 BSD 3-Clause 许可证发布。有关详细信息，请参阅附带文件 LICENSE.md。

有关 PHP Curl Class 许可证的更多信息，请参阅 php-curl-class/php-curl-class。

nyx-solutions / yii2-nyx-curl

维护者

详细信息