PHPackages                             rajpurohithitesh/amazon-paapi5-php-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. rajpurohithitesh/amazon-paapi5-php-sdk

ActiveLibrary[API Development](/categories/api)

rajpurohithitesh/amazon-paapi5-php-sdk
======================================

Amazon Product Advertising API v5 PHP SDK (Most Advanced SDK)

v1.1.2(4mo ago)1158↓50%1Apache-2.0PHPPHP ^8.0CI passing

Since May 18Pushed 4mo ago1 watchersCompare

[ Source](https://github.com/RajpurohitHitesh/amazon-paapi5-php-sdk)[ Packagist](https://packagist.org/packages/rajpurohithitesh/amazon-paapi5-php-sdk)[ RSS](/packages/rajpurohithitesh-amazon-paapi5-php-sdk/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (6)Versions (14)Used By (0)

Amazon Product Advertising API 5.0 PHP SDK
==========================================

[](#amazon-product-advertising-api-50-php-sdk)

[![PHP Version](https://camo.githubusercontent.com/662e69dc67fee9b15c531ec533a692c2e1f6fb5b21ecd6ad489d0ecd06c11578/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e302532422d707572706c65)](https://camo.githubusercontent.com/662e69dc67fee9b15c531ec533a692c2e1f6fb5b21ecd6ad489d0ecd06c11578/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e302532422d707572706c65)[![Amazon API](https://camo.githubusercontent.com/51242e20817d46d132b9859398807a5baad566c38ab9e7016b0417f14cd2a101/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f416d617a6f6e2532304150492d352e302d253233464439423135)](https://webservices.amazon.com/paapi5/documentation/)[![Latest Version](https://camo.githubusercontent.com/89ec37fcdce8eb69a76e850ea48ee809f625a9747acbbf1130de5feee0409472/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f72616a7075726f6869746869746573682f616d617a6f6e2d7061617069352d7068702d73646b)](https://packagist.org/packages/rajpurohithitesh/amazon-paapi5-php-sdk)[![Total Downloads](https://camo.githubusercontent.com/b3bad62b3f2c0d8116ce90f79f62bb8d4f7efbf909f58456f79882193caa6713/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f72616a7075726f6869746869746573682f616d617a6f6e2d7061617069352d7068702d73646b2e7376673f7374796c653d666c6174)](https://packagist.org/packages/rajpurohithitesh/amazon-paapi5-php-sdk)[![License](https://camo.githubusercontent.com/d8e3b9d3b1213595b06824a404d41ad7743f1e880a3f9e47bae54533a9b60c99/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4170616368655f322e302d626c7565)](LICENSE.txt)[![Security Rating](https://camo.githubusercontent.com/3633ff7547dadf670368a7c37d138e25b8f2051435f376c3ae8e61822d8b5326/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d52616a7075726f6869744869746573685f616d617a6f6e2d7061617069352d7068702d73646b266d65747269633d73656375726974795f726174696e67)](https://sonarcloud.io/summary/new_code?id=RajpurohitHitesh_amazon-paapi5-php-sdk)[![Quality Gate Status](https://camo.githubusercontent.com/b382c2021f2a5987c963c6e9e75b10a0fd26ca286a667bc0ffdd7df02e8c09fa/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d52616a7075726f6869744869746573685f616d617a6f6e2d7061617069352d7068702d73646b266d65747269633d616c6572745f737461747573)](https://sonarcloud.io/summary/new_code?id=RajpurohitHitesh_amazon-paapi5-php-sdk)[![CI](https://github.com/RajpurohitHitesh/amazon-paapi5-php-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/RajpurohitHitesh/amazon-paapi5-php-sdk/actions/workflows/ci.yml)[![PHP Composer](https://github.com/RajpurohitHitesh/amazon-paapi5-php-sdk/actions/workflows/php.yml/badge.svg)](https://github.com/RajpurohitHitesh/amazon-paapi5-php-sdk/actions/workflows/php.yml)

This repository provides a lightweight, modern, and feature-rich PHP SDK for the Amazon Product Advertising API 5.0 (PAAPI5). It is designed to simplify the integration of Amazon product data into your PHP applications, offering robust error handling, caching, and support for all PAAPI5 operations.

⚠️ IMPORTANT: Migrate to OffersV2
---------------------------------

[](#️-important-migrate-to-offersv2)

**Offers V1 is being deprecated!** Amazon PA-API will eventually remove the old Offers API. All new features are only being added to OffersV2.

**➡️ [Read Migration Guide: Offers V1 → OffersV2](MIGRATION_OFFERS_V1_TO_V2.md)**

**Use OffersV2 for all new projects:**

- ✅ Better reliability and data quality
- ✅ Full deal information (Lightning Deals, Prime Exclusive)
- ✅ Enhanced pricing with savings details
- ✅ Merchant ID support
- ✅ All future features

See [OffersV2 Documentation](OFFERSV2_README.md) for complete details.

Table of Contents
-----------------

[](#table-of-contents)

1. [Introduction](#introduction)
    - [What is this SDK?](#what-is-this-sdk)
    - [Who is it for?](#who-is-it-for)
    - [Benefits of using this SDK](#benefits-of-using-this-sdk)
2. [Key Features](#key-features)
3. [Requirements](#requirements)
4. [Installation](#installation)
    - [Using Composer](#using-composer)
    - [External Cache Packages (Optional)](#external-cache-packages-optional)
5. [Getting Started: Basic Setup](#getting-started-basic-setup)
    - [Prerequisites: Amazon PAAPI Credentials](#prerequisites-amazon-paapi-credentials)
    - [Including the Autoloader](#including-the-autoloader)
    - [Initializing Configuration (`Config` class)](#initializing-configuration-config-class)
    - [Initializing the Client (`Client` class)](#initializing-the-client-client-class)
6. [Core Concepts](#core-concepts)
    - [Operations](#operations)
    - [Request Objects](#request-objects)
    - [Response Objects](#response-objects)
7. [Making API Calls: Supported Operations](#making-api-calls-supported-operations)
    - [7.1. Searching for Items (`SearchItems`)](#71-searching-for-items-searchitems)
    - [7.2. Getting Item Details (`GetItems`)](#72-getting-item-details-getitems)
    - [7.3. Getting Product Variations (`GetVariations`)](#73-getting-product-variations-getvariations)
    - [7.4. Getting Browse Nodes (`GetBrowseNodes`)](#74-getting-browse-nodes-getbrowsenodes)
8. [Advanced Usage](#advanced-usage)
    - [8.1. Asynchronous Requests](#81-asynchronous-requests)
    - [8.2. Batch Operations (Conceptual)](#82-batch-operations-conceptual)
9. [Configuration In-Depth](#configuration-in-depth)
    - [9.1. Marketplace Configuration](#91-marketplace-configuration)
    - [9.2. Throttling and Rate Limiting](#92-throttling-and-rate-limiting)
    - [9.3. Caching Strategy](#93-caching-strategy)
    - [9.4. Credential Management and Encryption](#94-credential-management-and-encryption)
    - [9.5. Logging (PSR-3)](#95-logging-psr-3)
10. [Error Handling and Exceptions](#error-handling-and-exceptions)
    - [Custom Exception Hierarchy](#custom-exception-hierarchy)
    - [Handling Exceptions](#handling-exceptions)
11. [Security Best Practices](#security-best-practices)
12. [Performance Considerations](#performance-considerations)
13. [Contributing](#contributing)
14. [Official Amazon PAAPI Documentation](#official-amazon-paapi-documentation)

1. Introduction
---------------

[](#1-introduction)

### What is this SDK?

[](#what-is-this-sdk)

The Amazon Product Advertising API 5.0 PHP SDK is a powerful library that allows PHP developers to easily access Amazon's vast product catalog and advertising functionalities. It handles the complexities of API requests, authentication, and response parsing, letting you focus on building features for your application.

### Who is it for?

[](#who-is-it-for)

This SDK is for PHP developers who want to:

- Display Amazon product information (details, prices, images, reviews) on their websites or applications.
- Search for Amazon products based on various criteria.
- Retrieve information about product variations (e.g., different sizes or colors).
- Explore Amazon's product category structure (browse nodes).
- Build affiliate marketing solutions by leveraging Amazon's product data.

### Benefits of using this SDK

[](#benefits-of-using-this-sdk)

- **Simplified API Interaction:** Abstracts the low-level details of HTTP requests, signing, and XML/JSON parsing.
- **Modern PHP Practices:** Utilizes modern PHP features, PSR standards, and a clean architecture.
- **Time-Saving:** Reduces development time with pre-built functionalities for all PAAPI5 operations.
- **Robust and Reliable:** Includes features like smart throttling, caching, and comprehensive error handling.
- **Secure:** Implements AWS Signature V4 and credential encryption.

2. Key Features
---------------

[](#2-key-features)

This SDK is packed with features to make your development experience smooth and efficient:

- **Full PAAPI5 Operation Support:**
    - `SearchItems`: Find products based on keywords, category, and other filters.
    - `GetItems`: Retrieve detailed information for specific products using their ASINs or other identifiers.
    - `GetVariations`: Fetch available variations (like size, color) for a given product.
    - `GetBrowseNodes`: Access Amazon's category hierarchy.
- **Smart Throttling & Rate Limiting:**
    - Configurable delay between requests (default: 1 second).
    - Automatic request queueing and exponential backoff (conceptual, primarily managed by `ThrottleManager` delay) to respect Amazon's API rate limits.
- **PSR-6 Compliant Caching:**
    - Includes a built-in `FileCache` and `AdvancedCache` implementation.
    - Easily integrate external caching solutions like Redis or Memcached that implement `Psr\Cache\CacheItemPoolInterface`.
    - Configurable cache Time-To-Live (TTL).
- **Asynchronous Operations:**
    - Leverages Guzzle promises for non-blocking API calls, enabling parallel execution and efficient resource utilization.
- **Type-Safe Request/Response Models:**
    - Strictly typed PHP objects for building requests and handling responses.
    - Improves code reliability and enables better autocompletion in IDEs. (Located in `src/Models/Request/` and `src/Models/Response/`)
- **Comprehensive Marketplace Support:**
    - Supports all major Amazon marketplaces (e.g., US, UK, DE, JP, IN, CA, AU).
    - Automatic detection and configuration of regional API endpoints via the `Marketplace` class.
- **Robust Security:**
    - **Credential Encryption:** Uses OpenSSL (AES-256-CBC) to encrypt your AWS Access Key and Secret Key when an `encryption_key` is provided in the configuration. Managed by `Security\CredentialManager`.
    - **Advanced Encryption with Intelligent Fallback:**
    - **Primary Method - Sodium:** High-performance libsodium encryption with ChaCha20-Poly1305 authenticated encryption
    - **Fallback Method - OpenSSL:** AES-256-GCM encryption when Sodium is unavailable
    - **Automatic Detection:** Seamlessly switches between encryption methods based on server capabilities
    - **Cross-Platform Compatibility:** Works on any server configuration
    - **Method Migration Support:** Smooth transition between encryption methods without data loss
    - **Encryption Method Tagging:** Each encrypted credential is tagged with its encryption method for proper decryption
    - **AWS Signature Version 4:** All API requests are securely signed. Handled by `Auth\AwsV4Signer`.
    - **HTTPS Enforcement:** All communication with the API is over HTTPS.
- **Performance Optimizations:**
    - **Connection Reuse:** GuzzleHttp client is configured for connection reuse (Keep-Alive).
    - **Gzip Compression:** Supports Gzip for request and response bodies to reduce network latency (handled by Guzzle).
    - **Batch Processing for `GetItems`:** Retrieve data for up to 10 ASINs in a single `GetItems` request.
    - **Memory-Efficient Parsing:** Optimized object hydration from API responses.
- **Detailed Error Handling:**
    - A clear hierarchy of custom exceptions (e.g., `AuthenticationException`, `ThrottleException`, `RequestException`) for easier debugging and error management. (Located in `src/Exceptions/`)
- **Lightweight & PSR-12 Compliant:**
    - Minimal external dependencies (primarily GuzzleHttp).
    - Adheres to PSR-12 coding standards for clean and maintainable code.
- **PSR-3 Logging Support:**
    - Allows integration with any PSR-3 compatible logger (like Monolog) for detailed logging of API interactions.

3. Requirements
---------------

[](#3-requirements)

- **PHP:** 8.0 or higher
- **Required Extensions:**
    - `curl` (usually enabled by default)
    - `json` (usually enabled by default)
    - `openssl` (required for encryption fallback)
    - `sodium` (required - for optimal security and performance)
- **Encryption Method Priority:**
    1. **Sodium** (preferred) - Primary encryption method
    2. **OpenSSL** (fallback) - Used when Sodium unavailable
    3. **Installation fails** - If neither is available
- **Composer:** For managing dependencies.
- **GuzzleHttp:** `^7.0` (automatically installed as a dependency).
- **PSR-6 Cache Implementation (Optional):** If you plan to use an external cache like Redis or Memcached, you'll need a corresponding PSR-6 adapter (e.g., `symfony/cache`).

### Installation Options

[](#installation-options)

**Standard Installation (Recommended):**

```
composer require rajpurohithitesh/amazon-paapi5-php-sdk

## 4. Installation

### Using Composer

The recommended way to install the SDK is via [Composer](https://getcomposer.org/). Run the following command in your project's root directory:

```sh
composer require rajpurohithitesh/amazon-paapi5-php-sdk
```

This will download the SDK and its dependencies into your project's `vendor` directory.

### External Cache Packages (Optional)

[](#external-cache-packages-optional)

If you wish to use an external caching mechanism (like Redis or Memcached) instead of the built-in file cache, you'll need to install a PSR-6 compatible cache adapter. For example, to use Symfony Cache with Redis:

```
composer require symfony/cache symfony/redis-adapter
```

5. Getting Started: Basic Setup
-------------------------------

[](#5-getting-started-basic-setup)

### Prerequisites: Amazon PAAPI Credentials

[](#prerequisites-amazon-paapi-credentials)

Before you can use the SDK, you need to have valid Amazon Product Advertising API credentials:

1. **Access Key ID**
2. **Secret Access Key**
3. **Partner Tag (Associate Tag)**

You can obtain these by registering for the Amazon Associates Program and then for the Product Advertising API. Ensure your account has been approved and has API access.

### Including the Autoloader

[](#including-the-autoloader)

If you're using Composer, include the Composer-generated autoloader file at the beginning of your PHP script:

```