|
16 | 16 |
|
17 | 17 | <p align="center">This plugin provides basic refunds functionality for Sylius application.</p> |
18 | 18 |
|
19 | | - |
| 19 | +--- |
20 | 20 |
|
21 | | - |
| 21 | +## Documentation |
22 | 22 |
|
23 | | - |
| 23 | +📖 Full documentation is available here: |
| 24 | +👉 [Refund Plugin Documentation](https://docs.sylius.com/refund-plugin) |
24 | 25 |
|
25 | | -## Business value |
26 | | - |
27 | | -In contrast to basic Refund functionality delivered by core Sylius bundles, Refund Plugin offers much wider range of |
28 | | -possibilities and business scenarios. |
29 | | - |
30 | | -Once an Order is paid, an Administrator is able to access Refunds section of a given Order and perform a Refund |
31 | | -of chosen items or shipments. What's more, if a more detailed scenario occurs, an Administrator is able to refund an item |
32 | | -partially. |
33 | | - |
34 | | -From Administrator's point of view, every Refund request results in creating two entities: |
35 | | -* Credit Memo - a document representing a list of refunded items (downloadable and sent to Customer via .pdf file) |
36 | | -* Refund Payment - entity representing payment in favour of the Customer |
37 | | - |
38 | | -## Installation |
39 | | - |
40 | | -#### Beware! |
41 | | - |
42 | | -This installation instruction assumes that you're using Symfony Flex. If you don't, take a look at the |
43 | | -[legacy installation instruction](docs/legacy_installation.md). However, we strongly encourage you to use |
44 | | -Symfony Flex, it's much quicker! |
45 | | - |
46 | | -1. Require plugin with composer: |
47 | | - |
48 | | - ```bash |
49 | | - composer require sylius/refund-plugin |
50 | | - ``` |
51 | | - |
52 | | - > Remember to allow community recipes with `composer config extra.symfony.allow-contrib true` or during plugin installation process |
53 | | - |
54 | | -1. Apply migrations to your database: |
55 | | - |
56 | | - ```bash |
57 | | - bin/console doctrine:migrations:migrate |
58 | | - ``` |
59 | | - |
60 | | -1. Run `yarn encore dev` or `yarn encore production` |
61 | | - |
62 | | -1. Default configuration assumes enabled PDF file generator. If you don't want to use that feature change your app configuration: |
63 | | -
|
64 | | - ```yaml |
65 | | - # config/packages/sylius_refund.yaml |
66 | | - sylius_refund: |
67 | | - pdf_generator: |
68 | | - enabled: false |
69 | | - ``` |
70 | | -
|
71 | | - Otherwise, check if you have wkhtmltopdf binary. If not, you can download it [here](https://wkhtmltopdf.org/downloads.html). |
72 | | -
|
73 | | - In case wkhtmltopdf is not located in `/usr/local/bin/wkhtmltopdf` modify the `WKHTMLTOPDF_PATH` environment variable in the `.env` file: |
74 | | - |
75 | | - ``` |
76 | | - WKHTMLTOPDF_PATH=/usr/local/bin/wkhtmltopdf # Change this! :) |
77 | | - ``` |
78 | | -
|
79 | | -## Extension points |
80 | | -
|
81 | | -Refund Plugin is strongly based on both commands and events. Let's take RefundUnitsAction as an example. The whole |
82 | | -process consists of following steps: |
83 | | - |
84 | | -* Getting data from request |
85 | | -* Create a Command and fill it with data |
86 | | -* Dispatch Command |
87 | | -* Handle Command |
88 | | -* Fire Event |
89 | | -* Catch Event in Listener class |
90 | | - |
91 | | -Using command pattern and events make each step independent which means that providing custom implementation of given |
92 | | -part of refunding process doesn't affect any other step. |
93 | | -
|
94 | | -Apart from Events and Commands Refund Plugin is also based on mechanisms derived from core Sylius bundles such as: |
95 | | -
|
96 | | -* [Resources](https://docs.sylius.com/en/1.2/components_and_bundles/components/Resource/index.html) |
97 | | -* [Grids](https://docs.sylius.com/en/1.2/components_and_bundles/bundles/SyliusGridBundle/index.html) |
98 | | -* [State Machine](https://docs.sylius.com/en/1.2/book/architecture/state_machine.html) |
99 | | -
|
100 | | -Configuration of all elements mentioned above can be found and customized in `config.yml` file. |
101 | | -
|
102 | | -## Payment requirements |
103 | | -
|
104 | | -By default to refund your order, you need to have at least one available payment method configured with `offline` gateway. |
105 | | -In case your custom refund logic allows a different type of gateway (for example `stripe`), you should modify the specific parameter, |
106 | | -as shown below: |
107 | | -
|
108 | | -```yaml |
109 | | -# config/services.yaml |
110 | | - |
111 | | -parameters: |
112 | | - sylius_refund.supported_gateways: |
113 | | - - offline |
114 | | - - stripe |
115 | | -``` |
116 | | -
|
117 | | -Online refund logic should be implemented if you need it. |
118 | | -As the first try for the possible customization, you can check out `Sylius\RefundPlugin\Event\UnitsRefunded` event. |
119 | | -
|
120 | | -## Post-refunding process |
121 | | -
|
122 | | -After units are refunded, there are multiple other processes that should be triggered. By default, after units refund, there should be **CreditMemo** and |
123 | | -**RefundPayment** generated. As they're strictly coupled with each other, **RefundPayment** is always created after the **CreditMemo**. Moreover, if **RefundPayment** |
124 | | -fails, related **CreditMemo** should not be created as well. |
125 | | - |
126 | | -`Sylius\RefundPlugin\ProcessManager\UnitsRefundedProcessManager` service facilitates the whole process. If you want to add one or more steps to it, you should create |
127 | | -a service implementing `Sylius\RefundPlugin\ProcessManager\UnitsRefundedProcessStepInterface`, and register if with proper tag: |
128 | | - |
129 | | -```yaml |
130 | | -App\ProcessManager\CustomAfterRefundProcessManager: |
131 | | - tags: |
132 | | - - { name: sylius_refund.units_refunded.process_step, priority: 0 } |
133 | | -``` |
| 26 | +## Security issues |
134 | 27 |
|
135 | | -Tagged services would be executed according to their priority (descending). |
| 28 | +If you think that you have found a security issue, please do not use the issue tracker and do not post it publicly. |
| 29 | +Instead, all security issues must be sent to `security@sylius.com`. |
136 | 30 |
|
137 | | -## Supported branches |
| 31 | +## Community |
138 | 32 |
|
139 | | -* `1.4` (v1.4.*) - security fixes |
140 | | -* `1.5` (v1.5.*) - bug fixes, improvements |
141 | | -* `1.6` (v1.6.*) - new features |
142 | | -* `2.0` (v2.0.*) - new features, removing deprecations, BC breaks |
| 33 | +For online communication, we invite you to chat with us and other users on [Sylius Slack](https://sylius.com/slack). |
143 | 34 |
|
144 | | -## Security issues |
| 35 | +## License |
145 | 36 |
|
146 | | -If you think that you have found a security issue, please do not use the issue tracker and do not post it publicly. |
147 | | -Instead, all security issues must be sent to `security@sylius.com`. |
| 37 | +This plugin is released under the [MIT License](LICENSE). |
0 commit comments