Aws Sdk Php Laravel Package

## Getting Started

### Minimal Setup in Laravel
1. **Install the SDK** via Composer (updated for latest features):
   ```bash
   composer require aws/aws-sdk-php:^3.382.0

Laravel developers should use the aws/aws-sdk-php-laravel package for tighter integration:

composer require aws/aws-sdk-php-laravel

2. Configure AWS credentials in .env (unchanged):

   AWS_ACCESS_KEY_ID=your-access-key
   AWS_SECRET_ACCESS_KEY=your-secret-key
   AWS_DEFAULT_REGION=us-east-1
   

3. First use case: S3 Multipart Copy with Metadata Directive (new feature):

   use Aws\S3\S3Client;
   use Aws\Exception\AwsException;
   
   public function copyWithMetadataDirective()
   {
       $s3 = new S3Client([
           'version' => 'latest',
           'region'  => env('AWS_DEFAULT_REGION'),
       ]);
   
       try {
           $result = $s3->copyObject([
               'Bucket'     => 'destination-bucket',
               'Key'        => 'destination/path/file.jpg',
               'CopySource' => 'source-bucket/source/path/file.jpg',
               'MetadataDirective' => 'COPY', // New default: preserves source metadata
               // OR set to 'REPLACE' to suppress automatic metadata copying
           ]);
   
           return $result;
       } catch (AwsException $e) {
           \Log::error("S3 Copy Error: " . $e->getMessage());
           throw $e;
       }
   }
   

4. Leverage Laravel’s service container (updated for new services):

   $s3 = app('aws')->createS3();
   $iotWireless = app('aws')->createIoTWireless();
   $invoicing = app('aws')->createInvoicing();
   $securityAgent = app('aws')->createSecurityAgent();
   

Implementation Patterns

1. Service Clients & Dependency Injection (updated for new services)

• Register new clients in AppServiceProvider:

  public function register()
  {
      $this->app->singleton(\Aws\IoTWireless\IoTWirelessClient::class, function ($app) {
          return new \Aws\IoTWireless\IoTWirelessClient([
              'version' => 'latest',
              'region'  => env('AWS_IOT_WIRELESS_REGION'),
              'credentials' => [
                  'key'    => env('AWS_ACCESS_KEY_ID'),
                  'secret' => env('AWS_SECRET_ACCESS_KEY'),
              ],
          ]);
      });
  
      $this->app->singleton(\Aws\Invoicing\InvoicingClient::class, function ($app) {
          return new \Aws\Invoicing\InvoicingClient([
              'version' => 'latest',
              'region'  => env('AWS_INVOICING_REGION'),
          ]);
      });
  }
  

2. New: S3 Multipart Copy with Metadata Directive

• Preserve or replace metadata during S3 multipart copy operations:

  $s3->copyObject([
      'Bucket'     => 'destination-bucket',
      'Key'        => 'destination/path/file.jpg',
      'CopySource' => 'source-bucket/source/path/file.jpg',
      'MetadataDirective' => 'COPY', // Default: preserves source metadata
      // OR
      'MetadataDirective' => 'REPLACE', // Suppresses automatic metadata copying
      'Metadata' => ['custom-key' => 'custom-value'], // User-provided metadata
  ]);
  

3. New: Idempotency Support in Invoicing

• Use ClientToken for idempotency in Invoicing API calls:

  $invoicing = new \Aws\Invoicing\InvoicingClient([...]);
  
  $response = $invoicing->createInvoiceUnit([
      'ClientToken' => 'unique-idempotency-token-123',
      'InvoiceUnit' => [
          'InvoiceId' => 'invoice-123',
          'UnitType' => 'SUBSCRIPTION',
          'Quantity' => 1,
      ],
  ]);
  

4. New: Security Agent Verification Scripts

• Download verification scripts for penetration test findings:

  $securityAgent = new \Aws\SecurityAgent\SecurityAgentClient([...]);
  
  $response = $securityAgent->getFinding([
      'FindingId' => 'finding-123',
      'IncludeVerificationScript' => true,
  ]);
  
  // Save the verification script to a file
  file_put_contents(
      storage_path('app/verification_script.sh'),
      $response['VerificationScript']['Script']
  );
  

5. New: Performance Insights (PI) Recommendations

• List recommendations for performance analysis reports:

  $pi = new \Aws\PI\PIClient([...]);
  
  $response = $pi->listPerformanceAnalysisReportRecommendations([
      'ReportId' => 'report-123',
      'MaxResults' => 10,
  ]);
  
  foreach ($response['Recommendations'] as $recommendation) {
      \Log::info('Recommendation: ' . $recommendation['Recommendation']);
  }
  

6. New: QConnect Guardrail Assessment

• Retrieve guardrail assessment results for Bedrock Converse calls:

  $qConnect = new \Aws\QConnect\QConnectClient([...]);
  
  $response = $qConnect->listSpans([
      'SpanId' => 'span-123',
      'IncludeGuardrailAssessment' => true,
  ]);
  
  foreach ($response['Spans'][0]['GuardrailAssessment']['Results'] as $result) {
      \Log::info('Policy: ' . $result['PolicyName'] .
                 ', Blocked: ' . ($result['Blocked'] ? 'Yes' : 'No'));
  }
  

Gotchas and Tips

1. Breaking Changes

• None identified in this release. However, always check the AWS SDK for PHP changelog for service-specific changes.

2. New Features

• S3 Multipart Copy Metadata Directive:

  • metadata_directive: New option for copyObject to control metadata handling during multipart copy operations.
  • Default: 'COPY' (preserves source metadata).
  • Override: Set to 'REPLACE' to suppress automatic metadata copying and provide custom metadata via the Metadata parameter.
  • Use Case: Ideal for preserving or customizing metadata during large file transfers or migrations.

• Idempotency in Invoicing:

  • ClientToken: Added support for idempotency in CreateInvoiceUnit, DeleteInvoiceUnit, UpdateInvoiceUnit, DeleteProcurementPortalPreference, PutProcurementPortalPreference, and UpdateProcurementPortalPreferenceStatus.
  • Use Case: Prevent duplicate operations during retries or manual interventions.

• Security Agent Verification Scripts:

  • Verification Scripts: Download executable scripts to reproduce confirmed vulnerabilities from penetration test findings.
  • Use Case: Enhances security validation by allowing independent verification of findings.

• Performance Insights (PI) Recommendations:

  • ListRecommendations API: Retrieve actionable recommendations for performance analysis reports.
  • Use Case: Optimize database performance with automated insights.

• QConnect Guardrail Assessment:

  • Guardrail Results: Retrieve details on AI Guardrail policies evaluated during Bedrock Converse calls.
  • Use Case: Monitor content moderation and compliance in AI-driven applications.

3. Debugging Tips

• Metadata Directive Conflicts:

  • If metadata behaves unexpectedly, ensure the MetadataDirective is explicitly set and that user-provided metadata in the Metadata parameter takes precedence.
  • Example conflict scenario:

    // User metadata overrides source metadata
    $s3->copyObject([
        'MetadataDirective' => 'COPY', // Source metadata is copied
        'Metadata' => ['custom-key' => 'overrides-source'], // Overrides any source metadata
    ]);
    

• Idempotency Token Generation:

  • Use a UUID generator for ClientToken to ensure uniqueness:

    $clientToken = Str::uuid()->toString();
    

• Verification Script Execution:

  • Verify environment variables and dependencies are met before running downloaded scripts. Check the VerificationScript response for required variables and instructions.

4. General Best Practices

• Region Configuration:

  • Always explicitly configure regions for new services (e.g., AWS_IOT_WIRELESS_REGION, AWS_INVOICING_REGION) to avoid default region assumptions.

• Error Handling:

  • Use try-catch blocks for AWS API calls, especially for new services, to handle service-specific exceptions gracefully. Example:

    try {
        $response = $