Shoppingfeed Prestashop module developper guide

Shoppingfeed Prestashop module developper guide

Generalities

Source: 00-overview/00-module_overview.md

Some useful links :

The Shopping Feed API documentation ...Which shouldn't be necessary since we're using the Shopping Feed PHP SDK.

This module will replace the shoppingfluxexport module since version 1.4+. It's purpose is to keep the shop's data up to date with the marketplaces managed by Shopping Feed, reciprocally; hence the "synchronization".

This allows the merchant to manage all his orders and catalog from his shop, instead of managing his business on each marketplace.


1. Requirements and install

Source: 01-installation/01-requirements.md

Requirements

PHP version

PrestaShop version Module version Repo Doc PHP Version
1.6.0.x 1.x [master] module documentation 5.6 or greater
1.7.7.x 1.x [master] module documentation 7.1 or greater

Shopping Feed API

Shopping Feed's PHP SDK; this module uses version 0.2.4, which creates some problems.

Shopping Feed's PHP Feed Generator; this module uses version 1.2.0.

DO NOT run composer install without reading about our problems with Guzzle ! Running composer dump-autoload should be fine, though.

Installation for merchands

To install module on PrestaShop, download zip package supply by ShoppingFeed customer service or the zip file named v1.x.x-prod-shoppingfeed.zip attached on each detail release page.

Installation for developpers

If you are a developper, this module contain composer.json.dist file. If you clone or download the module from github repository, run the composer install is not necessary. You can see why on module documentation on "Guzzle trouble".

See the composer documentation to learn more about the composer.json file.

You can also use docker compose to install the module on a fresh ready to use PrestaShop version.

Compiling assets

For development

We use Webpack to compile our javascript and scss files. In order to compile those files, you must :

  1. have Node 10+ installed locally
  2. run npm install in the root folder to install dependencies
  3. then run npm run watch to compile assets and watch for file changes

For production

Run npm run build to compile for production. Files are minified, console.log and comments dropped.

Contributing

PrestaShop modules are open-source extensions to the PrestaShop e-commerce solution. Everyone is welcome and even encouraged to contribute with their own improvements.

Requirements

Contributors must follow the following rules:

  • Make your Pull Request on the "develop" branch, NOT the "master" branch.
  • Do not update the module's version number.
  • Follow the coding standards.

Process in details

Contributors wishing to edit a module's files should follow the following process:

  1. Create your GitHub account, if you do not have one already.
  2. Fork the shoppingflux/module-prestashop project to your GitHub account.
  3. Clone your fork to your local machine in the /modules/shoppingfeed directory of your PrestaShop installation.
  4. Create a branch in your local clone of the module for your changes.
  5. Change the files in your branch. Be sure to follow the coding standards!
  6. Push your changed branch to your fork in your GitHub account.
  7. Create a pull request for your changes on the 'develop' branch of the module's project. Be sure to follow the commit message norm in your pull request. If you need help to make a pull request, read the Github help page about creating pull requests.
  8. Wait for one of the core developers either to include your change in the codebase, or to comment on possible improvements you should make to your code.

That's it: you have contributed to this open-source project! Congratulations!


2. Problem : Guzzle trouble

Source: 01-installation/02-guzzle.md

Problem

With version 0.2.1-beta.1, the SDK uses Guzzle for HTTP communication. However, it uses a more recent version of Guzzle than Prestashop.

  • If the SDK's Guzzle is used, Prestashop breaks.
  • If Prestashop's Guzzle is used, the SDK breaks.

Solution

The prefixing script

The 202/prefix-vendor-namespace.php script is used to prefix the Guzzle library namespaces used by the SDK, as well as the SDK itself. The script must be used from CLI, and is configured directly in the file.
However, changes must be made so that :

  • The autoloader won't load the "original" Guzzle, or any of its own dependencies
  • The autoloader won't load the "original" SDK, since it uses the "original" Guzzle
  • The autoloader will load the "prefixed" Guzzle, with all its own "prefixed" dependencies
  • The autoloader will load the "rewritten" SDK, which uses the new Guzzle namespace.

Our composer.json file :

{
  "require": {
    "shoppingfeed/php-sdk": "0.2.1-beta.1"
  },
  "config": {
    "vendor-dir": "vendor"
  },
  "autoload": {
    "files": [
      "vendor/prefixed/guzzlehttp/guzzle/src/functions_include.php",
      "vendor/prefixed/guzzlehttp/psr7/src/functions_include.php",
      "vendor/prefixed/guzzlehttp/promises/src/functions_include.php"
    ],
    "psr-4": {
      "SfGuzzle\\GuzzleHttp\\":          "vendor/prefixed/guzzlehttp/guzzle/src/",
      "SfGuzzle\\GuzzleHttp\\Psr7\\":    "vendor/prefixed/guzzlehttp/psr7/src/",
      "SfGuzzle\\GuzzleHttp\\Promise\\": "vendor/prefixed/guzzlehttp/promises/src/",
      "ShoppingFeed\\Sdk\\":             "vendor/prefixed/shoppingfeed/php-sdk/src/"
    }
  }
}

The "directly included files" (e.g. vendor/prefixed/guzzlehttp/guzzle/src/functions_include.php) must be modified by hand, as they use namespaces in strings.

if (!function_exists('SfGuzzle\GuzzleHttp\uri_template')) {
    require __DIR__ . '/functions.php';
}

You can find which files should be included directly by looking at the libraries own composer.json files (e.g. /guzzlehttp/guzzle/composer.json).
You can also check these files to fill the psr-4 namespaces in the main composer.json.

Autoloading

As of now, the only way to prevent Composer from autoloading Guzzle is to rename or remove the folder. Using the "exclude-from-classmap" property does not work, since the namespace can still be resolved using the filesystem.
We don't have to do it for the SDK however, since we're not trying to prevent Composer from loading it, but to have it loaded from a different path.

Nevertheless, the PHP script moves all the "original" libraries to the 202 folder to solve those problems.

Usage

From the command line :

modules/shoppingfeed$ composer install
modules/shoppingfeed$ php 202/prefix-vendor-namespace.php
modules/shoppingfeed$ composer dump-autoload

The vendor/prefixed folder and the "original" libraries in 202 should be deleted before attempting a dependency update.
As mentioned previously, directly included files must be modified by hand.


Products

1. Products overview

Source: 02-features_products/01-overview.md

The module allows either real-time synchronization, or batch synchronization.

Every synchronizable field should have its associated classlib Actions class extending the abstract ShoppingfeedProductSyncActions class.

The syncProduct controller extending classlib's CronController is responsible for processing update batches.

Synchronization method

When real-time synchronization is selected, the module will send a request to the Shopping Feed API each time a synchronizable product field is updated; this may be dangerous for shops with a lot of traffic.

Whenever a product is updated, it will be added as "to synchronize" in the shoppingfeed_product table. From there, 2 possibilities :

  • If batch synchronization is selected, a CRON task will later read this table and send update requests to the Shopping Feed API with multiple products. The number of updates to process each time the task is run may be changed in the module's configuration page.
  • If real-time synchronization is selected, the requests will be sent immediately.

The only difference between real-time and batch synchronization lies in when the ShoppingfeedProductSync[Field]Actions will be executed.

The abstract ShoppingfeedProductSyncActions class

No matter which synchronization method is selected, an updated product will always be saved in the shoppingfeed_product table before being processed.

Every synchronizable field should have an associated classlib Actions class extending the ShoppingfeedProductSyncActions class. The class name is important; it should be formatted like ShoppingfeedProductSync[Field]Actions so that adding the new field will be easy in the syncProduct controller processing batch synchronizations.


class ShoppingfeedProductSyncStockActions extends ShoppingfeedProductSyncActions
{
    // ...
}

Since saving and retrieving updates to process is similar for every synchronizable fields, the abstract ShoppingfeedProductSyncActions is the one implementing those features. Every "field process" (e.g. ShoppingfeedProductSyncStockActions) should implement the remaining methods. Note that when real-time synchronization is selected, the ShoppingfeedProductSyncActions::saveProduct method will automatically forward to the ShoppingfeedProductSyncActions::getBatch method to run the synchronization process.

Processing the updates with batch synchronization

As previously mentioned, the syncProduct controller will process batch synchronization; it is responsible for checking which fields should be updated.

class ShoppingfeedSyncProductModuleFrontController extends CronController
{
    protected function processCron($data)
    {
        // Every field to synchronize should follow this pattern
        if(Configuration::get(Shoppingfeed::STOCK_SYNC_ENABLED)) {
            $actions[ShoppingfeedProduct::ACTION_SYNC_STOCK] = array(
                'actions_suffix' => 'Stock'
            );
        }

        // ...

        foreach($actions as $action => $actionData) {
            $this->processAction($action, $actionData['actions_suffix']);
        }

        // ...

    }

    // ...

    protected function processAction($action, $actions_suffix)
    {
        // ...

        // The 'actions_suffix' is used to find the Actions class
        $handler->setConveyor(array(
            'id_shop' => $shop['id_shop'],
            // The 'action' is the value saved in a ShoppingfeedProduct
            'product_action' => $action,
        ));
        $processResult = $handler->process('shoppingfeedProductSync' . $actions_suffix);

        // ...
    }
}

2. Mapping to Shopping Feed's catalog

Source: 02-features_products/02-product_mapping.md

The module uses the method Shoppingfeed::mapReference to get a product's reference for the Shopping Feed catalog. By default, this reference is {ps_id_product} (e.g. 1) or {ps_id_product}_{ps_id_product_attribute} if a declination is updated (e.g. 1_12).

To specify a different Shopping Feed reference, one may either :

  • Override the module's class and rewrite the mapReference method,
  • Create a module and hook it to the ShoppingfeedMapProductReference hook

// The reference is passed... by reference, so that you may tweak it.
Hook::exec(
    'ShoppingfeedMapProductReference', // hook_name
    array(
        'ShoppingFeedProduct' => &$sfProduct,
        'reference' => &$reference
    ) // hook_args
);

Note that having the method return false (weak comparison) will skip the update for the product and remove it from the updates list.


3. Stock synchronization

Source: 02-features_products/03-stock_sync.md

Detecting changes

A product's stock may change either when modified from the back-office, or during an order process.

Stock changes are detected through the actionUpdateQuantity hook. The updated product is saved as a ShoppingfeedProduct using the ActionsHandler component from Classlib; whether the update should be queued or immediately sent to the Shopping Feed API is managed in the abstract Action class.

Processing changes

Updated products are always saved in the database before being sent. The ProcessLogger component from Classlib is used to track every update process.

If real-time synchronization is selected, the ActionsHandler will execute the update chain immediately after saving the product. If not, a CRON task managed with Classlib's ProcessMonitor component will process the saved updates using the same chain of actions.


4. Price synchronization

Source: 02-features_products/04-price_sync.md

Detecting changes

A product's price may change only when modified from the back-office. Since there is no hook specific to price changes, the actionObjectProductUpdateBefore and actionObjectCombinationUpdateBefore are used to detect price changes.

Only products whose prices were updated are added to the updates list. However, a combination's price may change due to the "original" product's price changing.
Therefore, when a product's price change is detected in the actionObjectProductUpdateBefore hook, an id_product is saved in the classlib Registry so that the actionObjectCombinationUpdateBefore hook can check whether an updated combination should be added to the updates list.

Note : if a product or combination is updated, but does not pass Prestashop's validation, it might still be added to the list if its price has changed. But this shouldn't happen often, and since it will probably be re-updated with correct values right away, it shouldn't be a problem.

The updated product is saved as a ShoppingfeedProduct using the ActionsHandler component from Classlib; whether the update should be queued or immediately sent to the Shopping Feed API is managed in the abstract Actions class.

Processing changes

Updated products are always saved in the database before being sent. The ProcessLogger component from Classlib is used to track every update process.

If real-time synchronization is selected, the ActionsHandler will execute the update chain in the actionObjectProductUpdateAfter and actionObjectCombinationUpdateAfter hooks. If not, a CRON task managed with Classlib's ProcessMonitor component will process the saved updates using the same chain of actions.


5. Products feed synchronization

Source: 02-features_products/05-product_sync.md

Overview

The XML feed is not computed when Shoppingfeed call it. In fact each time a product is updated (on actionObjectProductUpdateBefore or actionObjectCombinationUpdateBefore), a serialized version of the product is put in cache (on the database).

Add or modify content on the feed

You can used 3 hooks called just before put in cache the serialized product:

  • shoppingfeedSerialize
  • shoppingfeedSerializePrice
  • shoppingfeedSerializeStock

The array content of the product are set by reference, so you can modify it as you want.


// myCustomShoppingfeedModule.php

/**
 * Change boolean attribute "isWashable" by a friendly text
 */
public function hookShoppingfeedSerialize(&$params)
{
    $isWashable = $params['content']['attributes']['isWashable'];

    if ($isWashable === true) {
        $params['content']['attributes']['washableText'] = 'This item is washable.';
    } else {
        $params['content']['attributes']['washableText'] = 'This item is NOT washable.';
    }

}

Processing changes

Updated products are always saved in the database before being sent. The ProcessLogger component from Classlib is used to track every update process.

If real-time synchronization is selected, the ActionsHandler will execute the update chain in the actionObjectProductUpdateAfter and actionObjectCombinationUpdateAfter hooks. If not, a CRON task managed with Classlib's ProcessMonitor component will process the saved updates using the same chain of actions.


Orders

1. Orders overview

Source: 03-features_orders/01-overview.md

Most of the process is similar to the products synchronization. However, updating an order's status leads to the creation of a ticket rather than an immediate confirmation (see 2. Status synchronization).

Orders allow only batch synchronization.

The syncOrder controller extending classlib's CronController is responsible for processing update batches.

Note : this module is not responsible for importing orders from the SF API (yet). The module should only synchronize orders imported using the shoppingfluxexport module.
A new CronController / Action pair will be created (one day, but not today) to support orders import; most likely named ShoppingfeedOrdersImportActions to separate the two features.

This module will use the validateOrder hook to detect orders added by the shoppingfluxexport module, and will then add a row in the shoppingfeed_order table. Data that couldn't be retrieved in the validateOrder hook will be added once an order synchronization is registered.

To see where the necessary data is stored, check the Shoppingfluxexport::hookPostUpdateOrderStatus() method in the shoppingfluxexport module.

Synchronization method

Orders only supports batch synchronization.

The ShoppingfeedOrderSyncActions class

Updated orders will always be saved in the shoppingfeed_task_order table before being processed.



use ShoppingfeedClasslib\Actions\DefaultActions;

class ShoppingfeedOrderSyncActions extends DefaultActions
{
    // ...
}

Processing the updates with batch synchronization

As previously mentioned, the syncOrder controller will process batch synchronization; it is responsible for checking which fields should be updated.


2. Mapping to Shopping Feed's catalog

Source: 03-features_orders/02-order_mapping.md

Orders are mapped using the name_marketplace and id_order_marketplace fields. It should be noted that an id_order_marketplace is unique only on the associated name_marketplace, so we need both values to identify an order.


3.1 Import orders

Source: 03-features_orders/03-import_orders.md

The import of new order uses the same CRON task as the order status update.

There is 11 steps to import an order:

  • Carrier retrieved
  • Order verified
  • Customer created
  • Customer retrieved from billing address
  • Billing address created / updated
  • Shipping address created / updated
  • Products quantities updated / validated
  • Cart created
  • Products added to cart
  • Order validated
  • Order acknowledged with SF API
  • Order prices updated

Each step can be intercept by a specipic import rules call back event. See also.

This module supply 10 specific rules documented on the backoffice of the module, menu: "Specific import order rules". It manage all specific behaviours of a marketplace or carrier.


3.2 Status synchronization

Source: 03-features_orders/03-status_sync.md

The order's statuses synchronization feature is already implemented by the shoppingfluxexport module. To avoid conflicts, this module will not run any order synchronization while the shoppingfluxexport module is configured to run order synchronization. (see The order statuses)

Only the order's current state will be taken into account to request the update from SF. If the order's current state is not managed by the API, the order will be removed from the queue (i.e. the shoppingfeed_task_order table).

Important note : order updates must be delayed when a Shipped status change is triggered, since the API requires a tracking number to register it, and it may not have been set by the merchant when the status changes (see Detecting changes). The exact delay can be configured from the back-office (default is 5 minutes).

The ticket system

When requesting a status change on an order, the update isn't processed immediately. Instead, a ticket number is returned by the SF API. This ticket number must be saved to monitor the update status; it will be set in the shoppingfeed_task_order, and the action will be updated accordingly.

The order statuses

The order statuses mapping can be edited in the module's configuration page. For now, the module supports the Shipped, Canceled, and Refunded statuses.

To avoid conflicts with the shopppingfluxexport module :

  • As long as the shoppingfluxexport module is not installed, the merchant won't be able to activate orders synchronization. If it's already activated, an error message will be logged by the CRON task.
  • As long as the shoppingfluxexport module is configured to synchronize orders, the merchant won't be able to activate orders synchronization. If it's already activated, an error message will be logged by the CRON task.

Multiple native PrestaShop order statuses may be selected to trigger an update, because third-party modules may add their own.

Note that the Refunded status update may only work when the order was imported from some specific marketplaces.

Detecting changes

To avoid conflicts with the shopppingfluxexport module :

  • If the shoppingfluxexport module is not installed or if it's still configured to synchronize orders, our process will not be executed and an error will be logged.

Status changes are detected in the actionOrderStatusPostUpdate hook. The order update is saved as a ShoppingfeedTaskOrder using the ActionsHandler component from Classlib.

When a Shipped status change is detected, the order update processing must be delayed to give the merchant some time to fill the order's tracking number. The exact delay can be configured from the back-office (default is 5 minutes).

The update_at field must be filled accordingly : time() + delay_in_secondes

Processing changes

To avoid conflicts with the shopppingfluxexport module :

  • If the shoppingfluxexport module is not installed or is still configured to synchronize orders, our process will not be executed and an error will be logged.

Orders updates are always saved in the database before being sent. The ProcessLogger component from Classlib is used to track every synchronization process.

A CRON task managed with Classlib's ProcessMonitor component will process the saved updates using the chain of actions.

Only the current status of an order will be checked. No need to save the order status in the update.

When requesting an order status update, the SF API will return a ticket number and a batch id. The ticket number must be saved to check it later; as we're not sure of the batch id's purpose, it will be saved as well.

Checking the ticket

Another process in the same ShoppingfeedOrderSyncActions class will be used to :

  • Check which orders have a ticket,
  • Check the ticket status with the SF API,
  • Act accordingly :
    • If the task succeeded, delete the order from the SF table.
    • If the task failed, add the order in the error mail.
    • If the task is still going, don't do anything; leave the order in the SF table.

It's quite similar to the other processes : get data, process data, send data, process result. This process uses the same CRON task as the order status update.


4. Data Model

Source: 03-features_orders/04-data_model.md

ShoppingFeedOrder

"Extends" a native PrestaShop order. Each line represents an order added by the shoppingfluxexport module.

Column Type Description
id_shoppingfeed_order int Primary key
id_internal_shoppingfeed string The order's id on shoppingfeed
id_order_marketplace string The order's id on the marketplace
name_marketplace string The order's marketplace
id_order int The native PrestaShop order id
payment_method string The payment_method on marketplace
date_marketplace_creation string Creation date on the marketplace
shipped_sent bool, default 0 Was the tracking number ever sent ?
date_add date
date_upd date

ShoppingFeedCarrier

"Map" a native PrestaShop carrier with marketplace carriers.

Column Type Description
id_shoppingfeed_carrier int primary key
name_marketplace string (50) The name of the marketplace (lowercase by convention)
name_carrier string (190) The native PrestaShop order id
id_carrier_reference int PrestaShop carrier reference
is_new boolean Is a new imported carrier ? Set to false when settings are saved
date_add date
date_upd date

ShoppingFeedTaskOrder

Represents a task to send to the Shopping Feed API. Very similar to the shoppingfeed_product table.

Column Type Description
id_shoppingfeed_task_order int primary key
action string (enum) The nature of the task; a constant from ShoppingFeedTaskOrder
id_order int The native PrestaShop order id
ticket_number string (default NULL) A Shopping Feed ticket number
batch_id string (default NULL) A Shopping Feed batch id
update_at date The date after which this task should be sent
date_add date
date_upd date

5. Testing

Source: 03-features_orders/05-roadmap.md

Testing this feature is a bit tricky. There are 2 ways to create an order on Shopping Feed's platform :

Tests have determined that :

  • Orders created using the platform could successfully be imported by the shoppingfluxexport module, but could not be updated using the new module.
  • Orders created through the API could not be imported by the shoppingfluxexport module, but could successfully be updated using the new module.

This means that the "hook on import" part of the process cannot be tested using the same orders as the "update order status" part.

To test the "update order status" process, one must manually add order data in the shoppingfeed_task_order table to map orders from PrestaShop with orders from Shopping Feed.

Developper

1. Internal hooks

Source: 04-customize/01-shoppingfeed-hooks.md

We recommand to not use override classes but hooks designed for developpers.

Products

  • ShoppingfeedMapProductReference:
    • Manage your own refecence of products ID. By default ID sent to shopping feed are id_product_id_attribute (ex: 125_61)
    • Returns the product's Shopping Feed reference. The developer can skip products to sync by returning false.
  • ShoppingfeedMapProduct (reverse of the previous method):
    • Returns the Prestashop product matching the Shopping Feed reference.
    • The developer can skip specific products during order import by overriding this method and have it return false.
  • ShoppingfeedMapProductPrice:
    • Returns the product's price sent to the Shopping Feed API.
    • The developer can skip products to sync by overriding this method and have it return false.
    • Note that the comparison with the return value is strict to allow "0" as a valid price.

Order

  • actionShoppingfeedOrderImportRegisterSpecificRules:
    • Adds the order import specific rules class to the manager.
    • Add, remove or extend an order import rule ! Use this hook to declare your own behaviour.
  • actionShoppingfeedTracking
    • Manage specific tracking url (shippment) on order feed (for instance URL with name of reciepient like "Relais colis")
  • actionShoppingfeedOrderImportCriteria
    • Manage criteria to retrienve new order
      • Skip unacknowledge order
      • Import available Shoppingfeed status: created, waiting_store_acceptance (default), refused, waiting_shipment, shipped, cancelled, refunded, partially_refunded, partially_shipped

Handler Actions class

This module use a design pattern call "Chain of responsability" on classes/actions direcory.

  • actionShoppingfeedActionsHandler:
    • Replace or override any class set on classes/actions
    • You can use obviously namespaces

2. Specific import order rules

Source: 04-customize/02-specific-order-rules.md

You can mange classes of rules to add a behaviour during the import of an order.

You need to create a rules class extends RuleAbstract and implements RuleInterface and declare on the actionShoppingfeedOrderImportRegisterSpecificRules hook.

Basic usage :


use ShoppingfeedAddon\OrderImport\RuleAbstract;
use ShoppingfeedAddon\OrderImport\RuleInterface;
use ShoppingFeed\Sdk\Api\Order\OrderResource;

use ShoppingfeedClasslib\Extensions\ProcessLogger\ProcessLoggerHandler;

class MyOwnRules extends RuleAbstract implements RuleInterface
{

    public function isApplicable(OrderResource $apiOrder)
    {
        $apiOrderData = $apiOrder->toArray();
        // apiOrderData give you all order data coming from API
        // put here conditions to set this rules according to apiOrderData
        // for instance according to the marketplace, the carrier, ...

        return true;
    }

    /**
     * @inheritdoc
     */
    public function getConditions()
    {
        return $this->l('My description of condition 'MyOwnRules');
    }

    /**
     * @inheritdoc
     */
    public function getDescription()
    {
        return $this->l('My description of what to do 'MyOwnRules');
    }

}

After defining your own class you can add one or several event schedule to be called back during the import process :

  • onPreProcess
  • onCarrierRetrieval
  • onVerifyOrder
  • onCustomerCreation
  • onCustomerRetrieval
  • beforeBillingAddressCreation
  • beforeBillingAddressSave
  • beforeShippingAddressCreation
  • beforeShippingAddressSave
  • checkProductStock
  • onCartCreation
  • afterCartCreation
  • afterOrderCreation
  • onPostProcess

You can also add configuration form on your backoffice "Specific rules" by adding a method getConfigurationSubform.

    public function getConfigurationSubform()
    {
        return array(
            array(
                'type' => 'switch',
                'label' => $this->l('My label', 'MyOwnRules'),
                'name' => 'mybeautyfullname',
                'is_bool' => true,
                'values' => array(
                    array(
                        'value' => 1,
                    ),
                    array(
                        'value' => 0,
                    )
                ),
            )
        );
    }

    public function getDefaultConfiguration()
    {
        return array('mybeautyfullname' => true);
    }

    // sample usage
    public function onPreProcess($params)
    {
        if (empty($this->configuration['mybeautyfullname'])) {
            return false;
        }
        // rest of the process
    }