OP-513 - installation.md has been updated

doc/installation.md

@@ -1,85 +1,117 @@
-
-1. Require plugin with composer:
-
-    ```bash
-    composer require bitbag/bonus-points-plugin
-    ```
-
-1. Add plugin dependencies to your `config/bundles.php` file:
-
-    ```php
-        return [
-         ...
-        
-            BitBag\SyliusBonusPointsPlugin\BitBagSyliusBonusPointsPlugin::class => ['all' => true],
-        ];
-    ```
-
-1. Import resource in your `config/packages/_sylius.yaml`
-
-    ```yaml
-    # config/packages/_sylius.yaml
-    
-    imports:
+# Installation
+
+## Overview:
+GENERAL
+- [Requirements](#requirements)
+- [Composer](#composer)
+- [Basic configuration](#basic-configuration)
+--- 
+BACKEND
+- [Entities](#entities)
+    - [Attribute mapping](#attribute-mapping)
+    - [XML mapping](#xml-mapping)
+---
+FRONTEND
+- [Templates](#templates)
+---
+ADDITIONAL
+- [Additional configuration](#additional-configuration)
+- [Known Issues](#known-issues)
+---
+
+## Requirements:
+We work on stable, supported and up-to-date versions of packages. We recommend you to do the same.
+
+| Package       | Version         |
+|---------------|-----------------|
+| PHP           | \>8.0           |
+| sylius/sylius | 1.12.x - 1.13.x |
+| MySQL         | \>= 5.7         |
+| NodeJS        | \>= 18.x        |
+
+## Composer:
+```bash
+composer require bitbag/bonus-points-plugin
+```
+
+## Basic configuration:
+Add plugin dependencies to your `config/bundles.php` file:
+
+```php
+# config/bundles.php
+
+return [
     ...
-   
-       - { resource: "@BitBagSyliusBonusPointsPlugin/Resources/config/config.yml" }
-    ```    
-
-1. Import routing in your `config/routes.yaml` file:
-
-    ```yaml
-    
-    # config/routes.yaml
-    ...
-    
-    bitbag_sylius_bonus_points_plugin:
-        resource: "@BitBagSyliusBonusPointsPlugin/Resources/config/routing.yml"
-    ```
-
-1. Extend `Order`(including Doctrine mapping):
+    BitBag\SyliusBonusPointsPlugin\BitBagSyliusBonusPointsPlugin::class => ['all' => true],
+];
+```
 
-    ```php
-    <?php 
-   
-   <?php
+Import required config in your `config/packages/_sylius.yaml` file:
 
-    declare(strict_types=1);
-
-    namespace App\Entity\Order;
-
-    use BitBag\SyliusBonusPointsPlugin\Entity\BonusPointsAwareInterface;
-    use Doctrine\ORM\Mapping as ORM;
-    use Sylius\Component\Core\Model\Order as BaseOrder;
-
-    /**
-     * @ORM\Entity
-     * @ORM\Table(name="sylius_order")
-     */
-     #[ORM\Entity]
-     #[ORM\Table(name: 'sylius_order')]
-     class Order extends BaseOrder implements BonusPointsAwareInterface
-     {
-         #[ORM\Column(type: 'integer', nullable: true)]
-         protected ?int $bonusPoints = null;
-
-         public function getBonusPoints(): ?int
-         {
-            return $this->bonusPoints;
-         }
-
-         public function setBonusPoints(?int $bonusPoints): void
-         {
-            $this->bonusPoints = $bonusPoints;
-         }
-     }
-
-1. Customize shop templates to include bonus points. For starter You may want copy to templates directory everything from plugin's tests/Application/templates
-
-1. Finish the installation by updating the database schema and installing assets:
-
-    ```
-    $ bin/console doctrine:migrations:diff
-    $ bin/console doctrine:migrations:migrate
-    ```
+```yaml
+# config/packages/_sylius.yaml
 
+imports:
+    ...
+    - { resource: "@BitBagSyliusBonusPointsPlugin/Resources/config/config.yml" }
+```
+
+Import routing in your `config/routes.yaml` file:
+```yaml
+# config/routes.yaml
+
+bitbag_sylius_bonus_points_plugin:
+    resource: "@BitBagSyliusBonusPointsPlugin/Resources/config/routing.yml"
+```
+
+## Entities
+You can implement entity configuration by using both xml-mapping and attribute-mapping. Depending on your preference, choose either one or the other:
+### Attribute mapping
+- [Attribute mapping configuration](installation/attribute-mapping.md)
+### XML mapping
+- [XML mapping configuration](installation/xml-mapping.md)
+
+### Update your database
+First, please run legacy-versioned migrations by using command:
+```bash
+bin/console doctrine:migrations:migrate
+```
+
+After migration, please create a new diff migration and update database:
+```bash
+bin/console doctrine:migrations:diff
+bin/console doctrine:migrations:migrate
+```
+**Note:** If you are running it on production, add the `-e prod` flag to this command.
+
+### Clear application cache by using command:
+```bash
+bin/console cache:clear
+```
+**Note:** If you are running it on production, add the `-e prod` flag to this command.
+
+## Templates
+Copy required templates into correct directories in your project.
+
+**AdminBundle** (`templates/bundles/SyliusAdminBundle`):
+```
+vendor/bitbag/bonus-points-plugin/tests/Application/templates/bundles/SyliusAdminBundle/Order/Show/Summary/_totals.html.twig
+```
+
+**ShopBundle** (`templates/bundles/SyliusShopBundle`):
+```
+vendor/bitbag/bonus-points-plugin/tests/Application/templates/bundles/SyliusShopBundle/Cart/Summary/_items.html.twig
+vendor/bitbag/bonus-points-plugin/tests/Application/templates/bundles/SyliusShopBundle/Cart/Summary/_totals.html.twig
+vendor/bitbag/bonus-points-plugin/tests/Application/templates/bundles/SyliusShopBundle/Common/Order/Table/_totals.html.twig
+```
+
+## Known issues
+### Translations not displaying correctly
+For incorrectly displayed translations, execute the command:
+```bash
+bin/console cache:clear
+```
+### Bonus points are not charged
+- When configuring the rules for accruing bonus points, select those categories to which the items are assigned directly.
+
+- If you want the points to be credited for each item, select all available categories.

doc/installation/attribute-mapping.md

@@ -0,0 +1,42 @@
+# Attribute-mapping
+
+Check the mapping settings in `config/packages/doctrine.yaml` and, if necessary, change them accordingly.
+```yaml
+doctrine:
+    ...
+    orm:
+        ...
+        mappings:
+            App:
+                ...
+                type: attribute
+```
+
+Extend entities with parameters and methods using attributes and traits:
+```php
+<?php
+// src/Entity/Order/Order.php
+
+declare(strict_types=1);
+
+namespace App\Entity\Order;
+
+use BitBag\SyliusBonusPointsPlugin\Entity\BonusPointsAwareInterface;
+use BitBag\SyliusBonusPointsPlugin\Entity\BonusPointsAwareTrait;
+use Doctrine\ORM\Mapping as ORM;
+use Sylius\Component\Core\Model\Order as BaseOrder;
+
+/**
+ * @ORM\Entity
+ * @ORM\Table(name="sylius_order")
+ */
+ #[ORM\Entity]
+ #[ORM\Table(name: 'sylius_order')]
+ class Order extends BaseOrder implements BonusPointsAwareInterface
+ {
+     use BonusPointsAwareTrait;
+
+     #[ORM\Column(type: 'integer', nullable: true)]
+     protected ?int $bonusPoints = null;
+ }
+```

doc/installation/xml-mapping.md

@@ -0,0 +1,60 @@
+# XML-mapping
+
+Check the mapping settings in `config/packages/doctrine.yaml` and, if necessary, change them accordingly.
+```yaml
+doctrine:
+    ...
+    orm:
+        ...
+        mappings:
+            App:
+                ...
+                type: xml
+                dir: '%kernel.project_dir%/src/Resources/config/doctrine'
+```
+
+Extend entities with parameters and methods using attributes and traits:
+
+```php
+<?php
+// src/Entity/Order.php
+
+declare(strict_types=1);
+
+namespace App\Entity\Order;
+
+use BitBag\SyliusBonusPointsPlugin\Entity\BonusPointsAwareInterface;
+use BitBag\SyliusBonusPointsPlugin\Entity\BonusPointsAwareTrait;
+use Sylius\Component\Core\Model\Order as BaseOrder;
+
+ class Order extends BaseOrder implements BonusPointsAwareInterface
+ {
+    use BonusPointsAwareTrait;
+ }
+```
+
+Define new Entity mapping inside `src/Resources/config/doctrine` directory.
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+
+<doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                  xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                            http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd"
+>
+    <entity name="App\Entity\Order" table="sylius_order">
+    </entity>
+</doctrine-mapping>
+```
+
+Override `config/packages/_sylius.yaml` configuration:
+```yaml
+# config/_sylius.yaml
+
+sylius_order:
+    resources:
+        order:
+            classes:
+                model: App\Entity\Order
+
+```