DeliveryModuleBundle/doc/index.md

Getting started with RetailCrmDeliveryModuleBundle

Prerequisites

This version of the bundle requires Symfony 5.1.

Translations

If you wish to use default texts provided in this bundle, you have to make sure you have translator enabled in your config:

    # config/packages/translation.yaml

    framework:
        translator: { fallback: en }

For more information about translations, check Symfony documentation.

Installation

Installation is a 7 steps process:

1. Download RetailCrmDeliveryModuleBundle
2. Enable the Bundle
3. Create your model class
4. Create your integration module factory
5. Create your delivery service
6. Create your tracker
7. Configure the RetailCrmDeliveryModuleBundle

Step 1: Install RetailCrmDeliveryModuleBundle

The preferred way to install this bundle is to rely on Composer.

Just check on Packagist the version you want to install (in the following example, we used "dev-master") and add it to your composer.json:

{
    "require": {
        // ...
        "retailcrm/delivery-module-bundle": "dev-master"
    }
}

Step 2: Enable the bundle

Finally, enable the bundle in the kernel:

<?php
// config/bundles.php

return [
    // ...
    RetailCrm\DeliveryModuleBundle\RetailCrmDeliveryModuleBundle::class => ['all' => true],
];

Step 3: Create model classes

This bundle needs to persist some classes to a database:

• Account
• Delivery

Your first job, then, is to create these classes for your application. These classes can look and act however you want: add any properties or methods you find useful.

These classes have just a few requirements:

1. They must extend one of the base classes from the bundle
2. They must have an id field

In the following sections, you'll see examples of how your classes should look, depending on how you're storing your data.

Your classes can live inside any bundle in your application.

Warning:

If you override the __construct() method in your classes, be sure to call parent::__construct(), as the base class depends on this to initialize some fields.

Doctrine ORM classes

If you're persisting your data via the Doctrine ORM, then your classes should live in the Entity namespace of your bundle and look like this to start:

<?php
// src/App/Entity/Account.php

namespace App\Entity;

use RetailCrm\DeliveryModuleBundle\Entity\Account as BaseAccount;
use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity
 */
class Account extends BaseAccount
{
    /**
     * @ORM\Id
     * @ORM\Column(type="integer")
     * @ORM\GeneratedValue(strategy="AUTO")
     */
    protected $id;

    public function __construct()
    {
        parent::__construct();
        // your own logic
    }
}

<?php
// src/App/Entity/Delivery.php

namespace Acme\ApiBundle\Entity;

use RetailCrm\DeliveryModuleBundle\Entity\Delivery as BaseDelivery;
use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity
 */
class Delivery extends BaseDelivery
{
    /**
     * @ORM\Id
     * @ORM\Column(type="integer")
     * @ORM\GeneratedValue(strategy="AUTO")
     */
    protected $id;

    /**
     * @ORM\ManyToOne(targetEntity="Account")
     * @ORM\JoinColumn(nullable=false, onDelete="CASCADE")
     */
    protected $account;
}

Note: If you don't have auto_mapping activated in your doctrine configuration you need to add RetailCrmDeliveryModuleBundle to your mappings in config/packages/doctrine.yaml.

Custom database driver

The bundle provides driver for Doctrine ORM.

Though sometimes you might want to use the bundle with a custom or in-house written storage. For that, the bundle has support for custom storage. Once set, setting manager options in retail_crm_delivery_module.service section becomes mandatory.

Step 4: Create your integration module factory

The IntegrationModuleFactory class responsibility is to build integration module configuration for RetailCRM.

A custom integration module factory needs to implement RetailCrn\DeliveryModuleBundle\Integration\Crm\IntegrationModuleFactoryInterface or extend RetailCrn\DeliveryModuleBundle\Integration\Crm\AbstractIntegrationModuleFactory, which makes creating an integration module factory even easier:

# src/Integration/Crm/CustomIntegrationModuleFactory.php

use RetailCrm\DeliveryModuleBundle\Integration\Crm\AbstractIntegrationModuleFactory;
use RetailCrm\DeliveryModuleBundle\Model\Account;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;

class CustomIntegrationModuleFactory extends AbstractIntegrationModuleFactory
{
    /** @var UrlGeneratorInterface */
    private $urlGenerator;

    public function __construct(UrlGeneratorInterface $urlGenerator, array $configuration)
    {
        $this->urlGenerator = $urlGenerator;

        parent::__construct($configuration);
    }

    protected function getBaseUrl(): string
    {
        return $this->urlGenerator->generate('base_url', [], UrlGeneratorInterface::ABSOLUTE_URL);
    }

    protected function getAccountUrl(): string
    {
        return $this->urlGenerator->generate('account_url', [], UrlGeneratorInterface::ABSOLUTE_URL);
    }

    protected function getDeliveryConfiguration(Account $account): array
    {
        $configuration = [];

        $configuration['description'] = sprintf("Account %s[%s] configuration", $account->getUrl(), $account->getClientId());
        
        $configuration['actions'] = [
            'calculate' => 'delivery/calculate',
            'save' => 'delivery/save',
            'get' => 'delivery/get',
            'delete' => 'delivery/delete',
            'shipmentPointList' => 'delivery/shipment-point-list',
            'shipmentSave' => 'delivery/shipment-save',
            'shipmentDelete' => 'delivery/shipment-delete',
            'tariffList' => 'delivery/tariff-list',
            'print' => 'delivery/print',
        ];

        $configuration['payerType'] = [
            'receiver',
            'sender',
        ];

        // TODO: add your logic

        return $configuration;
    }
}

Step 5: Create your delivery service

The DeliveryService class responsibility is to provide a gateway for delivery API.

Custom delivery service must implement:

• RetailCrm\DeliveryModuleBundle\DeliveryService\ProcessableDeliveryServiceInterface if delivery provides create/delete processing
• RetailCrm\DeliveryModuleBundle\DeliveryService\TrackableDeliveryServiceInterface if delivery provides tracking service

Step 6: Create your tracker

The Tracker class responsibility is to provide a tracking service.

You can use default tracker retail_crm_delivery_module.tracker.default or crete your custom.

Tracker is class must implement the RetailCrm\DeliveryModuleBundle\Tracking\TrackerInterface. This interface defines one method called tracking to perform delivery tracking.

Step 7: Configure RetailCrmDeliveryModuleBundle

Import the routing configuration file in config/routes.yaml:

# config/routes.yaml
retail_crm_delivery_module_callback_delivery:
    resource: "@RetailCrmDeliveryModuleBundle/Resources/config/routing/delivery_callback.xml"

retail_crm_delivery_module_callback_integration_module:
    resource: "@RetailCrmDeliveryModuleBundle/Resources/config/routing/integration_module_callback.xml"

Add RetailCrmDeliveryModuleBundle settings in config/packages/retail_crm_delivery_module.yaml:

# config/packages/retail_crm_delivery_module.yaml
retail_crm_delivery_module:
    db_driver: orm # Drivers available: orm or custom
    
    model:
        account_class:  App\Entity\Account
        delivery_class: App\Entity\Delivery

    service:
        manager:
            account: retail_crm_delivery_module.manager.account.default # Or your custom
            delivery: retail_crm_delivery_module.manager.delivery.default # Or your custom
        integration_module_factory: App\IntegrationModule\CustomIntegrationModuleFactory
        delivery_service: App\DeliveryService\CustomDeliveryService
        tracker: retail_crm_delivery_module.tracker.default # Or your custom

Update your database schema

Now the bundle is configured, the last thing you need to do is update your database schema because you have added a new entity.

For ORM run the following command.

$ php bin/console doctrine:schema:update --force