README

Afterglow is an unofficial PHP SDK for Alibaba Cloud. Built on Alibaba
Cloud Openmeta and designed to be HTTP client-agnostic, it aims to
provide a simple, developer-friendly, and maintainable interface to the
platform's services.

This package is in the early stages of development and may introduce
breaking changes at any time. If you plan to use it in production, be
aware that future releases may require application changes.


Installation
------------

You can install the package using Composer:

    composer require lizhineng/afterglow

Afterglow's API coverage is driven by its metadata package. Update it
periodically to obtain the latest API definitions:

    composer update lizhineng/afterglow-metadata


Quickstart
----------

Suppose you want to create a VPC for your next project:

    use Zhineng\Afterglow\Client;

    $client = Client::make([
        'service' => 'vpc',
        'region' => 'cn-shenzhen',
        'credentials' => [
            'key' => 'YOUR_ACCESSKEY_ID',
            'secret' => 'YOUR_ACCESSKEY_SECRET',
        ],
    ]);

    $result = $client->createVpc([
        'RegionId' => 'cn-shenzhen',
    ]);

    // Retrieve the newly created VPC ID
    $result->get('VpcId');

You initialize the client with the target service, region, and
credentials. Then, you send an API request to the VPC service to create
a new VPC network under the specific region. Finally, you retrieve the
newly created VPC ID.


Client options
--------------

service: string
    The service code of the Alibaba Cloud product.

version: string|null
    The API version for the service. If omitted, the SDK will
    automatically resolve the default version set by Alibaba Cloud. It
    is recommended to pin API version to avoid unexpected behavior when
    Alibaba Cloud updates its API metadata.

region: string
    The Alibaba Cloud region code (e.g., `cn-hangzhou`).

endpoint: string|null
    The HTTP endpoint to communicate with the service. If omitted, the
    SDK will automatically resolve based on the region code.

    The endpoint should not include the scheme (e.g., `http://` or
    `https://`) since it will be overridden by the API definition.

credentials: array
    The credentials used to communicate with Alibaba Cloud on your
    behalf.

credentials.key: string
    The AccessKey ID.

credentials.secret: string
    The AccessKey Secret.

credentials.token: string|null
    The security token used for temporary credentials.


Directives
----------

The SDK supports a set of directives that can be specified alongside API
arguments to control request behavior. The following directives are
currently available.

@headers::
    Add HTTP headers to the request. Header values may be specified
    directly as strings or generated dynamically using callbacks.

    Callbacks receive the outgoing PSR-7 request and are evaluated
    before the request is sent.

        use Psr\Http\Message\RequestInterface;

        $client->something([
            '@headers' => [
                'Content-Type' => 'text/plain',
                'Content-MD5' => fn (RequestInterface $request): string => base64_encode(
                    md5((string) $request->getBody(), binary: true)
                ),
            ],
        ]);


Result
------

You would receive a `Result` object back from the service if nothing
went wrong. To inspect the complete response payload:

    $result->getDecoded();

The response data varies by API. You can also retrieve a specific data
from the nested data structure using dot notation:

    $result->get('Vpcs.Vpc.0.VpcId');

Which is the same as:

    $data = $result->getDecoded();
    $data['Vpcs']['Vpc'][0]['VpcId'];

Sometimes you may need a fallback value when the data does not exist,
you can pass the default value to the second parameter:

    $result->get('not-exists', 'my-default-value');

To access the underlying HTTP response:

    $result->getResponse();


Exception
---------

The SDK throws a `ClientException` when the API returns an HTTP error
response. The associated `Result` object can be retrieved from the
exception:

    use Zhineng\Afterglow\Exceptions\ClientException;

    try {
        // ...
    } catch (ClientException $e) {
        $e->getResult();
    }


Further reading
---------------

Some service-specific features are documented in separate guides. Refer
to the corresponding documentation for more information.

- OSS Guide (docs/oss.txt)
- SLS Guide (docs/sls.txt)
- Simple Message Queue (formerly MNS) (docs/mns.txt)
- Tablestore Guide (docs/tablestore.txt)


Development
-----------

Before submitting changes, format the code, run static analysis, and
execute the test suite. The following commands provide consistent
workflows for these checks.

Use PHP CS Fixer to keep changes consistent with the existing code
style:

    make format

When a reusable formatting improvement is available, prefer adding the
corresponding rule to `.php-cs-fixer.dist.php` instead of applying the
change manually.

Because PHP 8.2 is the package's minimum supported version, run the
formatter under PHP 8.2 to ensure the formatting workflow remains
compatible. The Make target builds and runs the formatter in a Docker
container.

Run static analysis with PHPStan to catch type errors and other issues
that may not be exercised by the test suite:

    composer run lint

New features and bug fixes should include tests that demonstrate the
expected behavior. Run the test suite with:

    composer test

To run PHPStan and the test suite together:

    composer run qa

The local checks use the currently installed PHP version and dependency
set. To verify compatibility across all supported environments, run the
Docker test matrix. It covers every supported PHP version with both the
latest and lowest compatible dependency versions:

    make test

You can also run an individual matrix entry. For example:

    make test-php8.2
    make test-php8.2-lowest


Author
------

Zhineng Li <im@zhineng.li>


License
-------

The package is released under the MIT license.