- About
- Installation
- SellerClient Construction
- SellerClient Methods
- Events
- Authentication Integration
- License
This is the PHP seller client package for the F1 Shopping Cart service.
This package should be installed on the seller web server and enables seller-side operations such as getting and setting stock levels, purchase limits, etc.
The preferred method of installation is via
Packagist and
Composer.
Run the following command to install the package and add it as a requirement
to your project's composer.json:
composer require f1/seller-clientAll interactions between the seller server and the F1 Shopping Cart service happen via the SellerClient object. Constructing a SellerClient requires an App Id and an App Secret, which can be obtained from F1 Customer Support. Both the App Id and App Secret are strings. The App Secret should be kept confidential and stored securely. Here is an example of constructing a SellerClient using environment variables:
$appId = getenv('F1_APP_ID');
$appSecret = getenv('F1_APP_SECRET');
$client = new SellerClient($appId, $appSecret);- Stock Methods
- SKU Info Methods
- Cart Methods
- Purchase Limit Methods
- Cart Duration Methods
- Authentication Methods
- Event Methods
int getStockQuantity(int $sku)Returns the stock quantity of the given SKU.
sku: An integer representing the SKU.
The stock quantity as an integer.
$sku = 81;
$qty = $client->getStockQuantity($sku);int setStockQuantity(int $sku, int $qty)Sets the stock quantity of a single SKU. Note that this method should not be used in a loop for bulk quantity updates, as the setStockQuantities is much more efficient for bulk updates.
sku: An integer representing the SKU.qty: An integer representing the stock quantity to be set.
The stock quantity as an integer.
$sku = 81;
$qty = 500;
$setQty = $client->setStockQuantity($sku, $qty);bool setStockQuantities(array $skuToQtyArray)Sets the stock quantity of multiple SKUs.
skuToQtyArray: An array whose keys are SKUs (ints) and whose values are quantities (ints).
TRUE if the operation succeeded, FALSE otherwise.
$sku1 = 81;
$qty1 = 500;
$sku2 = 1234567;
$qty2 = 200;
$skuToQtyArray = array($sku1 => $qty1,
$sku2 => $qty2);
$ret = $client->setStockQuantities($skuToQtyArray);array getAllStockQuantities()Gets the stock quantity all SKUs. Only SKUs with non-zero stock quantities are returned.
- None
An array whose keys are SKUs (ints) and whose values are the stock quantities (ints).
$ret = $client->getAllStockQuantities();array getSkuInfo(int $sku)Gets quantity information about a SKU.
- sku: An integer representing the SKU.
An array with three keys:
stock: An integer representing the quantity of this SKU that are in stock.carts: An integer representing the quantity of this SKU that are currently in shopping carts.purchased: An integer representing the quantity of this SKU that have been purchased since the last purchase history reset. See resetPurchaseHistory and resetAllPurchaseHistories for more information on purchase histories.
$sku = 81;
$ret = $client->getSkuInfo($sku);array getAllSkuInfos()Gets quantity information about all SKUs.
- None
An array whose keys are integers representing SKUs and whose values are SKU info arrays, which have three keys:
stock: An integer representing the quantity of this SKU that are currently in stock.carts: An integer representing the quantity of this SKU that are currently in shopping carts.purchased: An integer representing the quantity of this SKU that have been purchased since the last purchase history reset. See resetPurchaseHistory and resetAllPurchaseHistories for more information on purchase histories.
$ret = $client->getAllSkuInfos();array getAggregateSkuInfo()Gets aggregate quantity information all active SKUs.
- None
An array with three keys:
stock: An integer representing the total quantity of all SKUs that are currently in stock.carts: An integer representing the quantity of all SKUs that are currently in shopping carts.purchased: An integer representing the quantity of all SKUs that have been purchased since the last purchase history reset. See resetPurchaseHistory and resetAllPurchaseHistories for more information on purchase histories.
$ret = $client->getAggregateSkuInfo();array getCart(int $userId)Gets the contents of a shopper's cart.
userId: An integer representing the shopper's user id.
An array whose keys are SKUs (integers) and whose values are the quantity of that SKU in the shopper's cart (integers).
$userId = 2435;
$ret = $client->getCart($userId);bool emptyCart(int $userId)Empties the shopper's cart, without marking any of the items as purchased.
userId: An integer representing the shopper's user id.
TRUE if the operation succeeded, FALSE otherwise.
$userId = 2435;
$ret = $client->emptyCart($userId);bool removeSkuFromAllCarts(int $sku)Removes all items of the given SKU from all users' carts and returns them to stock.
sku: An integer representing the SKU.
TRUE if the operation succeeded, FALSE otherwise.
$sku = 81;
$ret = $client->removeSkuFromAllCarts($sku);bool markCartAsPurchased(int $userId)Marks all the items in a shopper's cart as having been purchased and removes them from the cart.
userId: An integer representing the shopper's user id.
TRUE if the operation succeeded, FALSE otherwise.
$userId = 2435;
$ret = $client->markCartAsPurchased($userId);bool markSomeCartSkusAsPurchased(int $userId, array $skus)Marks the specified SKUs in a shopper's cart as having been purchased and removes them from the cart. Any other SKUs in the cart are unaffected.
userId: An integer representing the shopper's user id.skus: A non-empty, one-dimensional of integers representing the SKUs to be marked as purchased.
TRUE if the operation succeeded, FALSE otherwise.
$userId = 2435;
$skus = array(42, 99, 7, 1);
$ret = $client->markSomeCartSkusAsPurchased($userId, $skus);int getSkuPurchaseLimit(int $sku)Gets the current purchase limit for the given SKU. A shopper may only have purchased (or have in their cart) this quantity of the given SKU. Note that a purchase limit of zero means that there is no limit, i.e. shoppers may purchase an unlimited amount of the given SKU (subject to stock availability). To allow shoppers to purchase more of SKUs that are limited, their purchase history must be reset. See also resetPurchaseHistory and resetAllPurchaseHistories.
sku: An integer representing the SKU.
An integer representing the current purchase limit for the given SKU.
$sku = 81;
$limit = $client->getSkuPurchaseLimit($sku);bool setSkuPurchaseLimit(int $sku, int $qty)Sets the current purchase limit for the given SKU. A shopper may only have purchased (or have in their cart) this quantity of the given SKU. Note that a purchase limit of zero means that there is no limit, i.e. shoppers may purchase an unlimited amount of the given SKU (subject to stock availability). To allow shoppers to purchase more units of SKUs that are limited, their purchase history must be reset. See also resetPurchaseHistory and resetAllPurchaseHistories. If you want to set the purchase limit for many SKUs at once, use the related setSkuPurchaseLimits instead of this method.
sku: An integer representing the SKU.qty: An integer representing the quantity of this SKU that may be purchased.
TRUE if the operation succeeded, FALSE otherwise.
$sku = 81;
$limitQty = 5;
$ret = $client->setSkuPurchaseLimit($sku, $limitQty);array getAllSkuPurchaseLimits()Gets the current purchase limits for all SKUs. Only SKUs with non-zero limits are returned. Note that a purchase limit of zero means that there is no limit, i.e. shoppers may purchase an unlimited amount of the given SKU (subject to stock availability). To allow shoppers to purchase more units of SKUs that are limited, their purchase history must be reset. See also resetPurchaseHistory and resetAllPurchaseHistories.
- None
An array whose keys are SKUs (integers) and whose values are the purchase limits (integers) for the given SKUs.
$ret = $client->getAllSkuPurchaseLimits();bool setSkuPurchaseLimits(array $skuToLimitArray)Sets the current purchase limit for multiple SKUs. Note that a purchase limit of zero means that there is no limit, i.e. shoppers may purchase an unlimited amount of the given SKU (subject to stock availability). To allow shoppers to purchase more units of SKUs that are limited, their purchase history must be reset. See also resetPurchaseHistory and resetAllPurchaseHistories.
skuToLimitArray: An array whose keys are SKUs (ints) and whose values are limit quantities (ints).
TRUE if the operation succeeded, FALSE otherwise.
$sku1 = 81;
$limit1 = 500;
$sku2 = 1234567;
$limit2 = 200;
$skuToLimitArray = array($sku1 => $limit1,
$sku2 => $limit2);
$ret = $client->setSkuPurchaseLimits($skuToLimitArray);bool resetPurchaseHistory(int $userId)Resets the shopper's purchase history for purposes of purchase limits. After this method is called, the given shopper will be able to purchase up to the current purchase limit for any SKU, regardless of past purchases.
userId: An integer representing the shopper's user id.
TRUE if the operation succeeded, FALSE otherwise.
$userId = 2435;
$ret = $client->resetPurchaseHistory($userId);bool resetAllPurchaseHistories()Resets all shoppers' purchase histories for purposes of purchase limits. After this method is called, all shoppers will be able to purchase up to the current purchase limit for any SKU, regardless of past purchases.
- None
TRUE if the operation succeeded, FALSE otherwise.
$ret = $client->resetAllPurchaseHistories();int getCartDurationSeconds()Returns the current cart duration in seconds. Carts that have existed for longer than the current cart duration will be automatically emptied. The cart duration is counted from the time the first item is added to the cart until the time that the cart is marked as purchased or is otherwise emptied. See also resetCartStartTime and resetAllCartStartTimes.
- None
An integer representing the current cart duration in seconds.
$durationSeconds = $client->getCartDurationSeconds();bool setCartDurationSeconds(int $seconds)Sets the current cart duration in seconds. Carts that have existed for longer than the current cart duration will be automatically emptied. The cart duration is counted from the time the first item is added to the cart until the time that the cart is marked as purchased or is otherwise emptied. See also resetCartStartTime and resetAllCartStartTimes.
seconds: An integer representing the desired cart duration in seconds.
TRUE if the operation succeeded, FALSE otherwise.
$durationSeconds = 14400 // 4 hours
$ret = $client->setCartDurationSeconds($durationSeconds);int getCartSecondsRemaining(int $userId)Returns the number of seconds remaining before the given shopper's cart is automatically emptied. See also getCartDurationSeconds and setCartDurationSeconds.
userId: An integer representing the shopper's user id.
An integer representing the number of seconds remaining before the given shopper's cart is automatically emptied.
$userId = 2435;
$secondsRemaining = $client->getCartinutesRemaining($userId);bool resetCartStartTime(int $userId)Resets the start time of the given user's cart. The F1 service automatically expires (empties) carts that have existed for longer than the current cart duration (see setCartDurationSeconds). Normally, the cart duration is counted from the time the first item is added to the cart until the time that the cart is marked as purchased or is otherwise emptied. This method resets the shopper's cart start time, giving that shopper a new period of time to purchase the items in their cart.
userId: An integer representing the shopper's user id.
TRUE if the operation succeeded, FALSE otherwise.
$userId = 2435;
$ret = $client->resetCartStartTime($userId);bool resetAllCartStartTimes()Resets the start time of all users' carts. The F1 service automatically expires (empties) carts that have existed for longer than the current cart duration (see setCartDurationSeconds). Normally, the cart duration is counted from the time the first item is added to the cart until the time that the cart is marked as purchased or is otherwise emptied. This method resets all shoppers' cart start times, giving all shoppers a new period of time to purchase the items in their cart.
- None
TRUE if the operation succeeded, FALSE otherwise.
$ret = $client->resetAllCartStartTimes();string generateAuthToken(int $userId, $tokenDurationMinutes)Returns an authentication token for the given shopper. The token will be valid for the number of minutes specified by $tokenDurationMinutes. This method should be called by the authentication handler. See the Authentication Integration section for more information about authentication.
userId: An integer representing the shopper's user id.tokenDurationMinutes: An integer representing the number of minutes for which the token will be valid.
A string token allowing the shopper to authenticate directly to the F1 Shopping Cart service.
$userId = Auth::id();
$tokenDurationMins = 240;
$token = $client->generateAuthToken($userId, $tokenDurationMins);bool sendEventToShopper(int $userId, string $eventName, string $eventString)Sends a custom event to a specific shopper's browser connections. Custom events have an event name and an event value string. The event name and event value string are arbitrary and can be any string value. If the shopper has multiple browser windows or tabs connected, all of them will recieve the event. If the shopper is not currently connected, the event is dropped. See the Events section for more information. See also sendEventToAllShoppers
userId: An integer representing the shopper's user id.eventName: A string representing name of the eventeventString: A string representing the value of the event.
TRUE if the operation succeeded, FALSE otherwise.
$userId = 2435;
$eventName = 'direct-message'
$eventString = 'The item you've been waiting for just arrived in stock';
$ret = $client->sendEventToShopper($userId, $eventName, $eventString);bool sendEventToAllShoppers(string $eventName, string $eventString)Sends a custom event to all shoppers' connections. Custom events have an event name and an event value string. The event name and event value string are arbitrary and can be any string value. See the Events section for more information. See also sendEventToShopper
eventName: A string representing name of the eventeventString: A string representing the value of the event.
TRUE if the operation succeeded, FALSE otherwise.
$eventName = 'start-countdown'
$eventString = '20'
$ret = $client->sendEventToAllShoppers($eventName, $eventString);Events are sent to the shopper's browser connections. The ShopperClient handles events by binding handlers to each event type. F1 Shopping Cart has two categories of events:
- Built-in events
- Custom events
Built-in events are sent automatically by the F1 Shopping Cart service when certain things happen. See the ShopperClient's eveent documentation for the list of built-in events. Custom events are arbitrary strings sent to shoppers. Custom events have a name and a value, which are both strings. See sendEventToShopper and sendEventToAllShoppers for more information.
The F1 Shopping Cart service cooperates with the seller server to authenticate shoppers. This is done via an HTTP GET request from the shopper's browser client. The seller server must provide a route that accepts the request only if the shopper is authenticated. It should then call the generateAuthToken method on the SellerClient an authentication token. Finally, it should return the shopper's user id and the authentication token to the shopper in a JSON-encoded array. Here is an example using Laravel 4:
Route::get('get_f1_auth_token', ['before' => 'auth', function()
{
$userId = Auth::id(); // Replace this line for other auth systems
$tokenDurationMins = 240;
$appId = getenv('F1_APP_ID');
$appSecret = getenv('F1_APP_SECRET');
$client = new SellerClient($appId, $appSecret);
$token = $client->generateAuthToken($userId, $tokenDurationMins);
$ret = array('userId' => $userId,
'token' => $token);
return json_encode($ret);
}]);Copyright (c) 2017-2018 Deer Creek Labs, LLC
Distributed under the Apache Software License, Version 2.0 http://www.apache.org/licenses/LICENSE-2.0.txt