From aaf494436cc99f1dc01dc4ae92f7ebcb6a58d38a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Kali=C5=84ski?= Date: Fri, 30 Aug 2024 15:38:17 +0200 Subject: [PATCH] OP-503 - installation.md has been updated --- composer.json | 3 +- doc/installation.md | 133 +++++++++++++++++++++++++++++--------------- 2 files changed, 89 insertions(+), 47 deletions(-) diff --git a/composer.json b/composer.json index 7787e2f..a9e5f06 100644 --- a/composer.json +++ b/composer.json @@ -39,7 +39,8 @@ "bitbag/coding-standard": "^1.0.0 || ^2.0.0" }, "conflict": { - "doctrine/orm": ">=2.15.2" + "doctrine/orm": ">=2.15.2", + "doctrine/persistence": "<3.0" }, "prefer-stable": true, "autoload": { diff --git a/doc/installation.md b/doc/installation.md index 9508a37..4f311c8 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -1,21 +1,50 @@ - -## Installation - -Please require plugin by running composer command: - +# Installation + +## Overview: +GENERAL +- [Requirements](#requirements) +- [Composer](#composer) +- [Basic configuration](#basic-configuration) +--- +FRONTEND +- [Templates](#templates) +- [Webpack](#webpack) +--- +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.1 | +| sylius/sylius | 1.12.x - 1.13.x | +| MySQL | \>= 5.7 | +| NodeJS | \>= 18.x | + +## Composer: ```bash -$ composer require bitbag/mailchimp-plugin --no-scripts +composer require bitbag/mailchimp-plugin --no-scripts ``` +## Basic configuration: Add plugin dependencies to your `config/bundles.php` file: + ```php +# config/bundles.php + return [ ... BitBag\SyliusMailChimpPlugin\BitBagSyliusMailChimpPlugin::class => ['all' => true], ]; ``` -Import routing **on top** of your `config/routes.yaml` file: +Import routing in your `config/routes.yaml` file +(may have already been added in the `config/routes/bitbag_sylius_mailchimp_plugin.yaml` file): + ```yaml # config/routes.yaml @@ -23,6 +52,16 @@ bitbag_sylius_mailchimp_plugin: resource: "@BitBagSyliusMailChimpPlugin/Resources/config/routing.yml" ``` +Add the parameters listed below to your `config/packages/_sylius.yaml` file: +```yaml +# config/packages/_sylius.yaml + +parameters: + mailchimp.api_key: '%env(resolve:MAIL_CHIMP_API_KEY)%' + mailchimp.list_id: '%env(resolve:MAIL_CHIMP_LIST_ID)%' + mailchimp.webhook_secret: '%env(resolve:MAIL_CHIMP_WEBHOOK_SECRET)%' +``` + Add plugin parameters to your `config/services.yaml` file: ```yaml # config/services.yaml @@ -34,67 +73,67 @@ parameters: mailchimp.webhook_secret: '%env(resolve:MAIL_CHIMP_WEBHOOK_SECRET)%' ``` -Configure MailChimp credentials +### Configure MailChimp credentials: -To get info about list id: -https://mailchimp.com/developer/marketing/api/lists/get-lists-info/ +To get info about list id: https://mailchimp.com/developer/marketing/api/lists/get-lists-info/ - -```yaml +```dotenv # .env.local -// ... - +... MAIL_CHIMP_API_KEY=YOUR_KEY MAIL_CHIMP_LIST_ID=YOUR_LIST_ID MAIL_CHIMP_WEBHOOK_SECRET=QUERY_PARAMETER_FOR_UNSUBSCRIBED_WEBHHOOK ``` -[Read more about MAIL_CHIMP_WEBHOOK_SECRET](mailchimp_webhook.md) +- [Read more about MAIL_CHIMP_WEBHOOK_SECRET](https://github.com/BitBagCommerce/SyliusMailChimpPlugin/blob/master/doc/mailchimp_webhook.md) You can read more about Mailchimp webhooks here: https://mailchimp.com/developer/marketing/guides/sync-audience-data-webhooks/ -Add the parameters listed below to your `config/packages/_sylius.yaml` file: - +### Clear application cache by using command: +```bash +bin/console cache:clear ``` -parameters: - mailchimp.api_key: '%env(resolve:MAIL_CHIMP_API_KEY)%' - mailchimp.list_id: '%env(resolve:MAIL_CHIMP_LIST_ID)%' - mailchimp.webhook_secret: '%env(resolve:MAIL_CHIMP_WEBHOOK_SECRET)%' +**Note:** If you are running it on production, add the `-e prod` flag to this command. + + +## Templates +Include the newsletter in your template: +```php +{# templates location: templates/bundles/SyliusShopBundle/ #} + +{% include '@BitBagSyliusMailChimpPlugin/_subscribe.html.twig' %} ``` -Import plugin's `webpack.config.js` file +## Webpack +### Webpack.config.js +Please setup your `webpack.config.js` file to require the plugin's webpack configuration. To do so, please put the line below somewhere on top of your webpack.config.js file: ```js -// webpack.config.js const [bitbagMailChimp] = require('./vendor/bitbag/mailchimp-plugin/webpack.config.js'); -... - +``` +As next step, please add the imported consts into final module exports: +```js module.exports = [..., bitbagMailChimp]; ``` -Configure config/packages/webpack_encore.yaml -.yaml +### Webpack Encore +Add the webpack configuration into `config/packages/webpack_encore.yaml`: + ```yaml webpack_encore: + output_path: '%kernel.project_dir%/public/build/default' builds: - // ... - shop: '%kernel.project_dir%/public/build/shop' - admin: '%kernel.project_dir%/public/build/admin' + ... mail-chimp-shop: '%kernel.project_dir%/public/build/bitbag/mail-chimp/shop' ``` -Include the newsletter in your template: -```twig -{# templates location: templates/bundles/SyliusShopBundle/ #} - -{% include '@BitBagSyliusMailChimpPlugin/_subscribe.html.twig' %} -``` - -Add these javascripts to the layout template that includes your subscription form imported in the previous steps -```html - +### Encore functions +Add encore functions to your templates: +SyliusShopBundle: +```php +{# @SyliusShopBundle/_scripts.html.twig #} {{ encore_entry_script_tags('bitbag-mail-chimp-shop', null, 'mail-chimp-shop') }} ``` -Clear project cache: -```php -bin/console cache:clear # if there is an issue with translations displaying correctly, clear the cache again. +### Run commands +```bash +yarn install +yarn encore dev # or prod, depends on your environment ``` -Update your webpack build: - +## Known issues +### Translations not displaying correctly +For incorrectly displayed translations, execute the command: ```bash -yarn encore dev # or yarn encore prod, when you build production environment +bin/console cache:clear ```