README

分支: https://github.com/ixudra/curl

Laravel 6 框架的定制 PHP cURL 库

此软件包提供了一个简单的接口，可以从您的 PHP 网络应用程序发送 cURL 请求。它提供了一个直观、流畅的接口，类似于 Laravel 查询构建器，便于配置请求。此外，还有一些实用方法，允许您轻松地将某些选项添加到请求中。这使得创建和使用 cURL 请求变得更加容易，也使得您的代码更易于理解。

提供的功能完全独立于框架，但同时也包含一个 Laravel 服务提供程序，便于将其集成到您的 Laravel 项目中。

发布问题前的注意事项：在发布有关该软件包的问题时，请务必尽可能提供有关请求的详细信息。这包括您尝试将示例 cURL 请求转换为软件包语法的示例、您的实际软件包语法（完整请求）以及（如果可能）一个我可以用来测试请求的示例 URL。

安装

在终端中运行：composer require mderakhshi/curl

Laravel 5.5+ 集成

Laravel 的软件包发现将为您处理集成。

Laravel 5.* 集成

将服务提供程序添加到您的 config/app.php 文件

    'providers'     => array(

        //...
        mderakhshi\Curl\CurlServiceProvider::class,

    ),

将外观添加到您的 config/app.php 文件

    'aliases'       => array(

        //...
        'Curl'          => mderakhshi\Curl\Facades\Curl::class,

    ),

Laravel 4.* 集成

将服务提供程序添加到您的 app/config/app.php 文件

    'providers'     => array(

        //...
        'mderakhshi\Curl\CurlServiceProvider',

    ),

将外观添加到您的 app/config/app.php 文件

    'facades'       => array(

        //...
        'Curl'          => 'mderakhshi\Curl\Facades\Curl',

    ),

Lumen 5.* 集成

在您的 bootstrap/app.php 中，确保您已取消以下行的注释（大约在第 26 行）

$app->withFacades();

然后，注册您的类别名

class_alias('mderakhshi\Curl\Facades\Curl', 'Curl');

最后，您必须注册您的服务提供程序（大约在第 70-80 行）

/*
|--------------------------------------------------------------------------
| Register Service Providers
|--------------------------------------------------------------------------
|
| Here we will register all of the application's service providers which
| are used to bind services into the container. Service providers are
| totally optional, so you are not required to uncomment this line.
|
*/

// $app->register('App\Providers\AppServiceProvider');

// Package service providers
$app->register(mderakhshi\Curl\CurlServiceProvider::class);

非 Laravel 集成

在您想要使用该软件包的地方创建一个 CurlService 实例

    $curlService = new \mderakhshi\Curl\CurlService();

使用方法

Laravel 使用方法

该软件包提供了一个简单的接口，可以从您的应用程序发送 cURL 请求。它提供了一个流畅的接口，类似于 Laravel 查询构建器，便于配置请求。有一些实用方法允许您轻松地将某些选项添加到请求中。如果没有适用的实用方法，您还可以使用通用的 withOption 方法。

助手

   curl('https://www.google.com')->get();
   curl('https://www.google.com')->withData(['name'=>'ss'])->post();

发送 GET 请求

为了发送 GET 请求，您需要使用软件包提供的 get() 方法

    use mderakhshi\Curl\Facades\Curl;

    // Send a GET request to: http://www.foo.com/bar
    $response = Curl::to('http://www.foo.com/bar')
        ->get();

    // Send a GET request to: http://www.foo.com/bar?foz=baz
    $response = Curl::to('http://www.foo.com/bar')
        ->withData( array( 'foz' => 'baz' ) )
        ->get();

    // Send a GET request to: http://www.foo.com/bar?foz=baz using JSON
    $response = Curl::to('http://www.foo.com/bar')
        ->withData( array( 'foz' => 'baz' ) )
        ->asJson()
        ->get();

发送 POST 请求

POST 请求的工作方式类似于 GET 请求，但使用 post() 方法代替

    use mderakhshi\Curl\Facades\Curl;

    // Send a POST request to: http://www.foo.com/bar
    $response = Curl::to('http://www.foo.com/bar')
        ->post();
    
    // Send a POST request to: http://www.foo.com/bar
    $response = Curl::to('http://www.foo.com/bar')
        ->withData( array( 'foz' => 'baz' ) )
        ->post();
    
    // Send a POST request to: http://www.foo.com/bar with arguments 'foz' = 'baz' using JSON
    $response = Curl::to('http://www.foo.com/bar')
        ->withData( array( 'foz' => 'baz' ) )
        ->asJson()
        ->post();
    
    // Send a POST request to: http://www.foo.com/bar with arguments 'foz' = 'baz' using JSON and return as associative array
    $response = Curl::to('http://www.foo.com/bar')
        ->withData( array( 'foz' => 'baz' ) )
        ->asJson( true )
        ->post();

发送 PUT 请求

PUT 请求的工作方式类似于 POST 请求，但使用 put() 方法代替

    use mderakhshi\Curl\Facades\Curl;

    // Send a PUT request to: http://www.foo.com/bar/1 with arguments 'foz' = 'baz' using JSON
    $response = Curl::to('http://www.foo.com/bar/1')
       ->withData( array( 'foz' => 'baz' ) )
       ->asJson()
       ->put();

发送 PATCH 请求

PATCH 请求的工作方式类似于 POST 请求，但使用 patch() 方法代替

    use mderakhshi\Curl\Facades\Curl;

    // Send a PATCH request to: http://www.foo.com/bar/1 with arguments 'foz' = 'baz' using JSON
    $response = Curl::to('http://www.foo.com/bar/1')
        ->withData( array( 'foz' => 'baz' ) )
        ->asJson()
        ->patch();

发送 DELETE 请求

DELETE 请求的工作方式类似于 GET 请求，但使用 delete() 方法代替

    use mderakhshi\Curl\Facades\Curl;

    // Send a DELETE request to: http://www.foo.com/bar/1 using JSON
    $response = Curl::to('http://www.foo.com/bar/1')
        ->asJson()
        ->delete();

发送自定义头部

使用 withHeader() 方法可以轻松地发送自定义头部。可以通过链式调用多次调用以添加多个头部到请求中

    use mderakhshi\Curl\Facades\Curl;

    // Send a GET request to: http://www.foo.com/bar with 2 custom headers
    $response = Curl::to('http://foo.com/bar')
        ->withHeader('MyFirstHeader: 123')
        ->withHeader('MySecondHeader: 456')
        ->get();

或者，您可以使用 withHeaders() 将多个头部合并到一个方法调用中

    use mderakhshi\Curl\Facades\Curl;

    // Send a GET request to: http://www.foo.com/bar with 2 custom headers
    $response = Curl::to('http://foo.com/bar')
        ->withHeaders( array( 'MyFirstHeader: 123', 'MySecondHeader: 456' ) )
        ->get();

您还可以在 withHeaders() 方法中使用键值对

    use mderakhshi\Curl\Facades\Curl;

    // Send a GET request to: http://www.foo.com/bar with 2 custom headers
    $response = Curl::to('http://foo.com/bar')
        ->withHeaders( array( 'MyFirstHeader' => '123', 'MySecondHeader' => '456' ) )
        ->get();

请注意，如果添加了相同的头部多次，它们将相互覆盖。

指定内容类型

使用 withContentType() 方法发送自定义头信息非常简单。可以通过链式调用多次，为请求添加多个头信息

    use mderakhshi\Curl\Facades\Curl;

    // Send a GET request to: http://www.foo.com/bar with a json content type
    $response = Curl::to('http://foo.com/bar')
        ->withContentType('application/json')
        ->get();

使用代理

如果您需要通过代理发送请求，可以使用 'withProxy()' 方法。该方法需要五个参数

• 代理 URL（必需）
• 端口号（可选）
• 代理方案类型（可选，例如 http://、https:// 等）
• 用户名（可选）
• 密码（可选）

如果未填写，则忽略可选参数。

    use mderakhshi\Curl\Facades\Curl;

    // Send a GET request to: http://www.foo.com/bar with a json content type
    $response = Curl::to('http://foo.com/bar')
        ->withProxy('192.168.1.1', 80, 'http://', 'Foo', 'Bar')
        ->get();

通过 Curl 发送文件

对于通过 POST 请求发送文件，您可以使用 withFile 方法在发送前正确地格式化请求

    use mderakhshi\Curl\Facades\Curl;

    $response = Curl::to('http://foo.com/bar')
        ->withData( array( 'Foo' => 'Bar' ) )
        ->withFile( 'image_1', '/path/to/dir/image1.png', 'image/png', 'imageName1.png' )
        ->withFile( 'image_2', '/path/to/dir/image2.png', 'image/png', 'imageName2.png' )
        ->post();

您可以添加任意数量的文件到请求中。以下是一些需要注意的事项

• 提交文件时，不能使用 asJson() 方法或 asJsonRequest() 方法。如果使用，文件将无法正确传输
• 使用 withFile() 方法的第一个参数将文件添加到在 withData() 方法中提供的数据中。如果该键已存在，它将被覆盖。

下载文件

对于下载文件，您可以使用 download() 方法

    use mderakhshi\Curl\Facades\Curl;

    // Download an image from: file http://www.foo.com/bar.png
    $response = Curl::to('http://foo.com/bar.png')
        ->withContentType('image/png')
        ->download('/path/to/dir/image.png');

使用响应对象

默认情况下，该包只会返回请求的内容。在某些情况下，了解额外的请求信息可能也很有用，例如 HTTP 状态码和可能出现的错误消息。在这种情况下，您可以使用 returnResponseObject() 方法，该方法将返回一个包含额外信息和响应内容的 stdClass 对象

    use mderakhshi\Curl\Facades\Curl;

    // Send a GET request to http://www.foo.com/bar and return a response object with additional information
    $response = Curl::to('http://www.foo.com/bar')
        ->returnResponseObject()
        ->get();
            
    $content = $response->content;

响应对象将如下所示

{
   "content": "Message content here",
   "status": 200,
   "contentType": "content-type response header (ex: application/json)",
   "error": "Error message goes here (Only added if an error occurs)"
}

响应头

在某些情况下，可能需要将响应头返回给用户。这可以通过使用 withResponseHeaders() 方法轻松完成。

    use mderakhshi\Curl\Facades\Curl;

    // Send a GET request to http://www.foo.com/bar and return a response object with additional information including response headers
    $response = Curl::to('http://www.foo.com/bar')
        ->withResponseHeaders()
        ->returnResponseObject()
        ->get();
            
    $content = $response->content;
    $headers = $response->headers;

响应对象将如下所示

{
    "content": "Message content here",
    "status": 200,
    "contentType": "content-type response header (ex: application/json)",
    "error": "Error message goes here (Only added if an error occurs)",
    "headers": {
        "header-type-1": "header-content-1",
        "header-type-2": "header-content-2"
    }
}

请注意，必须与 returnResponseObject() 方法一起使用 withResponseHeaders() 方法才能看到返回的头信息

调试请求

如果请求失败，可能需要调试请求。在这种情况下，可以使用 enableDebug() 方法。该方法使用一个参数，即要存储调试信息的文件名

    use mderakhshi\Curl\Facades\Curl;

    // Send a GET request to http://www.foo.com/bar and log debug information in /path/to/dir/logFile.txt
    $response = Curl::to('http://www.foo.com/bar')
        ->enableDebug('/path/to/dir/logFile.txt')
        ->get();

使用 cURL 选项

您可以使用几个实用方法（例如，使用 withHeader() 添加头信息到请求中）或使用通用的 withOption() 方法（如果适用）将各种 cURL 选项添加到请求中。该包将自动在选项前添加 CURLOPT_ 前缀。请注意，该包不对 cURL 选项执行任何验证。有关可用 cURL 选项的更多信息，请参阅此处。

有关参数和返回类型的具体信息，我鼓励您查看 mderakhshi\curl\src\mderakhshi\Curl\Builder.php。该类包含详细的 doc blocks，其中包含每个特定方法所需的所有信息。

不使用 Laravel 的使用

不使用 Laravel 的使用与之前描述的使用相同。唯一的区别是您将无法使用外观来访问 CurlService。

    $curlService = new \mderakhshi\Curl\CurlService();

    // Send a GET request to: http://www.foo.com/bar
    $response = $curlService->to('http://www.foo.com/bar')
        ->get();

    // Send a POST request to: http://www.foo.com/bar
    $response = $curlService->to('http://www.foo.com/bar')
        ->post();

    // Send a PUT request to: http://www.foo.com/bar
    $response = $curlService->to('http://www.foo.com/bar')
        ->put();

    // Send a DELETE request to: http://www.foo.com/bar
    $response = $curlService->to('http://www.foo.com/bar')
        ->delete();

规划

• 添加其他 cURL 选项的实用方法
• 添加合约，以允许使用不同的 HTTP 提供程序，如 Guzzle

许可证

此软件包是开源软件，根据 MIT 许可证授权。