Core Laravel Package

Getting Started

1. Install the package

   composer require async-aws/core
   

   No framework integration required—it’s framework-agnostic.

2. First use: Sign an AWS request manually
   Use the built-in SigV4 signer to sign arbitrary HTTP requests (e.g., for direct API calls outside service clients):

   use AsyncAws\Core\Credentials\CredentialChain;
   use AsyncAws\Core\Signature\RequestSigner;
   use GuzzleHttp\Psr7\Request;
   
   $credentials = (new CredentialChain())->resolve();
   $signer = new RequestSigner($credentials, 'us-east-1', 'execute-api');
   
   $request = new Request('GET', 'https://api.example.com/resource');
   $signed = $signer->sign($request, $request->getUri()->getPath());
   

3. Check service-specific clients
   While core itself only ships the base classes (e.g., Result, Input, AbstractApi), service clients like async-aws/s3 depend on it. Start with AsyncAws service packages for practical use.

4. Look here first for low-level integrations
   If you’re building a custom AWS client or need fine-grained control over signing/authentication, core is the right place.

Implementation Patterns

• Reusing credential resolution
  Integrate AsyncAws credential resolution (environment variables, IAM roles, config files) into non-AWS services:

  $credentials = (new CredentialChain([
      new EnvVariables(),
      new InstanceProfile(),
  ]))->resolve();
  

• PSR-7/18 requests without SDK bloat
  Build HTTP clients that only pull in async-aws/core, leveraging its lightweight Request, Response, and PSR-compatibility:

  use AsyncAws\Core\HttpClient\HttpClient;
  $httpClient = new HttpClient(); // internally uses Symfony HttpClient by default
  $response = $httpClient->send($signedRequest);
  

• Extending service clients
  Service packages extend AbstractApi, which lives in core. If you need to override signing behavior or add retry logic, subclass AbstractApi and inject custom RequestSigner or HttpClient.

• Custom result parsing
  Use Result base class to build minimal response objects:

  use AsyncAws\Core\Result;
  
  class CustomResponse extends Result {
      protected function evaluate(): void {
          $data = $this->json;
          $this->data = ['status' => $data['Status'] ?? null];
      }
  
      public function getStatus(): ?string { return $this->data['status'] ?? null; }
  }
  

Gotchas and Tips

• SigV4 region/service mismatch
  Overriding the region/service in RequestSigner is easy—but remember AWS SigV4 requires exact matching. A mismatch causes 403 Forbidden (e.g., signing for s3 but using execute-api service name).

• Default HTTP client dependency
  HttpClient uses Symfony HttpClient when present. If not, it falls back to curl via a polyfill—but only if ext-curl is installed. Prefer installing symfony/http-client explicitly in production.

• No autodetection of AWS region
  Unlike the official SDK, core does not auto-detect the region from EC2 metadata. Always provide it explicitly in your RequestSigner or config.

• Exception handling consistency
  All AsyncAws service clients throw exceptions extending AwsException (from core). Catch this for uniform error handling:

  try { /* ... */ } catch (\AsyncAws\Core\Exception\AwsException $e) {
      $statusCode = $e->getResponseStatusCode(); // always available
  }
  

• Pagination isn’t automatic
  core provides the Paginator interface but doesn’t auto-paginate. Use service-specific pagination helpers (e.g., S3Client::listObjectsV2()->paginate()) or implement your own loop over nextToken.

• No dependency on aws/aws-sdk-php
  This is a replacement, not a layer on top. Avoid mixing it with the official AWS SDK in the same process—credential caches or HTTP middleware may conflict.