Merge pull request #18 from BitBagCommerce/OP-522

OP-522 - installation.md - new standard

.github/workflows/build.yml

@@ -138,7 +138,7 @@ jobs:
                 run: vendor/bin/behat --colors --strict -vvv --no-interaction || vendor/bin/behat --colors --strict -vvv --no-interaction --rerun
 
             -   name: Upload Behat logs
-                uses: actions/upload-artifact@v2
+                uses: actions/upload-artifact@v3
                 if: failure()
                 with:
                     name: Behat logs

README.md

@@ -51,129 +51,23 @@ All main functionalities of the plugin are described [here.](https://github.com/
 
 ## Installation
 
-***
-
-1. Add the plugin to your project using:
-
-```bash
-$ composer require bitbag/agreement-plugin --no-scripts
-```
-
-2. Add plugin dependencies to your config/bundles.php file:
-
-```php
-return [
-    ...
-
-    BitBag\SyliusAgreementPlugin\BitBagSyliusAgreementPlugin::class => ['all' => true],
-];
-```
-
-3. Import routing in your `config/routes.yaml` file:
-```yaml
-
-# config/routes.yaml
-...
-
-bitbag_sylius_agreement_plugin:
-  resource: "@BitBagSyliusAgreementPlugin/Resources/config/routing.yml"
-```
-
-4. Import required config in your `config/packages/_sylius.yaml` file:
-```yaml
-# config/packages/_sylius.yaml
-
-imports:
-    ...
-    
-    - { resource: "@BitBagSyliusAgreementPlugin/Resources/config/config.yaml" }
-```
-
-5. Extend Customer entity:
-```php
-<?php
-
-declare(strict_types=1);
-
-namespace App\Entity\Customer;
-
-use BitBag\SyliusAgreementPlugin\Entity\Agreement\AgreementsRequiredTrait;
-use Tests\BitBag\SyliusAgreementPlugin\Entity\Customer\Customer as BaseCustomer;
-
-class Customer extends BaseCustomer implements CustomerInterface
-{
-    use AgreementsRequiredTrait;
-}
-```
-
-```php
-<?php
-
-namespace App\Entity\Customer;
-
-use Tests\BitBag\SyliusAgreementPlugin\Entity\Customer\CustomerInterface as BaseCustomerInterface;
-
-interface CustomerInterface extends BaseCustomerInterface
-{
-}
-```
-
-6. Update database schema:
-##### Check for queries to execute
-```
-bin/console doctrine:schema:update --dump-sql
-```
-##### Execute database update
-```
-bin/console doctrine:schema:update --force
-```
-
-## Usage
-
-***
-
-1.Find a form/forms where you want to add agreements and set it in your config.yaml file, for example:
-```yaml
-bit_bag_sylius_agreement:
-    contexts:
-        registration_form:
-            - Sylius\Bundle\CoreBundle\Form\Type\Customer\CustomerRegistrationType
-        checkout_form:
-            - Sylius\Bundle\CoreBundle\Form\Type\Checkout\AddressType
-```
-
-2.Find an entity which is used in your form and add trait to that class:
-```php
-use AgreementsRequiredTrait;
-```
-
-3.In the admin panel, create a new agreement and select context to it according to the configuration in the config.yaml file.
+---
+### Requirements
 
-4.[Overwrite](https://symfony.com/doc/3.4/templating/overriding.html) templates used by yours extended form by adding:
+We work on stable, supported and up-to-date versions of packages. We recommend you to do the same.
 
-````twig
-{% for agreement in form.agreements %}
-    {{ form_row(agreement.approved) }}
-{% endfor %}
-````
-Examples are in the package you have downloaded under the path [tests/Application/templates/bundles/*](/tests/Application/templates/bundles/)
+| Package       | Version         |
+|---------------|-----------------|
+| PHP           | \>= 8.1         |
+| sylius/sylius | 1.12.x - 1.13.x |
+| MySQL         | \>= 5.7         |
+| NodeJS        | \>= 14.x        |
 
-## Testing
+----
 
-***
+### Full installation guide
+- [See the full installation guide](doc/installation.md)
 
-```bash
-$ composer install
-$ cd tests/Application
-$ yarn install
-$ yarn build
-$ bin/console doctrine:database:create --env=test 
-$ bin/console doctrine:schema:create --env=test
-$ bin/console sylius:fixtures:load --env=test
-$ APP_ENV=test symfony server:start --dir=public/
-$ cd ../..
-$ vendor/bin/behat
-```
 
 # About us
 

doc/installation.md

@@ -0,0 +1,176 @@
+# Installation
+
+## Overview:
+GENERAL
+- [Requirements](#requirements)
+- [Composer](#composer)
+- [Basic configuration](#basic-configuration)
+- [Usage](#usage)
+--- 
+BACKEND
+- [Entities](#entities)
+    - [Attribute mapping](#attribute-mapping)
+    - [XML mapping](#xml-mapping)
+---
+FRONTEND
+- [Templates](#templates)
+---
+ADDITIONAL
+- [Tests](#tests)
+- [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.1         |
+| sylius/sylius | 1.12.x - 1.13.x |
+| MySQL         | \>= 5.7         |
+| NodeJS        | \>= 14.x        |
+
+## Composer:
+```bash
+composer require bitbag/agreement-plugin --no-scripts
+```
+
+## Basic configuration:
+Add plugin dependencies to your `config/bundles.php` file:
+
+```php
+# config/bundles.php
+
+return [
+    ...
+    BitBag\SyliusAgreementPlugin\BitBagSyliusAgreementPlugin::class => ['all' => true],
+];
+```
+
+Import required config in your `config/packages/_sylius.yaml` file:
+
+```yaml
+# config/packages/_sylius.yaml
+
+imports:
+    ...
+    - { resource: "@BitBagSyliusAgreementPlugin/Resources/config/config.yaml" }
+```
+
+Add routing to your `config/routes.yaml` file:
+```yaml
+# config/routes.yaml
+
+bitbag_sylius_agreement_plugin:
+    resource: "@BitBagSyliusAgreementPlugin/Resources/config/routing.yml"
+```
+
+## Usage
+
+### The following procedure is not fixed for all the functionalities the plugin offers.
+- In other words, depending on where you want the agreement checkbox to appear, you need to extend other entities and make other configuration changes.
+
+- The configuration for the `registration form` has already been added:
+```
+vendor/bitbag/agreement-plugin/src/Resources/config/config.yaml
+```
+
+#### You can extend or change it in the `config/_sylius.yaml` file, for example.
+- example for the configuration of the following form:
+```yaml
+bit_bag_sylius_agreement:
+    contexts:
+        checkout_form:
+            - Sylius\Bundle\CoreBundle\Form\Type\Checkout\AddressType
+```
+
+Add a translation for the new form, e.g. in `translations/messages.en.yaml`:
+```yaml
+bitbag_sylius_agreement_plugin:
+    ui:
+        agreement:
+            contexts:
+                checkout_form: Checkout form
+```
+
+### Clear application cache by using command:
+```bash
+bin/console cache:clear
+```
+---
+### `In the admin panel, create a new agreement and select context.`
+---
+
+## Entities
+### Example for the agreement checkbox on the `registration form`.
+- Before you start extending entities, first determine what entity the form uses (in this case - `Customer`). Then add to the entity:
+```php
+use AgreementsRequiredTrait;
+```
+...and interfaces.
+
+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
+To add the agreement checkbox to the registration form, you need to add following code to the template with form:
+```php
+{% for agreement in form.agreements %}
+    {{ form_row(agreement.approved) }}
+{% endfor %}
+```
+
+For `registration form` you can copy the template from the plugin:
+
+**ShopBundle** (`templates/bundles/SyliusShopBundle`):
+```
+vendor/bitbag/agreement-plugin/tests/Application/templates/bundles/SyliusShopBundle/Register/_form.html.twig
+```
+
+## Tests
+To run the tests, execute the commands:
+```bash
+composer install
+cd tests/Application
+yarn install
+yarn build
+bin/console doctrine:database:create --env=test
+bin/console doctrine:schema:create --env=test
+bin/console sylius:fixtures:load --env=test
+APP_ENV=test symfony server:start --dir=public/
+cd ../..
+vendor/bin/behat
+```
+
+## Known issues
+### Translations not displaying correctly
+For incorrectly displayed translations, execute the command:
+```bash
+bin/console cache:clear
+```
+

doc/installation/attribute-mapping.md

@@ -0,0 +1,45 @@
+# Attribute-mapping
+
+Check the mapping settings in `config/packages/doctrine.yaml` and, if necessary, change them accordingly.
+```yaml
+doctrine:
+    ...
+    orm:
+        entity_managers:
+            default:
+                ...
+                mappings:
+                    App:
+                        ...
+                        type: attribute
+```
+
+Extend entities with parameters and methods using attributes and traits:
+
+- `Customer` entity:
+
+```php
+<?php
+// src/Entity/Customer/Customer.php
+
+declare(strict_types=1);
+
+namespace App\Entity\Customer;
+
+use BitBag\SyliusAgreementPlugin\Entity\Agreement\AgreementsRequiredInterface;
+use BitBag\SyliusAgreementPlugin\Entity\Agreement\AgreementsRequiredTrait;
+use Doctrine\ORM\Mapping as ORM;
+use Sylius\Component\Core\Model\Customer as BaseCustomer;
+use Sylius\Component\Core\Model\CustomerInterface as BaseCustomerInterface;
+
+/**
+ * @ORM\Entity
+ * @ORM\Table(name="sylius_customer")
+ */
+#[ORM\Entity]
+#[ORM\Table(name: 'sylius_customer')]
+class Customer extends BaseCustomer implements BaseCustomerInterface, AgreementsRequiredInterface
+{
+    use AgreementsRequiredTrait;
+}
+```