retailcrm / aliexpress-top-client

AliExpress TOP client

AliExpress TOP API client

API client implementation for AliExpress TOP.

Usage

1. This library uses php-http/httplug under the hood. If you don't want to bother with details, just install library and it's dependencies via Composer:

composer require php-http/curl-client nyholm/psr7 php-http/message retailcrm/aliexpress-top-client

Details about those third-party libraries and why you need to install them can be found here.

2. Instantiate client using TopClientFactory:

use RetailCrm\Component\AppData;
use RetailCrm\Factory\TopClientFactory;

$client = TopClientFactory::createClient(
    AppData::OVERSEAS_ENDPOINT,
    'appKey',
    'appSecret',
    'session token here'
);

3. Create and fill request data. All requests and responses use the same naming: part of the namespace is the first word in the request name, and everything else is in the request DTO class name. Requests live under RetailCrm\Model\Request namespace, and responses can be found in the RetailCrm\Model\Response namespace. Let's use taobao.httpdns.get request as an example. It's first word is the taobao, so, this request can be found under RetailCrm\Model\Request\Taobao namespace, and it's class name is HttpDnsGetRequest. You can instantiate it with this code:

use RetailCrm\Model\Request\Taobao\HttpDnsGetRequest;

$request = new HttpDnsGetRequest();

4. Send request using TopClient::sendRequest or TopClient::sendAuthenticatedRequest (you can't send authenticated request using client without authenticator). taobao.httpdns.get can be sent like this:

/** @var \RetailCrm\Model\Response\Taobao\HttpDnsGetResponse $response */
$response = $client->sendRequest(new HttpDnsGetRequest());

This particular request doesn't require authorization, so, it can be sent via TopClient::sendRequest method. For any other requests which require authorization you must use TopClient::sendAuthenticatedRequest method (an example of such request would be aliexpress.solution.seller.category.tree.query, which class FQN is \RetailCrm\Model\Request\AliExpress\SolutionSellerCategoryTreeQuery).

Friendly note. Use response type annotations. Both client methods which returns responses actually returns ResponseInterface (not the PSR one). Actual response type will be determined by the request model. Your IDE will not recognize any response options unless you put a proper type annotation for the response variable.

Customization

This library uses Container pattern under the hood. You can pass additional dependencies using ContainerBuilder. For example:

use Http\Client\Curl\Client;
use RetailCrm\Component\AppData;
use RetailCrm\Component\Environment;
use Nyholm\Psr7\Factory\Psr17Factory;
use RetailCrm\Builder\TopClientBuilder;
use RetailCrm\Builder\ContainerBuilder;
use RetailCrm\Component\Logger\StdoutLogger;
use RetailCrm\Component\Authenticator\TokenAuthenticator;

$client = new Client();
$logger = new StdoutLogger();
$factory = new Psr17Factory();
$authenticator = new TokenAuthenticator('token');
$appData = new AppData(AppData::OVERSEAS_ENDPOINT, 'appKey', 'appSecret');
$container = ContainerBuilder::create()
            ->setEnv(Environment::TEST)
            ->setClient($client)
            ->setLogger($logger)
            ->setStreamFactory($factory)
            ->setRequestFactory($factory)
            ->setUriFactory($factory)
            ->build();
$client = TopClientBuilder::create()
            ->setContainer($container)
            ->setAppData($appData)
            ->build();

Logger should implement Psr\Log\LoggerInterface (PSR-3), HTTP client should implement Psr\Http\TopClient\TopClientInterface (PSR-18), HTTP objects must be compliant to PSR-7. You can use your own container if you want to - it must be compliant to PSR-11. This is strongly discouraged because it'll be much easier to just integrate library with your own application, and your own DI system.

The simplest example of client initialization without using TopClientFactory looks like this:

use RetailCrm\Component\AppData;
use RetailCrm\Builder\TopClientBuilder;
use RetailCrm\Builder\ContainerBuilder;
use RetailCrm\Component\Authenticator\TokenAuthenticator;

$appData = new AppData(AppData::OVERSEAS_ENDPOINT, 'appKey', 'appSecret');
$client = TopClientBuilder::create()
            ->setContainer(ContainerBuilder::create()->build())
            ->setAppData($appData)
            ->setAuthenticator(new TokenAuthenticator('session token here'))
            ->build();

In fact, TopClientFactory works just like this under the hood.

aliexpress-top-client's Issues

Add descrition to readme.md about what is project is for

In your readme you described how to install and customize it, but what does it do or what problem does it try to solve?
Based from the description AliExpress TOP client i assume it is a custom front-end for aliexpress. If that is the case someone passing by your project (like me) still does not know why he/she should use your front-end over the default aliexpress front-end.
Someone passing by also does not want to review the source code to understand the purpose or having to install it to then figure out whats its purpose is.