README

安装

使用composer安装此包

composer require antonioprimera/laravel-api-client

如果您想使用预配置的客户端和端点，而不是在PHP代码中定义身份验证类型、凭证、请求方法和URL，您可以创建一个新的配置文件，命名为apiEndpoints.php。

使用方法

ApiClient可以根据配置文件或直接在代码中创建并指定所有必要的身份验证详细信息来使用。

不带配置的示例用法

创建一个Laravel Sanctum客户端。Laravel Sanctum客户端将通过Authorization头中的Bearer令牌发送其身份验证令牌。

    use AntonioPrimera\ApiClient\ApiClient;
    use AntonioPrimera\ApiClient\Clients\HttpClient;
    
    $response = ApiClient::makeSanctumClient()
        ->withToken('some-token')
        ->post('http://my-api-endpoint-url.com', ['id' => 15]);

创建一个具有基本身份验证的HTTP客户端。此类身份验证需要将凭证设置为一个包含“username”和“password”键的数组。这些凭证将被编码并发送在Authorization头中。

    use AntonioPrimera\ApiClient\ApiClient;
    use AntonioPrimera\ApiClient\Clients\HttpClient;

    $response = ApiClient::makeHttpClient()
        ->withAuthenticationType(HttpClient::AUTHENTICATION_TYPE_BASIC)
        ->withCredentials(['username' => 'my-user-name', 'password' => 'my-password'])
        ->get('http://my-api-endpoint-url.com', ['id' => 15]);

创建一个具有查询身份验证的HTTP客户端。对于此类身份验证，凭证将通过get请求的URL查询参数发送，或通过其他请求方法的请求体发送。您可以提供任何身份验证数据集（不一定是用户名和密码，如基本HTTP身份验证协议中那样）。

以下示例将向： http://my-api-endpoint-url.com?user=my-user-name&pass=my-pass&tk=my-token&id=15 发送get请求

    use AntonioPrimera\ApiClient\ApiClient;
    use AntonioPrimera\ApiClient\Clients\HttpClient;

    $response = ApiClient::makeHttpClient()
        ->withAuthenticationType(HttpClient::AUTHENTICATION_TYPE_QUERY)
        ->withCredentials(['user' => 'my-user-name', 'pass' => 'my-pass', 'tk' => 'my-token'])
        ->get('http://my-api-endpoint-url.com', ['id' => 15]);

带配置的示例用法（见以下示例配置）

基于配置的客户端'mySanctumClient'创建一个Laravel Sanctum客户端并调用配置的端点。如果配置中提供了API令牌，您可以仅调用配置的端点或某些其他URL。如果配置中没有提供令牌，必须在调用任何端点/URL之前使用withCredentials(...)或setCredentials()方法。

    use AntonioPrimera\ApiClient\ApiClient;
    use AntonioPrimera\ApiClient\Clients\HttpClient;
    
    $response = ApiClient::getClient('mySanctumClient')
        ->callEndpoint('setTracks', ['tracks' => '...']);

创建具有基本身份验证的HTTP客户端。如果配置中提供了凭证，您可以仅调用配置的端点或某些其他URL。如果没有提供配置中的凭证，必须在调用端点之前使用withCredentials(...)方法或setCredentials()。

    use AntonioPrimera\ApiClient\ApiClient;
    use AntonioPrimera\ApiClient\Clients\HttpClient;
 
    $response = ApiClient::makeClient('myBasicHttpClientWithCredentials')
        ->callEndpoint('getUser', ['user-id' => 15]);

创建具有查询身份验证的HTTP客户端。对于此类身份验证，凭证将通过get请求的URL查询参数发送，或通过其他请求方法的请求体发送。

    use AntonioPrimera\ApiClient\ApiClient;
    use AntonioPrimera\ApiClient\Clients\HttpClient;
    
    $response = ApiClient::getClient('myQueryHttpClient')
        ->callEndpoint('getMenu');
        

您可以使用配置的客户端对给定URL的端点进行调用，因此不一定需要配置所有端点。只需在客户端上调用'get' / 'post' / 'put' / 'patch' / 'delete' / 'head'方法并提供必要的数据即可。

    use AntonioPrimera\ApiClient\ApiClient;
    use AntonioPrimera\ApiClient\Clients\HttpClient;
    
    $response = ApiClient::getClient('myQueryHttpClient')
        ->post('http://my-api-endpoint-url.com', ['user' => ['id' => 15, 'name' => 'Gigi']]);

配置

默认情况下，使用配置文件apiEndpoints.php，所以如果您想根据配置数据使用api客户端，请不要忘记创建它。

如果您想使用另一个配置文件或更改ApiClient类的行为，您必须在项目中创建自己的ApiClient类，继承自AntonioPrimera\ApiClient\ApiClient。然后您可以重写静态变量$config以指向您期望的配置文件。

use AntonioPrimera\ApiClient\ApiClient;

class MyApiClient extends ApiClient
{
    protected static $config = 'myApiConfig';
}

ApiClient也可以不使用配置来使用，通过指定HTTP客户端类型、身份验证类型、凭证、URL和用于发送请求的方法。

//sample config
return [

    //the name of the client, usually the name of an external api provider e.g. "github" / "instagram"
    'mySanctumClient' => [
        
        //mandatory to have at least the authentication type provided
        'authentication' => [
            'type'  => 'sanctum',
            
            //(optional) if not provided, must be provided at run-time
            'token' => env('MY_SANCTUM_TOKEN'),
        ],
        
        //(optional) if rootUrl is provided it will be prepended to each endpoint url
        'rootUrl' => 'https://:8080/',
        
        //the list of all endpoints
        'endpoints' => [
        
            'setTracks' => [                //endpoint name, to be used in development (like a route name)
                'url'    => '/tracks/',     //url is mandatory
                'method' => 'post',         //(optional) by default: 'get'
            ],
            
            //endpoints with method 'get' can also be provided as strings
            'getPositions' => 'positions',
        ],
    ],
    
    //example of a provider with a basic http authentication
    'myBasicHttpClientWithCredentials' => [
        'authentication' => [
            'type' => 'http:basic',
            
            //optional
            'credentials' => [
                'username' => env('MY_HTTP_CLIENT_USERNAME'),
                'password' => env('MY_HTTP_CLIENT_PASSWORD'),
            ],
        ],
        
        'endpoints' => [
            //... all endpoints are the same, regardless of the authentication type
        ],
    ],
    
    //example of a provider with an authentication via query parameters (credentials are sent as part of the url)
    'myQueryHttpClient' => [
        'authentication' => [
            'type' => 'http:query',
            
            //credentials are optional (can be provided at runtime via method $client->setCredentials(...)
            'credentials' => [
                'key' 		 => 'my-key',
                'passphrase' => 'my-phrase',
                'token'		 => 'my-token',
            ],

        ],
        
        'endpoints' => [
            //... all endpoints are the same, regardless of the authentication type
        ],
    ],    
];