sylius/refund-plugin

Plugin provides basic refunds functionality for Sylius application.

Installs: 128 302

Dependents: 4

Suggesters: 0

Security: 0

Stars: 42

Watchers: 11

Forks: 45

Open Issues: 18

Type:sylius-plugin


README

68747470733a2f2f64656d6f2e73796c6975732e636f6d2f6173736574732f73686f702f696d672f6c6f676f2e706e67

Refund Plugin

68747470733a2f2f7472617669732d63692e6f72672f53796c6975732f526566756e64506c7567696e2e7376673f6272616e63683d6d6173746572

68747470733a2f2f73796c6975732e636f6d2f6173736574732f62616467652d6f6666696369616c2d73796c6975732d706c7567696e2e706e67

This plugin provides basic refunds functionality for Sylius application.

Screenshot showing order's refund section

Screenshot showing order's credit memos and refund payments

Business value

In contrast to basic Refund functionality delivered by core Sylius bundles, Refund Plugin offers much wider range of possibilities and business scenarios.

Once an Order is paid, an Administrator is able to access Refunds section of a given Order and perform a Refund of chosen items or shipments. What's more, if a more detailed scenario occurs, an Administrator is able to refund an item partially.

From Administrator's point of view, every Refund request results in creating two entities:

  • Credit Memo - a document representing a list of refunded items (downloadable and sent to Customer via .pdf file)
  • Refund Payment - entity representing payment in favour of the Customer

Pre - requirements

In order to be able to generate PDF files of refunds, wkhtmltopdf must be installed. It is used by KnpSnappyBundle and can be configured according to their docummentation.

Installation

  1. Require plugin with composer:

    composer require sylius/refund-plugin:1.0.0-RC.9

    Remember to allow community recipes with composer config extra.symfony.allow-contrib true or during plugin installation process

  2. Apply migration to your database:

    bin/console doctrine:migrations:migrate
  3. Copy Sylius templates overridden in plugin to your templates directory (e.g templates/bundles/):

    mkdir -p templates/bundles/SyliusAdminBundle/
    cp -R vendor/sylius/refund-plugin/src/Resources/views/SyliusAdminBundle/* templates/bundles/SyliusAdminBundle/
  4. If you use Sylius v1.8 you also need to change files src/Entity/Shipping/Shipment.php and src/Entity/Order/Adjustment.php to use proper traits and interfaces:

    <?php
    
    declare(strict_types=1);
    
    namespace App\Entity\Order;
    
    use Doctrine\ORM\Mapping as ORM;
    use Sylius\Component\Order\Model\Adjustment as BaseAdjustment;
    use Sylius\RefundPlugin\Entity\AdjustmentInterface as RefundAdjustmentInterface;
    use Sylius\RefundPlugin\Entity\AdjustmentTrait;
    
    /**
    * @ORM\Entity
    * @ORM\Table(name="sylius_adjustment")
    */
    class Adjustment extends BaseAdjustment implements RefundAdjustmentInterface
    {
        use AdjustmentTrait;
    }
    <?php
    
    declare(strict_types=1);
    
    namespace App\Entity\Shipping;
    
    use Doctrine\Common\Collections\ArrayCollection;
    use Doctrine\ORM\Mapping as ORM;
    use Sylius\Component\Core\Model\AdjustmentInterface as BaseAdjustmentInterface;
    use Sylius\Component\Core\Model\Shipment as BaseShipment;
    use Sylius\RefundPlugin\Entity\ShipmentTrait;
    use Sylius\RefundPlugin\Entity\ShipmentInterface as RefundShipmentInterface;
    
    /**
    * @ORM\Entity
    * @ORM\Table(name="sylius_shipment")
    */
    class Shipment extends BaseShipment implements RefundShipmentInterface
    {
        use ShipmentTrait;
    
        public function __construct()
        {
            parent::__construct();
    
            /** @var ArrayCollection<array-key, BaseAdjustmentInterface> $this->adjustments */
            $this->adjustments = new ArrayCollection();
        }
    }

Beware!

This installation instruction assumes that you're using Symfony Flex. If you don't, take a look at the legacy installation instruction. However, we strongly encourage you to use Symfony Flex, it's much quicker! :)

Extension points

Refund Plugin is strongly based on both commands and events. Let's take RefundUnitsAction as an example. The whole process consists of following steps:

  • Getting data from request
  • Create a Command and fill it with data
  • Dispatch Command
  • Handle Command
  • Fire Event
  • Catch Event in Listener class

Using command pattern and events make each step independent which means that providing custom implementation of given part of refunding process doesn't affect any other step.

Apart from Events and Commands Refund Plugin is also based on mechanisms derived from core Sylius bundles such as:

Configuration of all elements mentioned above can be found and customized in config.yml file.

Payment requirements

By default to refund your order, you need to have at least one available payment method configured with offline gateway. In case your custom refund logic allows a different type of gateway (for example stripe), you should modify the specific parameter, as shown below:

    # config/services.yaml
    
    parameters:
        sylius_refund.supported_gateways:
            - offline
            - stripe

Online refund logic should be implemented if you need it. As the first try for the possible customization, you can check out Sylius\RefundPlugin\Event\UnitsRefunded event.

Security issues

If you think that you have found a security issue, please do not use the issue tracker and do not post it publicly. Instead, all security issues must be sent to security@sylius.com.