Deprecate SessionResource::getMainStore() (#116)

* Deprecate SessionResource::getMainStore()
* Add documentation

README.md

@@ -42,7 +42,7 @@ $session = Client\Client::createSession($credential);
 
 ```php
 /** @var \ShoppingFeed\Sdk\Api\Session\SessionResource $session */
-$store = $session->getMainStore();
+$store = $session->selectStore(1276);
 $store->getName(); // test-store
 $store->getId(); // 1276
 // ... and so on
@@ -60,7 +60,7 @@ $stores->count();
 $store = $stores->select('id-or-store-name');
 // Loop over available stores
 foreach ($stores as $store) {
-	$store->getName(); 
+    $store->getName(); 
 }
 ```
 

composer.json

@@ -5,7 +5,8 @@
   "description": "Shopping Feed SDK to ease integration of our API",
   "require": {
     "php": ">=7.1",
-    "ext-json": "*"
+    "ext-json": "*",
+    "symfony/deprecation-contracts": "^2.5|^3.0"
   },
   "autoload": {
     "psr-4": {

docs/manual/resources/inventory.md

@@ -5,8 +5,8 @@
 Accessing the inventory API can be done using the store resource
 
 ```php
-<?php
-$inventoryApi = $session->getMainStore()->getInventoryApi();
+$storeId      = 1276;
+$inventoryApi = $session->selectStore($storeId)->getInventoryApi();
 ```
 
 Find an inventory item by a product's reference (sku):

docs/manual/resources/order.md

@@ -2,11 +2,47 @@
 
 ## Access
 
-Accessing the order API can be done from the store.
+Accessing the order API can be done from your sessions. As your session can be 
+linked to multiple stores, you have to select stores you want to access to.
 
+### Single store management
 ```php
-<?php
-$orderApi = $session->getMainStore()->getOrderApi();
+$storeId  = 1234;
+$orderApi = $session->selectStore($storeId)->getOrderApi();
+```
+
+### Multiple stores management
+
+```php
+$storesIds = [1234, 5678];
+
+foreach ($storesIds as $storeId) {
+    $orderApi = $session->selectStore($storeId)->getOrderApi();
+}
+```
+
+Please note that whole order API is store scoped. You cannot access an order 
+from the wrong store even if your session is allowed to access the given 
+order's store.
+
+For instance, if your session has access to stores `1` and `5`, and if store 
+`1` has an order `1111` and store `5` has an order `5555`, you cannot access 
+order `5555` from store `1`:
+
+```php
+// Lead to a 404
+$session->selectStore(1)->getOrderApi()->getOne(5555);
+```
+
+### Deprecated method
+
+Usage of getMainStore() has been deprecated and SHOULD NOT be used anymore. 
+It can lead to major issue if your session get access to new stores.
+It will be removed in the next major version of the SDK.
+
+```php
+$storeId  = 1276;
+$orderApi = $session->selectStore($storeId)->getOrderApi();
 ```
 
 ## Retrieve orders

docs/manual/resources/pricing.md

@@ -6,7 +6,8 @@ Accessing the pricing API can be done using the store resource
 
 ```php
 <?php
-$pricingApi = $session->getMainStore()->getPricingApi();
+$storeId    = 1276;
+$pricingApi = $session->selectStore($storeId)->getPricingApi();
 ```
 
 Find an pricing item by a product's reference (sku):

docs/manual/resources/ticket.md

@@ -9,7 +9,8 @@ To get a ticket detail you need to call ticket API like so :
 
 ```php
 <?php
-$ticketApi = $session->getMainStore()->getTicketApi();
+$storeId   = 1276;
+$ticketApi = $session->selectStore($storeId)->getTicketApi();
 
 $ticket = $ticketApi->getOne('abc123def456ghi789');
 $ticket->getStatus();
@@ -23,7 +24,8 @@ A batch ID is then returned to the user to be able to retrieve all tickets neede
 
 ```php
 <?php
-$ticketApi = $session->getMainStore()->getTicketApi();
+$storeId   = 1276;
+$ticketApi = $session->selectStore($storeId)->getTicketApi();
 $tickets   = $ticketApi->getByBatch('987ihg654fed321cba');
 
 // Check global status of the batch based on all ticket status

src/Api/Session/SessionResource.php

@@ -78,7 +78,7 @@ public function getLanguageTag()
     /**
      * @param int|string $idOrName
      *
-     * @return \ShoppingFeed\Sdk\Api\Store\StoreResource
+     * @return \ShoppingFeed\Sdk\Api\Store\StoreResource|null
      */
     public function selectStore($idOrName)
     {
@@ -92,11 +92,21 @@ public function selectStore($idOrName)
     }
 
     /**
+     * @deprecated Use selectStore instead
+     *
      * @return \ShoppingFeed\Sdk\Api\Store\StoreResource|null
      */
     public function getMainStore()
     {
+        trigger_deprecation(
+            'shopping-feed/sdk',
+            '0.8.0',
+            'The SessionResource::getMainStore() method is deprecated and will '
+            . 'be removed in 1.0. Use selectStore instead'
+        );
+
         $resource = $this->resource->getFirstResource('store');
+
         if ($resource) {
             return new Store\StoreResource($resource, true);
         }