### Returns

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/quick-reference.md

Examples for getting returns, accepting/refusing, marking as received, and updating return information.

```php
// Get returns
use Mirakl\MMP\Shop\Request\Returns\GetReturnsRequest;
$returns = $api->getReturns(
    (new GetReturnsRequest())->setLimit(50)
);

// Accept/refuse return
use Mirakl\MMP\Shop\Request\Returns\AcceptOrRefuseReturnsRequest;
$request = (new AcceptOrRefuseReturnsRequest())->setReturns([
    ['return_id' => 'RET001', 'accept' => true],
]);
$result = $api->acceptOrRefuseReturns($request);

// Mark as received
use Mirakl\MMP\Shop\Request\Returns\ReceiveReturnsRequest;
$request = (new ReceiveReturnsRequest())->setReturns(['RET001']);
$result = $api->receiveReturns($request);

// Update returns
use Mirakl\MMP\Shop\Request\Returns\UpdateReturnsRequest;
$request = (new UpdateReturnsRequest())->setReturns([
    ['return_id' => 'RET001', 'comment' => 'Item received'],
]);
$result = $api->updateReturns($request);
```

--------------------------------

### Basic Setup

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/quick-reference.md

Initialize the ShopApiClient with your environment URL, API key, and Shop ID.

```php
require 'vendor/autoload.php';

use Mirakl\MMP\Shop\Client\ShopApiClient;

$api = new ShopApiClient(
    'https://your.env/api',
    'your_api_key',
    'SHOP_ID'
);
```

--------------------------------

### Multi-Module Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/quick-reference.md

An example showing how to use different Mirakl API clients (MMP for orders/offers, MCI for catalog) within the same application and how they can interact.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient as MmpClient;
use Mirakl\MCI\Shop\Client\ShopApiClient as MciClient;

// MMP for orders/offers
$mmp = new MmpClient('URL', 'KEY', 'SHOP');
$offers = $mmp->getOffers(new GetOffersRequest());

// MCI for catalog
$mci = new MciClient('URL', 'KEY', 'SHOP');
$attrs = $mci->getAttributes(new GetAttributesRequest());

// Use together
foreach ($offers as $offer) {
    $sku = $offer->getSku();
    // Use MCI to get product attributes for this SKU
}
```

--------------------------------

### Messages

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/quick-reference.md

Examples for posting, getting, and retrieving thread details for messages.

```php
// Post message
use Mirakl\MMP\Shop\Request\Order\Message\CreateOrderMessageRequest;
$request = (new CreateOrderMessageRequest('ORDER_ID'))
    ->setMessage('Status update')
    ->setSubject('Order Status');
$created = $api->createOrderMessage($request);

// Get messages
use Mirakl\MMP\Shop\Request\Order\Message\GetOrderMessagesRequest;
$messages = $api->getOrderMessages(new GetOrderMessagesRequest());

// Get thread details
use Mirakl\MMP\OperatorShop\Request\Message\GetThreadDetailsRequest;
$thread = $api->getThreadDetails(new GetThreadDetailsRequest('THREAD_ID'));
foreach ($thread->getMessages() as $msg) {
    echo $msg->getBody();
}
```

--------------------------------

### Account & Configuration

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/quick-reference.md

Examples for retrieving and updating shop account details, and fetching platform configuration, reasons, and shipping settings.

```php
// Get shop account
use Mirakl\MMP\Shop\Request\Shop\GetAccountRequest;
$account = $api->getAccount(new GetAccountRequest());
echo $account->getEmail();

// Update account
use Mirakl\MMP\Shop\Request\Shop\UpdateAccountRequest;
$request = (new UpdateAccountRequest())->setAccount([
    'contact_info' => ['phone' => '1234567890'],
]);
$result = $api->updateAccount($request);

// Get platform config
use Mirakl\MMP\Shop\Request\PlatformConfiguration\GetPlatformConfigurationRequest;
$config = $api->getPlatformConfiguration(
    new GetPlatformConfigurationRequest()
);

// Get reasons
use Mirakl\MMP\Shop\Request\Reason\GetReasonsRequest;
$reasons = $api->getReasons(new GetReasonsRequest());

// Get shipping configuration
$carriers = $api->getShippingCarriers();
$zones = $api->getShippingZones(new GetShippingZonesRequest());
$types = $api->getShippingTypes(new GetShippingTypesRequest());
```

--------------------------------

### async() Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/mmp-shop-api-client.md

Example of using the async() method to get a promise.

```php
$promise = $api->async()->getOffers($request);
// Returns GuzzleHttp\Promise\PromiseInterface
$result = $promise->wait();
```

--------------------------------

### Usage Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/README.md

Demonstrates how to instantiate the client, build a request, and call the API to get an offer. It also shows how to retrieve the raw HTTP response.

```php
<?php
require 'vendor/autoload.php';

use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\Offer\GetOfferRequest;

// Environment parameters
$url = 'https://your.env/api';
$apiKey = 'your_api_key';

try {
    // Instantiating the Mirakl API Client
    $api = new ShopApiClient('API_URL', 'API_KEY', 'SHOP_ID');

    // Building request
    $request = new GetOfferRequest('OFFER_ID');

    // Calling the API
    $result = $api->getOffer($request);
    var_dump($result); // \Mirakl\MMP\Shop\Domain\Offer\ShopOffer

    // You can also retrieve raw response by using run() method of API client:
    $result = $api->run($request); // or $api->raw()->getOffer($request)
    var_dump($result); // returns \Psr\Http\Message\ResponseInterface

} catch (\Exception $e) {
    // An exception is thrown if object requested is not found or if an error occurs
    var_dump($e);
}

```

--------------------------------

### Get Offer Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/mmp-shop-api-client.md

Example of retrieving a single offer by ID.

```php
use Mirakl\MMP\Shop\Request\Offer\GetOfferRequest;

$request = new GetOfferRequest('OFFER_ID');
$offer = $api->getOffer($request);

echo $offer->getId(); // OFFER_ID
echo $offer->getPrice(); // 99.99
echo $offer->getQuantity(); // 50
```

--------------------------------

### Installation

Source: https://github.com/mirakl/sdk-php-shop/blob/master/README.md

Install the SDK using Composer.

```bash
composer require mirakl/sdk-php-shop
```

--------------------------------

### Constructor Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/mci-shop-api-client.md

Example of how to instantiate the ShopApiClient.

```php
use Mirakl\MCI\Shop\Client\ShopApiClient;

$api = new ShopApiClient(
    'https://your.env/api',
    'your_api_key',
    'SHOP_ID'
);
```

--------------------------------

### async() Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/core-api-client.md

Example of enabling asynchronous mode to get a promise for the response.

```php
$promise = $client->async(true)->getOffers($request);
// Returns GuzzleHttp\Promise\PromiseInterface
$result = $promise->wait();
```

--------------------------------

### Utility Functions

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/quick-reference.md

Examples of various utility functions available in the SDK for file creation, date formatting, version retrieval, string manipulation, and array utilities.

```php
// Create CSV file
$file = Mirakl\create_temp_csv_file([
    ['col1', 'col2'],
    ['val1', 'val2'],
]);

// Create file from string
$file = Mirakl\create_temp_file('content here');

// Format date
$iso = Mirakl\date_format(new \DateTime('2024-01-01'));

// Get SDK version
echo Mirakl\get_version();

// String conversion
echo Mirakl\pascalize('my_var');      // MyVar
echo Mirakl\underscorize('MyVar');    // my_var

// Array utilities
Mirakl\remove_null_values($data);
Mirakl\array_is_assoc($arr);
Mirakl\array_format($data);
```

--------------------------------

### Catalog (MCI)

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/quick-reference.md

Examples for interacting with the Mirakl Catalog Integration (MCI) for attributes, hierarchies, product imports, and status checks.

```php
use Mirakl\MCI\Shop\Client\ShopApiClient as MciClient;

$mci = new MciClient('URL', 'KEY', 'SHOP_ID');

// Get attributes
use Mirakl\MCI\Shop\Request\Attribute\GetAttributesRequest;
$attrs = $mci->getAttributes(
    (new GetAttributesRequest())->setLocale('en')
);

// Get hierarchies
use Mirakl\MCI\Shop\Request\Hierarchy\GetHierarchiesRequest;
$hierarchies = $mci->getHierarchies(new GetHierarchiesRequest());

// Import products
use Mirakl\MCI\Shop\Request\Product\ProductImportRequest;
$file = Mirakl\create_temp_csv_file([
    ['sku', 'name', 'description'],
    ['SKU001', 'Product 1', 'Description...'],
]);
$tracking = $mci->importProducts(new ProductImportRequest($file));

// Check import status
use Mirakl\MCI\Shop\Request\Product\ProductImportStatusRequest;
sleep(5);
$status = $mci->getProductImportStatus(
    new ProductImportStatusRequest($tracking->getImportId())
);
echo $status->getStatus();
```

--------------------------------

### Get Account Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/mmp-shop-api-client.md

Example of retrieving shop account information.

```php
$api = new ShopApiClient('API_URL', 'API_KEY', 'SHOP_ID');
$account = $api->getAccount();

echo $account->getId(); // SHOP_ID
echo $account->getEmail(); // shop@example.com
echo $account->getContactInfo()->getName(); // Shop name
```

--------------------------------

### Constructor Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/mmp-shop-api-client.md

Example of how to instantiate the ShopApiClient.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;

$api = new ShopApiClient(
    'https://your.env/api',
    'your_api_key',
    'SHOP_ID'
);
```

--------------------------------

### GetOffersRequest Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/requests-reference.md

Example demonstrating the use of GetOffersRequest with pagination, state filtering, and sorting.

```php
$request = new GetOffersRequest();
$request->setLimit(50)
        ->setOffset(0)
        ->setStates(['ACTIVE', 'INACTIVE'])
        ->setSortBy('updated_date')
        ->setDir('DESC');

$offers = $api->getOffers($request);
```

--------------------------------

### GetOfferRequest Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/requests-reference.md

Example of how to instantiate and use GetOfferRequest to fetch offer details.

```php
$request = new GetOfferRequest('OFFER_ID');
$offer = $api->getOffer($request);
```

--------------------------------

### Get Attributes Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/mci-shop-api-client.md

Example of retrieving product attributes with a locale filter.

```php
use Mirakl\MCI\Shop\Request\Attribute\GetAttributesRequest;

$request = new GetAttributesRequest();
$request->setLocale('en');
$attributes = $api->getAttributes($request);

foreach ($attributes as $attr) {
    echo $attr->getCode();       // e.g., 'brand'
    echo $attr->getLabel();      // e.g., 'Brand'
    echo $attr->getType();       // e.g., 'text' or 'select'
    echo $attr->isRequired();    // true/false
}
```

--------------------------------

### Get Value Lists Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/mci-shop-api-client.md

Example of retrieving predefined value lists for specific attribute codes and locale.

```php
use Mirakl\MCI\Shop\Request\ValueList\GetValueListsItemsRequest;

$request = new GetValueListsItemsRequest();
$request->setAttributeCodes(['color', 'size']);
$request->setLocale('en');

$valueLists = $api->getValueLists($request);
// Access values per attribute code
```

--------------------------------

### UpdateOffersRequest Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/requests-reference.md

Example of how to set offers for the UpdateOffersRequest.

```php
public function setOffers(array $offers): self
public function getOffers(): array
```

```php
$request = new UpdateOffersRequest();
$request->setOffers([
    [
        'offer_id' => 'OFFER001',
        'price' => 99.99,
        'quantity' => 100,
        'leadtime_to_ship' => 5,
    ],
    // ... more offers
]);
```

--------------------------------

### raw() Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/core-api-client.md

Example of enabling raw mode to get a raw PSR-7 response object.

```php
$response = $client->raw(true)->getOffer($request);
// $response is Psr\Http\Message\ResponseInterface
 echo $response->getStatusCode();
```

--------------------------------

### raw() Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/mmp-shop-api-client.md

Example of using the raw() method to get a raw PSR-7 ResponseInterface.

```php
$response = $api->raw()->getOffer($request);
// $response is Psr\Http\Message\ResponseInterface
echo $response->getStatusCode();
```

--------------------------------

### Get Hierarchies Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/mci-shop-api-client.md

Example of retrieving product classification hierarchies with a locale filter.

```php
use Mirakl\MCI\Shop\Request\Hierarchy\GetHierarchiesRequest;

$request = new GetHierarchiesRequest();
$request->setLocale('en');
$hierarchies = $api->getHierarchies($request);

foreach ($hierarchies as $hierarchy) {
    echo $hierarchy->getCode();   // e.g., 'PRODUCTS_EN'
    echo $hierarchy->getLabel();  // e.g., 'Products'
}
```

--------------------------------

### Offers

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/quick-reference.md

Common operations for managing offers, including getting, importing, updating, and exporting.

```php
// Get single offer
use Mirakl\MMP\Shop\Request\Offer\GetOfferRequest;
$offer = $api->getOffer(new GetOfferRequest('OFFER_ID'));

// Get multiple offers
use Mirakl\MMP\Shop\Request\Offer\GetOffersRequest;
$request = (new GetOffersRequest())->setLimit(50)->setOffset(0);
$offers = $api->getOffers($request);

// Import offers (CSV)
use Mirakl\MMP\Shop\Request\Offer\Importer\OfferImportRequest;
$file = Mirakl\create_temp_csv_file([
    ['offer_id', 'sku', 'price', 'quantity'],
    ['OFF001', 'SKU001', '99.99', '100'],
]);
$tracking = $api->importOffers(new OfferImportRequest($file));

// Update offers
use Mirakl\MMP\Shop\Request\Offer\UpdateOffersRequest;
$request = (new UpdateOffersRequest())->setOffers([
    ['offer_id' => 'OFF001', 'price' => 89.99],
]);
$tracking = $api->updateOffers($request);

// Export offers
use Mirakl\MMP\Shop\Request\Offer\OffersExportRequest;
$offers = $api->exportOffers(new OffersExportRequest());
```

--------------------------------

### run() Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/core-api-client.md

Example of executing a request synchronously and accessing the response status code and body.

```php
$response = $client->run($request);
 echo $response->getStatusCode();
 echo $response->getBody();
```

--------------------------------

### LocalizableTrait Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/requests-reference.md

Example demonstrating the usage of LocalizableTrait for setting the locale.

```php
$request = new GetAttributesRequest();
$request->setLocale('en_US');
```

--------------------------------

### OfferImportRequest Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/requests-reference.md

Example of how to prepare CSV data and use OfferImportRequest to import offers.

```php
$csv = [
    ['offer_id', 'sku', 'price', 'quantity'],
    ['OFF001', 'SKU001', '99.99', '100'],
    ['OFF002', 'SKU002', '149.99', '50'],
];

$request = new OfferImportRequest(
    Mirakl\create_temp_csv_file($csv)
);

$tracking = $api->importOffers($request);
```

--------------------------------

### Async Operations

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/quick-reference.md

Illustrates how to perform asynchronous operations, retrieve raw responses, and configure logging.

```php
// Async mode
$promise = $api->async()->getOffers($request);
$offers = $promise->wait();

// Raw response
$response = $api->raw()->getOffer($request);
echo $response->getStatusCode();

// Logging
use Monolog\Logger;
use Monolog\Handlers\StreamHandler;

$logger = new Logger('mirakl');
$logger->pushHandler(new StreamHandler('mirakl.log'));
$api->setLogger($logger);
```

--------------------------------

### UploadOrdersDocumentsRequest Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/requests-reference.md

Example of how to upload documents for an order.

```php
$request = new UploadOrdersDocumentsRequest();
$request->setOrderId('ORDER123')
        ->setDocumentType('INVOICE');

$file = Mirakl\create_temp_file('Invoice content...');
$wrapper = new FileWrapper($file);
$wrapper->setFileName('invoice.pdf');

$request->addFile($wrapper);
$result = $api->uploadOrderDocuments($request);
```

--------------------------------

### pascalize() Examples

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/utilities.md

Demonstrates the pascalize function converting underscore strings to Pascal Case.

```php
echo Mirakl\pascalize('my_class_name');      // MyClassName
echo Mirakl\pascalize('order_id');           // OrderId
echo Mirakl\pascalize('shop-account-info');  // ShopAccountInfo
```

--------------------------------

### Get Source Product Data Sheet Status File Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/mcm-shop-api-client.md

Downloads a source product data sheet as a file.

```php
use Mirakl\MCM\Shop\Request\Catalog\Product\GetSourceProductDataSheetStatusFileRequest;

$request = new GetSourceProductDataSheetStatusFileRequest();
$file = $api->getSourceProductDataSheetStatusFile($request);

// Save or process file
$file->getFile()->rewind();
file_put_contents('datasheet.xlsx', $file->getFile()->fread($file->getFile()->fstat()['size']));
```

--------------------------------

### Client Configuration

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/quick-reference.md

Demonstrates how to configure the API client, including setting base URL, API key, shop ID, user agent, and request options like timeout and SSL verification.

```php
$api->setBaseUrl('new_url');
$api->setApiKey('new_key');
$api->setShopId('new_shop');
$api->setUserAgent('MyApp/1.0');

$api->addOption('timeout', 30);
$api->addOption('connect_timeout', 10);
$api->addOption('verify', false);  // Disable SSL verification

$api->disable(true);   // Disable requests
$api->disable(false);  // Re-enable
```

--------------------------------

### get_version() Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/utilities.md

Retrieves and displays the current SDK version.

```php
echo "Using SDK version: " . Mirakl\get_version();
// Output: Using SDK version: 1.23.0
```

--------------------------------

### create_temp_file() Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/utilities.md

Creates a temporary file filled with contents and demonstrates reading from it.

```php
$file = Mirakl\create_temp_file('CSV content here');
$file->rewind();
echo $file->fgets(); // Read content
```

--------------------------------

### PageableTrait Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/requests-reference.md

Example demonstrating the usage of PageableTrait for setting limit, offset, and page token for pagination.

```php
$request = new GetOrdersRequest();
$request->setLimit(50)
        ->setOffset(0);

// Token-based pagination
$request->setPageToken('next_page_token');
```

--------------------------------

### Get Single Resource

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/configuration-and-patterns.md

Example of fetching a single resource, such as an offer, using its ID.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\Offer\GetOfferRequest;

$api = new ShopApiClient('URL', 'KEY');
$request = new GetOfferRequest('OFFER_123');
$offer = $api->getOffer($request);

echo $offer->getId();
echo $offer->getPrice();
echo $offer->getQuantity();
```

--------------------------------

### CreateRefundRequest Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/requests-reference.md

Example of how to request a refund for an order using CreateRefundRequest.

```php
public function setRefunds(array $refunds): self
public function getRefunds(): array
```

```php
$request = new CreateRefundRequest();
$request->setRefunds([
    [
        'order_line_id' => 'LINE001',
        'reason_code' => 'PRODUCT_DEFECT',
        'amount' => 99.99,
        'quantity' => 1,
    ],
]);
```

--------------------------------

### Basic Client Setup

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/configuration-and-patterns.md

Sets up the basic ShopApiClient with base URL, API key, and an optional shop ID.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;

$api = new ShopApiClient(
    'https://your-environment.mirakl.net/api', // Base URL
    'your_api_key_here',                       // API Key
    'SHOP_ID'                                  // Shop ID (optional)
);
```

--------------------------------

### Orders

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/quick-reference.md

Common operations for managing orders, including getting, accepting, canceling, and requesting refunds.

```php
// Get orders
use Mirakl\MMP\Shop\Request\Order\Get\GetOrdersRequest;
$request = (new GetOrdersRequest())
    ->setLimit(100)
    ->setStates(['ACCEPTED', 'SHIPPED'])
    ->setStartDate(new \DateTime('2024-01-01'));
$orders = $api->getOrders($request);

// Accept order
use Mirakl\MMP\Shop\Request\Order\Accept\AcceptOrderRequest;
$api->acceptOrder(new AcceptOrderRequest('ORDER_ID'));

// Cancel order
use Mirakl\MMP\Shop\Request\Order\Workflow\CancelOrderRequest;
$api->cancelOrder(new CancelOrderRequest('ORDER_ID'));

// Cancel order lines
use Mirakl\MMP\Shop\Request\Order\Cancelation\CreateCancelationsRequest;
$request = (new CreateCancelationsRequest())->setCancelations([
    ['order_line_id' => 'LINE001', 'quantity' => 1, 'reason_code' => 'OUT_OF_STOCK'],
]);
$result = $api->requestCancelOrderLines($request);

// Request refund
use Mirakl\MMP\Shop\Request\Order\Refund\CreateRefundRequest;
$request = (new CreateRefundRequest())->setRefunds([
    ['order_line_id' => 'LINE001', 'amount' => 99.99],
]);
$result = $api->requestRefundOrder($request);

// Update orders
use Mirakl\MMP\Shop\Request\Order\Update\UpdateOrdersRequest;
$request = (new UpdateOrdersRequest())->setOrders([
    ['order_id' => 'ORDER001', 'custom_field' => 'value'],
]);
$results = $api->updateOrders($request);
```

--------------------------------

### Product Import Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/mci-shop-api-client.md

Example of importing products via file upload (CSV format).

```php
use Mirakl\MCI\Shop\Request\Product\ProductImportRequest;

$file = new \SplFileObject('/path/to/products.csv');
$request = new ProductImportRequest($file);
$tracking = $api->importProducts($request);

echo $tracking->getImportId();
// Use this ID to poll import status
```

--------------------------------

### MiraklObject Decorator Usage

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/utilities.md

Example of using a response decorator to get a single domain object.

```php
// In request class
public function getResponseDecorator()
{
    return ShopOffer::decorator();
}
```

--------------------------------

### addOption() Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/core-api-client.md

Example of adding Guzzle HTTP client options like timeout and connect_timeout.

```php
$client->addOption('timeout', 30)
       ->addOption('connect_timeout', 10);
```

--------------------------------

### setLogger() example usage

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/core-api-client.md

Example of setting up a Monolog logger and attaching it to the client.

```php
use Monolog\Logger;
use Monolog\Handlers\StreamHandler;

$logger = new Logger('mirakl');
$logger->pushHandler(new StreamHandler('php://stdout'));

$client->setLogger($logger);
```

--------------------------------

### SortableTrait Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/requests-reference.md

Example demonstrating the usage of SortableTrait for setting sorting field and direction.

```php
$request = new GetOrdersRequest();
$request->setSortBy('created_date')
        ->setDir('DESC');
```

--------------------------------

### Constructor Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/mcm-shop-api-client.md

Instantiates the ShopApiClient with base URL, API key, and an optional shop ID.

```php
use Mirakl\MCM\Shop\Client\ShopApiClient;

$api = new ShopApiClient(
    'https://your.env/api',
    'your_api_key',
    'SHOP_ID'
);
```

--------------------------------

### UpdateOrdersRequest Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/requests-reference.md

Example of how to update multiple orders using UpdateOrdersRequest.

```php
public function setOrders(array $orders): self
public function getOrders(): array
```

```php
$request = new UpdateOrdersRequest();
$request->setOrders([
    [
        'order_id' => 'ORDER001',
        'custom_field_1' => 'value1',
    ],
    [
        'order_id' => 'ORDER002',
        'custom_field_1' => 'value2',
    ],
]);

$results = $api->updateOrders($request);
```

--------------------------------

### Get Source Product Data Sheet Status Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/mcm-shop-api-client.md

Retrieves the status of source product data sheets.

```php
use Mirakl\MCM\Shop\Request\Catalog\Product\GetSourceProductDataSheetStatusRequest;

$request = new GetSourceProductDataSheetStatusRequest();
$statuses = $api->getSourceProductDataSheetStatus($request);

foreach ($statuses as $status) {
    // Access status properties
}
```

--------------------------------

### Shipments

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/quick-reference.md

Common operations for managing shipments, including getting items to ship, creating, and shipping shipments.

```php
// Get items to ship
use Mirakl\MMP\Shop\Request\Shipment\GetItemsToShipRequest;
$items = $api->getItemsToShip(new GetItemsToShipRequest());

// Create shipments
use Mirakl\MMP\Shop\Request\Shipment\CreateShipmentsRequest;
$request = (new CreateShipmentsRequest())->setItems($items);
$created = $api->createShipments($request);

// Ship shipments
use Mirakl\MMP\Shop\Request\Shipment\ShipShipmentsRequest;
$request = new ShipShipmentsRequest();
foreach ($created->getShipments() as $shipment) {
    $request->addShipment([
        'shipment_id' => $shipment->getId(),
        'tracking_number' => 'TRACK123',
        'carrier_code' => 'DHL',
    ]);
}
$result = $api->shipShipments($request);

// Update tracking
use Mirakl\MMP\Shop\Request\Shipment\UpdateShipmentTrackingsRequest;
$request = (new UpdateShipmentTrackingsRequest())->setTrackings([
    ['shipment_id' => 'SHIP001', 'tracking_number' => 'NEW_TRACK'],
]);
$result = $api->updateShipmentTrackings($request);
```

--------------------------------

### default_user_agent() Example (default)

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/utilities.md

Generates the default User-Agent string for the SDK.

```php
$ua = Mirakl\default_user_agent();
// Output: Mirakl-PHP-SDK/1.23.0 GuzzleHttp/7.4.5 curl/7.68.0 PHP/8.1.0
```

--------------------------------

### FileCollection Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/types.md

Example of creating and adding files to a FileCollection.

```php
$files = new FileCollection();
$files->add(new FileWrapper(new \SplFileObject('file1.pdf')));
$files->add(new FileWrapper(new \SplFileObject('file2.pdf')));
```

--------------------------------

### Documents

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/quick-reference.md

Operations for uploading and downloading documents related to orders and invoices.

```php
// Upload order documents
use Mirakl\MMP\Shop\Request\Order\Document\UploadOrdersDocumentsRequest;
use Mirakl\Core\Domain\FileWrapper;

$request = (new UploadOrdersDocumentsRequest())
    ->setOrderId('ORDER_ID')
    ->setDocumentType('INVOICE');

$file = Mirakl\create_temp_file('Invoice content...');
$wrapper = (new FileWrapper($file))->setFileName('invoice.pdf');
$request->addFile($wrapper);

$result = $api->uploadOrderDocuments($request);

// Download documents
use Mirakl\MMP\Shop\Request\Order\Document\DownloadOrdersDocumentsRequest;
$request = (new DownloadOrdersDocumentsRequest())->setDocumentIds(['DOC_ID']);
$file = $api->downloadOrdersDocuments($request);
$file->getFile()->rewind();
file_put_contents($file->getFileName(), 
    $file->getFile()->fread($file->getFile()->fstat()['size']));

// Download invoice
use Mirakl\MMP\Shop\Request\Payment\Invoice\DownloadInvoiceRequest;
$file = $api->downloadInvoice(new DownloadInvoiceRequest('INVOICE_ID'));
```

--------------------------------

### Import Offers Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/mmp-shop-api-client.md

Example of importing offers via file upload (CSV format).

```php
use Mirakl\MMP\Shop\Request\Offer\Importer\OfferImportRequest;

$file = new \SplFileObject('/path/to/offers.csv');
$request = new OfferImportRequest($file);
$tracking = $api->importOffers($request);

echo $tracking->getImportId(); // ID for polling import status
```

--------------------------------

### UpdateOrderTrackingInfoRequest Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/requests-reference.md

Example of how to update tracking for order lines using UpdateOrderTrackingInfoRequest.

```php
public function setOrderLines(array $lines): self
```

```php
$request = new UpdateOrderTrackingInfoRequest();
$request->setOrderLines([
    [
        'order_line_id' => 'LINE001',
        'tracking_number' => 'TRACK123456',
        'carrier_code' => 'DHL',
        'is_delivered' => false,
    ],
]);
```

--------------------------------

### __call() example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/core-api-client.md

Demonstrates equivalent ways to execute a request using dynamic method calling.

```php
// These are equivalent:
$result = $client->getOffer($request);
$result = $request->run($client);
$result = $client($request); // Using __invoke
```

--------------------------------

### GetOrdersRequest Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/requests-reference.md

Example of how to retrieve orders with filtering using GetOrdersRequest.

```php
public function setOrderIds(array $ids): self
public function getOrderIds(): array

public function setStates(array $states): self
public function getStates(): array

public function setStartDate(\DateTime $date): self
public function getStartDate(): \DateTime

public function setEndDate(\DateTime $date): self
public function getEndDate(): \DateTime

public function setChannelCode(string $code): self
public function getChannelCode(): string
```

```php
$request = new GetOrdersRequest();
$request->setLimit(100)
        ->setOffset(0)
        ->setStates(['ACCEPTED', 'SHIPPED'])
        ->setStartDate(new \DateTime('2024-01-01'))
        ->setEndDate(new \DateTime('2024-12-31'))
        ->setSortBy('updated_date')
        ->setDir('DESC');

$orders = $api->getOrders($request);
```

--------------------------------

### File Upload Pattern

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/utilities.md

Example of uploading a file using create_temp_csv_file and OfferImportRequest.

```php
use Mirakl\Core\Domain\FileWrapper;
use Mirakl\MMP\Shop\Request\Offer\Importer\OfferImportRequest;

// Create CSV file
$file = Mirakl\create_temp_csv_file([
    ['offer_id', 'sku', 'price', 'quantity'],
    ['OFFER001', 'SKU001', '99.99', '100'],
    ['OFFER002', 'SKU002', '149.99', '50'],
]);

// Create request
$request = new OfferImportRequest($file);

// Import
$tracking = $api->importOffers($request);
echo $tracking->getImportId(); // Poll for status
```

--------------------------------

### setClient() example usage

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/core-api-client.md

Example of creating and setting a custom Guzzle HTTP client with specific timeouts.

```php
$guzzleClient = new GuzzleHttp\Client([
    'timeout' => 30,
    'connect_timeout' => 10
]);
$client->setClient($guzzleClient);
```

--------------------------------

### List Resources with Pagination

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/configuration-and-patterns.md

Example of fetching a list of resources (e.g., orders) with pagination, iterating until all pages are retrieved.

```php
use Mirakl\MMP\Shop\Request\Order\Get\GetOrdersRequest;

$request = new GetOrdersRequest();
$request->setLimit(50);
$request->setOffset(0);

$allOrders = [];

while (true) {
    $orders = $api->getOrders($request);
    $allOrders = array_merge($allOrders, $orders->toArray());
    
    if (!$orders->hasNextPage()) {
        break;
    }
    
    $request->setOffset($orders->getNextOffset());
}

echo "Total orders: " . count($allOrders);
```

--------------------------------

### Pagination Pattern

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/quick-reference.md

Shows a common pattern for handling paginated results, iterating through pages until all data is retrieved.

```php
$request = new GetOrdersRequest();
$request->setLimit(50);

$allOrders = [];
$offset = 0;

do {
    $request->setOffset($offset);
    $orders = $api->getOrders($request);
    $allOrders = array_merge($allOrders, $orders->toArray());
    $offset = $orders->getNextOffset();
} while ($orders->hasNextPage());

echo "Total: " . count($allOrders);
```

--------------------------------

### CreateCancelationsRequest Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/requests-reference.md

Example of how to request cancellation of specific order lines using CreateCancelationsRequest.

```php
public function setCancelations(array $cancelations): self
public function getCancelations(): array
```

```php
$request = new CreateCancelationsRequest();
$request->setCancelations([
    [
        'order_line_id' => 'LINE001',
        'quantity' => 5,
        'reason_code' => 'OUT_OF_STOCK',
    ],
    // ... more lines
]);
```

--------------------------------

### getOrders() Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/mmp-shop-api-client.md

Example usage of the getOrders method to retrieve and process orders.

```php
use Mirakl\MMP\Shop\Request\Order\Get\GetOrdersRequest;

$request = new GetOrdersRequest();
$request->setLimit(10);
$request->setOffset(0);
$orders = $api->getOrders($request);

foreach ($orders as $order) {
    echo $order->getId(); // ORDER_ID
    echo $order->getState(); // order state
}

```

--------------------------------

### setApiKey() Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/core-api-client.md

Example of how to set the API key for the client.

```php
$client->setApiKey('your_api_key_here');
```

--------------------------------

### __invoke() example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/core-api-client.md

Example of invoking the client directly with a request object.

```php
$result = $client($request);
```

--------------------------------

### default_user_agent() Example (with suffix)

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/utilities.md

Generates the User-Agent string with an optional suffix.

```php
$ua = Mirakl\default_user_agent('MyIntegration/1.0');
// Output: Mirakl-PHP-SDK/1.23.0 MyIntegration/1.0
```

--------------------------------

### Custom Request Handling Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/requests-reference.md

Shows how to create and execute requests directly without using predefined API methods.

```php
$request = new GetOfferRequest('OFFER123');

// Use client to execute
$response = $api->run($request);  // Returns PSR-7 Response
$offer = $request->run($api);     // Returns decoded object
```

--------------------------------

### Error Handling

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/quick-reference.md

Demonstrates how to catch and handle various exceptions, including validation errors and general API errors.

```php
use Mirakl\Core\Exception\ApiException;
use Mirakl\Core\Exception\RequestValidationException;

try {
    $offer = $api->getOffer(new GetOfferRequest('OFFER_ID'));
} catch (RequestValidationException $e) {
    echo "Validation error: " . $e->getMessage();
} catch (ApiException $e) {
    if ($e->getCode() == 404) {
        echo "Offer not found";
    } else {
        echo "API error: " . $e->getMessage();
    }
} catch (\Exception $e) {
    echo "Unexpected error: " . $e->getMessage();
}
```

--------------------------------

### File Download Pattern

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/utilities.md

Example of downloading a file using DownloadInvoiceRequest and accessing its properties.

```php
use Mirakl\MMP\Shop\Request\Payment\Invoice\DownloadInvoiceRequest;

// Download invoice
$request = new DownloadInvoiceRequest('INVOICE_ID');
$file = $api->downloadInvoice($request);

// Access file
$file->getFile()->rewind();
$contents = $file->getFile()->fread($file->getFile()->fstat()['size']);

// Save to disk
file_put_contents(
    $file->getFileName() ?: 'invoice.pdf',
    $contents
);

// Or get properties
echo $file->getContentType();  // application/pdf
echo $file->getFileExtension(); // pdf
```

--------------------------------

### Request Method Chaining Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/requests-reference.md

Demonstrates how to use method chaining with request setters for fluent API calls.

```php
$request = new GetOrdersRequest();
$request
    ->setLimit(50)
    ->setOffset(0)
    ->setStates(['ACCEPTED'])
    ->setStartDate(new \DateTime('2024-01-01'))
    ->setDir('DESC')
    ->setSortBy('created_date');

$orders = $api->getOrders($request);
```

--------------------------------

### FileWrapper for Uploads

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/types.md

Example of how to prepare a file for upload using FileWrapper.

```php
// For file uploads
$file = new FileWrapper(new \SplFileObject('/path/to/file.csv'));
$file->setFileName('offers.csv');
```

--------------------------------

### array_map_keys() Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/utilities.md

Maps array keys against a given mapping.

```php
$data = [
    'offer_id' => '123',
    'shop_id' => 'SHOP001',
    'pricing' => ['price' => 99.99, 'discount' => 10]
];

$mapping = [
    'offer_id' => 'offerId',
    'pricing/price' => 'sale_price'
];

$result = Mirakl\array_map_keys($data, $mapping);
// Result: ['offerId' => '123', 'shop_id' => 'SHOP001', 'sale_price' => 99.99, ...]
```

--------------------------------

### parse_file_response() Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/utilities.md

Converts a file response to a FileWrapper for download.

```php
$response = $api->raw(true)->downloadInvoice($request);
$file = Mirakl\parse_file_response($response, 'pdf');

// Save file
$file->getFile()->rewind();
file_put_contents('invoice.pdf', $file->getFile()->fread($file->getFile()->fstat()['size']));
```

--------------------------------

### Request Cloning for Pagination Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/requests-reference.md

Illustrates how to clone a request object to handle pagination and retrieve all results.

```php
$request = new GetOrdersRequest();
$request->setLimit(50);

$allOrders = [];
$offset = 0;

while (true) {
    $request->setOffset($offset);
    $orders = $api->getOrders($request);
    
    $allOrders = array_merge($allOrders, $orders->toArray());
    
    if (!$orders->hasNextPage()) {
        break;
    }
    
    $offset = $orders->getNextOffset();
}
```

--------------------------------

### MiraklObject Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/types.md

Demonstrates dynamic property access and magic methods for MiraklObject.

```php
$offer = new ShopOffer(['id' => '123', 'price' => 99.99]);
echo $offer->getId();       // '123'
echo $offer->getPrice();    // 99.99
$offer->setQuantity(10);    // Chainable
```

--------------------------------

### create_temp_csv_file() Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/utilities.md

Creates a temporary CSV file from array data and shows how to use it for an API upload.

```php
$offers = [
    ['offer_id', 'sku', 'price', 'quantity'], // Header row
    ['OFFER001', 'SKU001', '99.99', '100'],
    ['OFFER002', 'SKU002', '149.99', '50'],
];

$file = Mirakl\create_temp_csv_file($offers);

// Upload to API
$request = new OfferImportRequest($file);
$tracking = $api->importOffers($request);
```

--------------------------------

### Address Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/types.md

Demonstrates how to access address properties from an order object.

```php
$address = $order->getShippingAddress();
echo $address->getStreet1();
echo $address->getCity();
echo $address->getCountry();
```

--------------------------------

### date_format() Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/utilities.md

Formats a DateTime object to an ISO 8601 string and shows its use in API requests.

```php
$now = new \DateTime();
$iso8601 = Mirakl\date_format($now);

// Use in API request
$request->setStartDate(Mirakl\date_format(new \DateTime('2024-01-01')));
$request->setEndDate(Mirakl\date_format(new \DateTime('2024-12-31')));
```

--------------------------------

### downloadProductImportErrorReport Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/mci-shop-api-client.md

Downloads the error report for a product import job.

```php
use Mirakl\MCI\Shop\Request\Product\DownloadProductImportErrorReportRequest;

$request = new DownloadProductImportErrorReportRequest('IMPORT_ID');
$file = $api->downloadProductImportErrorReport($request);

// Save the file
$file->getFile()->rewind();
file_put_contents('errors.csv', $file->getFile()->fread($file->getFile()->fstat()['size']));
```

--------------------------------

### GetHierarchiesRequest Methods

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/requests-reference.md

Methods for getting product hierarchies.

```php
public function setHierarchyCodes(array $codes): self
```

--------------------------------

### FileWrapper for Downloads

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/types.md

Example of how to handle file downloads using FileWrapper.

```php
// For file downloads
$file = $api->downloadInvoice($request);
$file->getFile()->rewind();
file_put_contents('invoice.pdf', $file->getFile()->fread(...));
```

--------------------------------

### Integration Testing

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/configuration-and-patterns.md

An example of an integration test using a TestCase class that sets up a real API client for testing against a Mirakl environment.

```php
class MiraklApiTestCase extends TestCase {
    protected $api;
    
    public function setUp(): void {
        $this->api = new ShopApiClient(
            getenv('MIRAKL_TEST_URL'),
            getenv('MIRAKL_TEST_KEY'),
            getenv('MIRAKL_TEST_SHOP')
        );
    }
    
    public function testGetOffer() {
        $request = new GetOfferRequest('TEST_OFFER_ID');
        $offer = $this->api->getOffer($request);
        
        $this->assertNotNull($offer->getId());
        $this->assertGreater($offer->getPrice(), 0);
    }
}
```

--------------------------------

### underscorize() Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/utilities.md

Converts a camelCase or spaced string to underscore format.

```php
echo Mirakl\underscorize('MyClassName');     // my_class_name
echo Mirakl\underscorize('OrderID123');      // order_i_d_123
echo Mirakl\underscorize('ShopAccountInfo'); // shop_account_info
```

--------------------------------

### MiraklCollection Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/types.md

Demonstrates iterating and counting items in a MiraklCollection.

```php
$offers = $api->getOffers($request); // Returns ShopOfferCollection
foreach ($offers as $offer) {
    echo $offer->getId();
}
echo count($offers);  // Total items
```

--------------------------------

### Logger Setup

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/configuration-and-patterns.md

Configures Monolog logger for the SDK, optionally with a custom message format.

```php
use Monolog\Logger;
use Monolog\Handlers\StreamHandler;
use GuzzleHttp\MessageFormatter;

// Create logger
$logger = new Logger('mirakl-sdk');
$logger->pushHandler(new StreamHandler('mirakl.log'));

// Set on client
$api->setLogger($logger);

// Optional: Custom message format
$formatter = new MessageFormatter('{method} {target_url} -> {status_code}');
$api->setLogger($logger, $formatter);
```

--------------------------------

### Authentication Error Solution

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/errors.md

Provides a PHP code example for setting and verifying an API key to resolve authentication errors.

```php
$api->setApiKey('valid_api_key');

// Verify key before use
if (!$api->getApiKey()) {
    throw new InvalidArgumentException('API key required');
}
```

--------------------------------

### refs_to_query_param() Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/utilities.md

Formats a references associative array to a query parameter string.

```php
$refs = [
    'SKU' => ['SKU001', 'SKU002'],
    'SHOP' => 'SHOP123'
];

$param = Mirakl\refs_to_query_param($refs);
// Result: "SKU|SKU001,SKU|SKU002,SHOP|SHOP123"

// Use in request
$request->setProductReferences(json_decode($param));
```

--------------------------------

### array_format() Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/utilities.md

Formats string values in an array to corresponding types (bool, int, float).

```php
$data = [
    'quantity' => '100',
    'price' => '99.99',
    'active' => 'true',
    'archived' => 'false'
];

$formatted = Mirakl\array_format($data);
// Result: ['quantity' => 100, 'price' => 99.99, 'active' => true, 'archived' => false]
```

--------------------------------

### tuples_to_query_param() Example

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/utilities.md

Formats multiple array values to a query parameter string.

```php
$data = [
    ['offer_id' => '123', 'quantity' => '10'],
    ['offer_id' => '456', 'quantity' => '20']
];

$param = Mirakl\tuples_to_query_param($data);
// Result: "123|10,456|20"
```

--------------------------------

### Token-based Pagination

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/types.md

Example of using token-based pagination for collections.

```php
if ($orders->getPageToken()) {
    $nextRequest->setPageToken($orders->getPageToken());
}
```

--------------------------------

### Shipment Workflow

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/configuration-and-patterns.md

Demonstrates the process of getting items to ship, creating shipments, and shipping them using the Mirakl API.

```php
use Mirakl\MMP\Shop\Request\Shipment\GetItemsToShipRequest;
use Mirakl\MMP\Shop\Request\Shipment\CreateShipmentsRequest;
use Mirakl\MMP\Shop\Request\Shipment\ShipShipmentsRequest;

// 1. Get items to ship
$request = new GetItemsToShipRequest();
$items = $api->getItemsToShip($request);

// 2. Create shipments
$shipRequest = new CreateShipmentsRequest();
$shipRequest->setItems($items);
$created = $api->createShipments($shipRequest);

// 3. Ship shipments
$shipShipRequest = new ShipShipmentsRequest();
foreach ($created->getShipments() as $shipment) {
    $shipShipRequest->addShipment([
        'shipment_id' => $shipment->getId(),
        'tracking_number' => 'TRACK123',
        'carrier_code' => 'DHL',
    ]);
}

$result = $api->shipShipments($shipShipRequest);
```

--------------------------------

### Date/Time Formatting

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/types.md

Example of formatting a DateTime object to an API-compatible string.

```php
$dateString = Mirakl\date_format(new \DateTime());
// Result: "2024-05-27T15:30:00+00:00" (ISO 8601)
```

--------------------------------

### Collection Pagination

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/types.md

Example of paginating through a collection of orders.

```php
$orders = $api->getOrders($request);

echo count($orders);           // Current page item count
echo $orders->getTotalCount(); // Total items across all pages

if ($orders->hasNextPage()) {
    $nextRequest = clone $request;
    $nextRequest->setOffset($orders->getNextOffset());
    $nextOrders = $api->getOrders($nextRequest);
}
```

--------------------------------

### Provide Context in Logs

Source: https://github.com/mirakl/sdk-php-shop/blob/master/_autodocs/errors.md

Example of logging detailed information about an API exception, including request and error message.

```php
try {
    $offer = $api->getOffer($request);
} catch (ApiException $e) {
    error_log(sprintf(
        "Failed to get offer %s: %s [%d]",
        $request->getOfferId(),
        $e->getMessage(),
        $e->getCode()
    ));
}
```