salesrender/plugin-component-guzzle

SalesRender plugin guzzle helper

0.3.3 2023-12-13 13:49 UTC

Requires

• php: >=7.4.0
• guzzlehttp/guzzle: ^6.5
• salesrender/plugin-component-info: ^0.1.2

proprietary

• Timur Kasumov aka XAKEPEHOK

README

Singleton wrapper around GuzzleHttp providing an HTTP client with a SalesRender plugin-specific User-Agent header.

Overview

This component provides a thin abstraction over the GuzzleHttp Client, exposing it through a static singleton factory. Its primary purpose is to ensure that every HTTP request made by a SalesRender plugin carries a standardized User-Agent header that identifies the plugin type and its public endpoint.

The User-Agent format follows the convention:

SR-PLUGIN-{TYPE}-BOT/1.0 (+{SELF_URI}/info)

For example, a macros plugin hosted at https://plugin.example.com/excel would send:

SR-PLUGIN-MACROS-BOT/1.0 (+https://plugin.example.com/excel/info)

The plugin type is resolved from the Info component configuration, and the base URI comes from the LV_PLUGIN_SELF_URI environment variable. This makes all outgoing HTTP traffic from SalesRender plugins easily identifiable by external services.

Installation

composer require salesrender/plugin-component-guzzle

Requirements

• PHP >= 7.4
• guzzlehttp/guzzle ^6.5
• salesrender/plugin-component-info ^0.1.2

Key Classes

Guzzle

Namespace: SalesRender\Plugin\Components\Guzzle

Static singleton factory that creates and returns a configured GuzzleHttp Client instance.

The constructor is private -- the only way to obtain a client is through the getInstance() static method.

Methods

Method	Signature	Description
getInstance	static getInstance(array $config = []): \GuzzleHttp\Client	Returns the singleton GuzzleHttp Client. On the first call, creates the client by merging the provided $config with the default User-Agent header. Subsequent calls return the same instance (the $config argument is only applied on the first call).

Usage

Basic Usage

use SalesRender\Plugin\Components\Guzzle\Guzzle;

// Get the singleton HTTP client
$client = Guzzle::getInstance();

// Make a GET request
$response = $client->get('https://api.example.com/data');
$body = $response->getBody()->getContents();

Passing Custom Configuration

You can pass additional GuzzleHttp configuration options on the first call. These are merged recursively with the default User-Agent header:

use SalesRender\Plugin\Components\Guzzle\Guzzle;

$client = Guzzle::getInstance([
    'timeout' => 30,
    'headers' => [
        'Accept' => 'application/json',
    ],
]);

Note: The $config parameter is only used when the singleton is first created. Subsequent calls to getInstance() return the already-created instance regardless of the arguments passed.

Making API Requests

The returned object is a standard GuzzleHttp\Client, so all Guzzle methods are available:

use SalesRender\Plugin\Components\Guzzle\Guzzle;

// POST request with JSON body
$response = Guzzle::getInstance()->request('POST', 'https://api.example.com/orders', [
    'json' => ['order_id' => 12345],
]);

// GET request
$publicKey = Guzzle::getInstance()->get($uri)->getBody()->getContents();

// PUT request
$response = Guzzle::getInstance()->put($uri, [
    'json' => $payload,
]);

Usage in Other SalesRender Components

The Guzzle singleton is used throughout the SalesRender plugin ecosystem:

// In plugin-component-access (Registration)
return Guzzle::getInstance()->request(
    'PUT',
    $uri,
    ['json' => $requestBody]
);

// In plugin-component-api-client
$this->client = Guzzle::getInstance([
    'base_uri' => $endpoint,
    'headers' => [
        'Authorization' => "Bearer {$token}",
    ],
]);

// In plugin-component-special-request
$response = Guzzle::getInstance()->request(
    $method,
    $uri,
    $options
);

Configuration

The component requires two things to be configured before use:

1. Environment Variable

Set the LV_PLUGIN_SELF_URI environment variable to the plugin's public base URL:

LV_PLUGIN_SELF_URI=https://plugin.example.com/excel

This value is used as part of the User-Agent string. The trailing slash is automatically trimmed.

2. Plugin Info

The salesrender/plugin-component-info package must be configured so that the plugin type (e.g., MACROS, LOGISTIC, CHAT) can be resolved:

use SalesRender\Plugin\Components\Info\Info;
use SalesRender\Plugin\Components\Info\PluginType;

Info::config(
    new PluginType(PluginType::MACROS),
    'Plugin Name',
    'Plugin Description',
    $extra,
    $developer
);

The plugin type is included in the User-Agent header. Available types: MACROS, LOGISTIC, PBX, CHAT, GEOCODER, INTEGRATION, RESALE.

User-Agent Format

The resulting User-Agent header follows this pattern:

SR-PLUGIN-{TYPE}-BOT/1.0 (+{SELF_URI}/info)

Examples:

• SR-PLUGIN-MACROS-BOT/1.0 (+https://plugin.example.com/excel/info)
• SR-PLUGIN-LOGISTIC-BOT/1.0 (+https://logistic.example.com/cdek/info)
• SR-PLUGIN-CHAT-BOT/1.0 (+https://chat.example.com/wazzup/info)

API Reference

Guzzle

final class Guzzle
{
    private function __construct();
    public static function getInstance(array $config = []): \GuzzleHttp\Client;
}

Parameters:

• $config (array, optional) -- GuzzleHttp configuration array. Merged recursively with the default configuration using array_merge_recursive(). Only applied on the first invocation. Default: [].

Returns:

• \GuzzleHttp\Client -- A configured GuzzleHttp client singleton with the SalesRender User-Agent header.

Behavior:

1. On the first call, reads $_ENV['LV_PLUGIN_SELF_URI'] and Info::getInstance()->getType()
2. Creates a new GuzzleHttp\Client by merging the provided $config with the User-Agent header
3. Stores the client instance in a private static property
4. On subsequent calls, returns the stored instance

Dependencies

Package	Version	Purpose
guzzlehttp/guzzle	^6.5	The underlying HTTP client library
salesrender/plugin-component-info	^0.1.2	Provides the plugin type for the User-Agent string via Info::getInstance()->getType()

See Also

• salesrender/plugin-component-access -- Uses Guzzle::getInstance() for plugin registration and public key retrieval
• salesrender/plugin-component-api-client -- Uses Guzzle::getInstance() as the base HTTP client for API calls
• salesrender/plugin-component-special-request -- Uses Guzzle::getInstance() for handling special request forwarding
• salesrender/plugin-component-info -- Provides the Info singleton used to build the User-Agent header