> ## Documentation Index
> Fetch the complete documentation index at: https://partner-integrations.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

The Magento 2 extension for Engage is developed in PHP. These are the steps to install it.

## Installation

Add this repository to your composer:

```bash theme={null}
composer config repositories.voyado composer 
https://gitlab.com/api/v4/group/11993948/-/packages/composer/
```

Then add this to use the magento2 module:

```bash theme={null}
composer require voyado/magento2
```

## Development

The module has quality assurance scripts in place. To activate them, run:

```bash theme={null}
composer install
```

Use composer 2 and PHP 7.4.

You'll be asked for Magento credentials. It's best to use those for Magento Enterprise. Don't store them as they are needed just once.

You'll also need a GitLab token. Create an "auth.json" file with it as follows:

```json theme={null}
{
    "gitlab-token": {
        "gitlab.com": "generate-this-in-your-gitlab-account"
    }
}
```

When changes are committed, GrumPHP will now perform some checks.

## Flows

See PlantUML flows in src/doc.

## Extending

The module can be extended to, for example, allow more data to be sent to Engage in the order receipt. To do this, replace "\[Vendor]" in the four examples below with your own vendor name and add these files to the paths shown:

<AccordionGroup>
  <Accordion title="app/code/[Vendor]/ExtendedVoyado/registration.php">
    ```php theme={null}
    <?php
    \Magento\Framework\Component\ComponentRegistrar::register(
        \Magento\Framework\Component\ComponentRegistrar::MODULE,
        '[Vendor]_ExtendedVoyado',
        __DIR__
    );
    ```
  </Accordion>

  <Accordion title="app/code/[Vendor]/ExtendedVoyado/etc/module.xml">
    ```xml theme={null}
    <?xml version="1.0"?>
    <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">

        <module name="[Vendor]_ExtendedVoyado" setup_version="1.0.0">
            <sequence>
                <module name="Voyado_Magento2" />
            </sequence>
        </module>
    </config>
    ```
  </Accordion>

  <Accordion title="app/code/[Vendor]/ExtendedVoyado/etc/di.xml">
    ```xml theme={null}
    <?xml version="1.0"?>
    <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
        <type name="Voyado\Magento2\Helper\VoyadoHelper">
            <plugin name="[Vendor]ExtendedVoyado_Plugin_AddOwnAttributeToOrderItem"
                    type="[Vendor]ExtendedVoyado\Plugin\AddOwnAttributeToOrderItem" />
        </type>
    </config>
    ```
  </Accordion>

  <Accordion title="app/code/[Vendor]/ExtendedVoyado/Plugin/AddOwnAttributeToOrderItem.php">
    ```php theme={null}
    <?php

    namespace [Vendor]\ExtendedVoyado\Plugin;

    use Voyado\Magento2\Helper\VoyadoHelper;

    class AddOwnAttributeToOrderItem
    {
        /**
         * @param VoyadoHelper $object
         * @param array $result
         * @param mixed $orderItem
         * @return array
         */
        public function afterGetExtraDataForItem(VoyadoHelper $object, $result, $orderItem)
        {
            if ($orderItem->getProduct() !== null) {
                if ($orderItem->getProduct()->getTypeId() === 'simple') {
                    if ($orderItem->getProduct()->getAttributeText('my_own_attribute') !== false) {
                        $result['my_own_attribute'] = $orderItem->getProduct()->getAttributeText('my_own_attribute');
                    }
                } elseif ($orderItem->getProduct()->getTypeId() === 'configurable') {
                    $options = $orderItem->getProductOptions();
                    if (isset($options['attributes_info'])) {
                        foreach ($options['attributes_info'] as $option) {
                            if ($option['label'] === 'My Own Attribute Label') {
                                $result['my_own_attribute'] = $option['value'];
                                break;
                            }
                        }
                    }
                }
            }
            return $result;
        }

        /**
         * @param VoyadoHelper $object
         * @param array $result
         * @param mixed $orderItem
         * @return array
         */
        public function afterGetExtraDataForReceiptItem(VoyadoHelper $object, $result, $orderItem)
        {
            if ($orderItem->getProduct() !== null) {
                if ($orderItem->getProduct()->getTypeId() === 'simple') {
                    if ($orderItem->getProduct()->getAttributeText('my_own_attribute') !== false) {
                        $result = [
                            [
                                'name' => 'my_own_attribute',
                                'value' => $orderItem->getProduct()->getAttributeText('my_own_attribute')
                            ]
                        ];
                    }
                } elseif ($orderItem->getProduct()->getTypeId() === 'configurable') {
                    $options = $orderItem->getProductOptions();
                    if (isset($options['attributes_info'])) {
                        foreach ($options['attributes_info'] as $option) {
                            if ($option['label'] === 'My Own Attribute Label') {
                                $result = [
                                    [
                                        'name' => 'my_own_attribute',
                                        'value' => $option['value']
                                    ]
                                ];
                                break;
                            }
                        }
                    }
                }
            }
            return $result;
        }
    }
    ```
  </Accordion>
</AccordionGroup>

<Warning>
  When adding custom functionality to this extension, make sure to create your own plugin. Otherwise, you may interfere with the existing code and risk breaking it.
</Warning>

## Consents

Add consents for contacts by creating two plugins:

* `afterGetConsents` for class "Voyado\Magento2\Helper\ContactAttributesHelper"
* `afterGetConsents` for class "Voyado\Magento2\Helper\OrderBodyHelper"

For `addOrder` and `creditMemo`, the function will receive "true" for the argument fromOrder.

The method `getConsents` can be found in the class "Voyado\Magento2\Helper\VoyadoHelper" and only returns an empty array.

Per index, an array should be added with these keys (the values are examples):

```cs theme={null}
[
    "id" => "consentGeneralTerms",
    "value" => true,
    "date" => "2021-03-15T16:32:42+01:00",
    "source" => "string",
    "comment" => "string"
]
```