PHPackages nosto/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. nosto/php-sdk ActiveLibrary[API Development](/categories/api) nosto/php-sdk ============= PHP SDK for developing Nosto modules for e-commerce platforms 7.7.3(2mo ago)7850.3k↑14.2%7[3 issues](https://github.com/Nosto/nosto-php-sdk/issues)[2 PRs](https://github.com/Nosto/nosto-php-sdk/pulls)7BSD-3-ClausePHPPHP >=5.5CI failing Since Jan 18Pushed 2mo ago24 watchersCompare [ Source](https://github.com/Nosto/nosto-php-sdk)[ Packagist](https://packagist.org/packages/nosto/php-sdk)[ RSS](/packages/nosto-php-sdk/feed)WikiDiscussions develop Synced 1mo ago READMEChangelog (10)Dependencies (30)Versions (183)Used By (7) php-sdk ======= [](#php-sdk) Provides tools for building modules that integrate Nosto into your e-commerce platform. Requirements ------------ [](#requirements) - The Nosto PHP SDK requires at least PHP version 5.4.0 and it's also compatible with PHP >= 7.0.0 Getting started --------------- [](#getting-started) ### Creating a new Nosto account [](#creating-a-new-nosto-account) A Nosto account is needed for every shop and every language within each shop. ``` ..... try { /** @var NostoSignupInterface $meta */ /** @var NostoSignup $account */ $account = NostoSignup::create($meta); // save newly created account according to the platforms requirements ..... } catch (NostoException $e) { // handle failure ..... } ..... ``` ### Connecting with an existing Nosto account [](#connecting-with-an-existing-nosto-account) This should be done in the shops back end when the admin user wants to connect an existing Nosto account to the shop. First redirect to the Nosto OAuth2 server. ``` ..... /** @var OAuthInterface $meta */ $client = new NostoOAuthClient($meta); header('Location: ' . $client->getAuthorizationUrl()); ``` Then have a public endpoint ready to handle the return request. ``` if (isset($_GET['code'])) { try { /** @var OAuthInterface $meta */ $account = NostoSignup::syncFromNosto($meta, $_GET['code']); // save the synced account according to the platforms requirements } catch (NostoException $e) { // handle failures } // redirect to the admin page where the user can see the account controls ..... } } elseif (isset($_GET['error'])) { // handle errors; 3 parameter will be sent, 'error', 'error_reason' and 'error_description' // redirect to the admin page where the user can see an error message ..... } else { // 404 ..... } ``` ### Deleting a Nosto account [](#deleting-a-nosto-account) This should be used when you delete a Nosto account for a shop. It will notify Nosto that this account is no longer used. ``` try { /** @var NostoSignup $account */ $account->delete(); } catch (NostoException $e) { // handle failure } ``` ### Get authenticated Nosto URL for the account controls [](#get-authenticated-nosto-url-for-the-account-controls) The Nosto account can be created and managed through the controls that should be accessible to the admin user in the shop's backend. The account controls will redirect to nosto.com. ``` ..... /** * @param ConnectionMetadataInterface $connection the connection meta data. * @param AccountInterface|null $account the configuration to return the url for. * @param UserInterface|null $user * @param array $params additional parameters to add to the connection url. */ try { $url = Nosto::helper('connection')->getUrl($meta, $account, $user, $params); } catch (NostoException $e) { // handle failure } // render the link to the user with given url ..... ``` ### Sending order confirmations using the Nosto API [](#sending-order-confirmations-using-the-nosto-api) Sending order confirmations to Nosto is a vital part of the functionality. OrderConfirm confirmations should be sent when an order has been completed in the shop. It is NOT recommended to do this when the "thank you" page is shown to the user, as payment gateways work differently and you cannot rely on the user always being redirected back to the shop after a payment has been made. Therefore, it is recommended to send the order conformation when the order is marked as payed in the shop. OrderConfirm confirmations can be sent two different ways: - matched orders; where we know the Nosto customer ID of the user who placed the order - un-matched orders: where we do not know the Nosto customer ID of the user who placed the order The Nosto customer ID is set in a cookie "2c.cId" by Nosto and it is up to the platform to keep a link between users and the Nosto customer ID. It is recommended to tie the Nosto customer ID to the order or shopping cart instead of an user ID, as the platform may support guest checkouts. ``` ..... try { /** * @var NostoOrderInterface $order * @var NostoSignupInterface $account * @var string $customerId */ NostoOrderConfirmation::send($order, $account, $customerId); } catch (NostoException $e) { // handle error } ..... ``` ### Sending product re-crawl requests using the Nosto API [](#sending-product-re-crawl-requests-using-the-nosto-api) Note: this feature has been deprecated in favor of the create/update/delete method below. When a product changes in the store, stock is reduced, price is updated etc. it is recommended to send an API request to Nosto that initiates a product "re-crawl" event. This is done to update the recommendations including that product so that the newest information can be shown to the users on the site. Note: the $product model needs to include only `productId` and `url` properties, all others can be omitted. ``` ..... try { /** * @var NostoProductInterface $product * @var NostoSignupInterface $account */ NostoProductReCrawl::send($product, $account); } catch (NostoException $e) { // handle error } ..... ``` Batch re-crawling is also possible by creating a collection of product models: ``` ..... try { /** * @var NostoExportProductCollection $collection * @var NostoProductInterface $product * @var NostoSignupInterface $account */ $collection[] = $product; NostoProductReCrawl::sendBatch($collection, $account); } catch (NostoException $e) { // handle error } ..... ``` ### Sending product create/update/delete requests using the Nosto API [](#sending-product-createupdatedelete-requests-using-the-nosto-api) When a product changes in the store, stock is reduced, price is updated etc. it is recommended to send an API request to Nosto to handle the updated product info. This is also true when adding new products as well as deleting existing ones. This is done to update the recommendations including that product so that the newest information can be shown to the users on the site. Creating new products: ``` ..... try { /** * @var NostoProductInterface $product * @var NostoSignupInterface $account */ $op = new UpsertProduct($account); $op->addProduct($product); $op->create(); } catch (NostoException $e) { // handle error } ..... ``` Note: you can call `addProduct` multiple times to add more products to the request. This way you can batch create products. Updating existing products: ``` ..... try { /** * @var NostoProductInterface $product * @var NostoSignupInterface $account */ $op = new UpsertProduct($account); $op->addProduct($product); $op->update(); } catch (NostoException $e) { // handle error } ..... ``` Note: you can call `addProduct` multiple times to add more products to the request. This way you can batch update products. Deleting existing products: ``` ..... try { /** * @var NostoProductInterface $product * @var NostoSignupInterface $account */ $op = new UpsertProduct($account); $op->addProduct($product); $op->delete(); } catch (NostoException $e) { // handle error } ..... ``` Note: you can call `addProduct` multiple times to add more products to the request. This way you can batch delete products. ### Exporting encrypted product/order information that Nosto can request [](#exporting-encrypted-productorder-information-that-nosto-can-request) When new Nosto accounts are created for a shop, Nosto will try to fetch historical data about products and orders. This information is used to bootstrap recommendations and decreases the time needed to get accurate recommendations showing in the shop. For this to work, Nosto requires 2 public endpoints that can be called once a new account has been created through the API. These endpoints should serve the history data encrypted with AES. The SDK comes bundled with the ability to encrypt the data with a pure PHP solution (), It is recommended, but not required, to have mcrypt installed on the server. Additionally, the endpoints need to support the ability to limit the amount of products/orders to export and an offset for fetching batches of data. These must be implemented as GET parameters "limit" and "offset" which will be sent as integer values and expected to be applied to the data set being exported. ``` ..... /** * @var NostoProductInterface[] $products * @var NostoSignupInterface $account */ $collection = new NostoExportProductCollection(); foreach ($products as $product) { $collection[] = $product; } // The exported will encrypt the collection and output the result. $cipher_text = NostoExporter::export($account, $collection); echo $cipher_text; // It is important to stop the script execution after the export, in order to avoid any additional data being outputted. die(); ``` ``` ..... /** * @var NostoOrderInterface[] $orders * @var NostoSignupInterface $account */ $collection = new NostoExportOrderCollection(); foreach ($orders as $order) { $collection[] = $order; } // The exported will encrypt the collection and output the result. $cipher_text = NostoExporter::export($account, $collection); echo $cipher_text; // It is important to stop the script execution after the export, in order to avoid any additional data being outputted. die(); ``` Testing ------- [](#testing) The SDK is unit tested with Codeception (). ### Running tests [](#running-tests) First cd into the root directory. Then install Codeception via composer: ``` php composer.phar install ``` Then run the tests: ``` vendor/bin/codecept run ``` ### Testing new added operation [](#testing-new-added-operation) The SDK unit test uses the apiary as the stub server. The apiary pulls the api-blueprint.md from master branch and builds fake api endpoints based on it. A way to test new added operation before merging it to master is using Drakov API Bleuprint Mock Server () running on Node. First cd into the root directory. Then install Codeception via composer: ``` php composer.phar install ``` After that you can install the drakov server via npm: ``` npm install -g drakov ``` Update the endpoints in the tests/.env file: ``` NOSTO_API_BASE_URL=localhost:3000 NOSTO_OAUTH_BASE_URL=localhost:3000/oauth NOSTO_WEB_HOOK_BASE_URL=http://localhost:3000 ``` Then start the drakov mock server with the API blueprint: ``` drakov -f tests/api-blueprint.md ``` Then in another window run the tests: ``` vendor/bin/codecept run ``` You can pass debugMode flag to the drakov server for debugging purposes: ``` drakov -f tests/api-blueprint.md --debugMode ``` ### Running phpcs [](#running-phpcs) First cd into the root directory. Then the phpcs: ``` phpcs --standard=ruleset.xml -v . ``` ### Health Score 61 — FairBetter than 99% of packages Maintenance77 Regular maintenance activity Popularity45 Moderate usage in the ecosystem Community34 Small or concentrated contributor base Maturity77 Established project with proven stability Bus Factor2 2 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~23 days Recently: every ~63 days Total 171 Last Release 74d ago Major Versions 3.15.0 → 4.0.02019-08-09 4.1.0 → 5.0.02020-05-26 5.8.2 → 6.0.02022-08-01 6.2.0 → 7.0.02023-02-21 6.2.2 → 7.1.02023-05-29 PHP version history (2 changes)3.1.1PHP >=5.4.0 5.2.0PHP >=5.5 ### Community Maintainers ![](https://www.gravatar.com/avatar/72fc62faab717a903a7ddd1dc340b920403cbd382ce7b6eb30044430f69eeced?d=identicon)[nosto](/maintainers/nosto) --- Top Contributors [![olsi-qose](https://avatars.githubusercontent.com/u/44775916?v=4)](https://github.com/olsi-qose "olsi-qose (273 commits)")[![supercid](https://avatars.githubusercontent.com/u/2778820?v=4)](https://github.com/supercid "supercid (231 commits)")[![dairbuirabass](https://avatars.githubusercontent.com/u/26374746?v=4)](https://github.com/dairbuirabass "dairbuirabass (100 commits)")[![prahimi94](https://avatars.githubusercontent.com/u/182894291?v=4)](https://github.com/prahimi94 "prahimi94 (31 commits)")[![TobiasGraml11](https://avatars.githubusercontent.com/u/51320851?v=4)](https://github.com/TobiasGraml11 "TobiasGraml11 (30 commits)")[![liangde-chen](https://avatars.githubusercontent.com/u/25772561?v=4)](https://github.com/liangde-chen "liangde-chen (28 commits)")[![bojand-soprex](https://avatars.githubusercontent.com/u/103487672?v=4)](https://github.com/bojand-soprex "bojand-soprex (28 commits)")[![iganulevics](https://avatars.githubusercontent.com/u/162290733?v=4)](https://github.com/iganulevics "iganulevics (28 commits)")[![Bibarella](https://avatars.githubusercontent.com/u/36549236?v=4)](https://github.com/Bibarella "Bibarella (15 commits)")[![lisafindo](https://avatars.githubusercontent.com/u/47558295?v=4)](https://github.com/lisafindo "lisafindo (14 commits)")[![phonglynosto](https://avatars.githubusercontent.com/u/134046761?v=4)](https://github.com/phonglynosto "phonglynosto (11 commits)")[![mridang](https://avatars.githubusercontent.com/u/327432?v=4)](https://github.com/mridang "mridang (9 commits)")[![Radomir98](https://avatars.githubusercontent.com/u/153912622?v=4)](https://github.com/Radomir98 "Radomir98 (8 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (5 commits)")[![artiommatvejev](https://avatars.githubusercontent.com/u/185074651?v=4)](https://github.com/artiommatvejev "artiommatvejev (4 commits)")[![ugljesaspx](https://avatars.githubusercontent.com/u/153918141?v=4)](https://github.com/ugljesaspx "ugljesaspx (2 commits)")[![peter279k](https://avatars.githubusercontent.com/u/9021747?v=4)](https://github.com/peter279k "peter279k (1 commits)")[![jluostar](https://avatars.githubusercontent.com/u/897726?v=4)](https://github.com/jluostar "jluostar (1 commits)") ### Code Quality TestsCodeception Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/nosto-php-sdk/health.svg) ``` [![Health](https://phpackages.com/badges/nosto-php-sdk/health.svg)](https://phpackages.com/packages/nosto-php-sdk) ``` ### Alternatives [netflie/whatsapp-cloud-api The first PHP SDK to send and receive messages using a cloud-hosted version of the WhatsApp Business Platform 640431.7k4](/packages/netflie-whatsapp-cloud-api)[wheelpros/fitment-platform-api Magento 2 (Open Source) 12.1k1.2k](/packages/wheelpros-fitment-platform-api)[packbackbooks/lti-1p3-tool A library used for building IMS-certified LTI 1.3 tool providers in PHP. 51438.3k2](/packages/packbackbooks-lti-1p3-tool)[yoti/yoti-php-sdk Yoti SDK for quickly integrating your PHP backend with Yoti 27539.9k1](/packages/yoti-yoti-php-sdk)[hoels/app-store-server-library-php The PHP server library for the App Store Server API and App Store Server Notifications. 44162.2k](/packages/hoels-app-store-server-library-php)[wrav/oembed A simple plugin to extract media information from websites, like youtube videos, twitter statuses or blog articles. 36205.0k3](/packages/wrav-oembed) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)