From 418f6566a82c1d12a108902c6529c6d9e6dfb187 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Kali=C5=84ski?= Date: Tue, 10 Sep 2024 14:40:16 +0200 Subject: [PATCH] OP-532 - installation.md and build.yml has been changed --- .github/workflows/build.yml | 18 +- README.md | 25 +-- composer.json | 2 +- doc/installation.md | 383 ++++++++++++++++++++---------------- 4 files changed, 238 insertions(+), 190 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 60fb364..d0a79a6 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -23,15 +23,19 @@ jobs: matrix: php: [ "8.0", "8.1", "8.2", "8.3" ] symfony: ["^5.4", "^6.0"] - sylius: ["^1.12", "^1.13"] + sylius: ["~1.12.0", "~1.13.0"] node: [ "18.x", "20.x" ] mysql: ["8.0"] exclude: - - sylius: ^1.13 - php: 8.0 - - sylius: ^1.12 - php: 8.0 - symfony: ^6.4 + - sylius: "~1.13.0" + php: "8.0" + - sylius: "~1.12.0" + php: "8.0" + symfony: "^6.4" + - sylius: "~1.12.0" + php: "8.3" + symfony: "^6.0" + env: APP_ENV: test DATABASE_URL: "mysql://root:root@127.0.0.1/sylius?serverVersion=${{ matrix.mysql }}" @@ -177,7 +181,7 @@ jobs: - name: Upload Behat logs - uses: actions/upload-artifact@v2 + uses: actions/upload-artifact@v3 if: failure() with: name: Behat logs diff --git a/README.md b/README.md index 56eaef1..2a5dc1e 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,8 @@ At BitBag we do believe in open source. However, we are able to do it just becau * [Support](#we-are-here-to-help) * [Installation](#installation) * [Requirements](#requirements) - * [Usage](#usage) - * [Configuration](#configuration) +* [Usage](#usage) +* [Configuration](#configuration) * [About us](#about-us) * [Community](#community) * [Additional Sylius resources for developers](#additional-resources-for-developers) @@ -41,21 +41,24 @@ This **open-source plugin was developed to help the Sylius community** and make [![](https://bitbag.io/wp-content/uploads/2020/10/button-contact.png)](https://bitbag.io/contact-us/?utm_source=github&utm_medium=referral&utm_campaign=plugins_ing) -# Installation ----- +## Installation +--- ### Requirements -We work on stable, supported, and up-to-date versions of packages. We recommend you do the same. +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/refund-plugin | ^1.0.0 | +| sylius/sylius | ~1.12.x or ~1.13.x | -| Package | Version | -|----------------------|----------------| -| PHP | ^8.0 | -| sylius/refund-plugin | ^1.0.0 | -| sylius/sylius | ~1.11 or ~1.12 | ---- -For the full installation guide please go to [installation](doc/installation.md) +### Full installation guide +- [See the full installation guide](doc/installation.md) + ### Usage diff --git a/composer.json b/composer.json index b14fdbc..6ea796e 100644 --- a/composer.json +++ b/composer.json @@ -7,7 +7,7 @@ "php": "^8.0", "ext-json": "*", "sylius/refund-plugin": "^1.0", - "sylius/sylius": "^1.12 || ^1.13", + "sylius/sylius": "~1.12.0 || ~1.13.0", "twig/extra-bundle": "^3.4", "symfony/webpack-encore-bundle": "^1.16" }, diff --git a/doc/installation.md b/doc/installation.md index 96f84d7..7eac86a 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -1,171 +1,212 @@ -## Installation - -### Sylius configuration - -1. The [Sylius Refund Plugin](https://github.com/Sylius/RefundPlugin) is our plugin dependency. Please complete [its installation steps](https://github.com/Sylius/RefundPlugin?tab=readme-ov-file#installation) before continuing. - - **Note.** After installation of the Refund plugin, please remove Refund configuration from your project. Imoje plugin already has this configuration and doubling it will cause and error. - -3. Require our plugin with composer: - - ```bash - composer require bitbag/sylius-imoje-plugin --no-scripts - ``` - - **Note.** If you receive an error related to `Twig\Extra\Intl\IntlExtension` class, please go to `config/packages/twig.yaml` file and remove the mentioned service definition. In some cases, multiple dependencies redefine the service, so it results the error message. After removing it, please run the composer command second time, to finish the step. - -4. Add plugin dependencies to your `config/bundles.php` file: - - ```php - return [ - ... - BitBag\SyliusImojePlugin\BitBagSyliusImojePlugin::class => ['all' => true], - ]; - ``` - -5. Import required config in your `config/packages/_sylius.yaml` file: - - ```yaml - # config/packages/_sylius.yaml - - imports: - ... - - { resource: "@BitBagSyliusImojePlugin/Resources/config.yaml" } - ``` - -6. Import the routing in your `config/routes.yaml` file: - - ```yaml - # config/routes.yaml - - bitbag_sylius_imoje_plugin: - resource: "@BitBagSyliusImojePlugin/Resources/config/routing.yaml" - ``` - -7. Add Imoje as a supported refund gateway in `config/packages/_sylius.yaml`: - - ```yaml - # config/packages/_sylius.yaml - - parameters: - sylius_refund.supported_gateways: - - offline - - bitbag_imoje - ``` - -8. Copy Sylius templates overridden by the plug-in to your templates directory (`templates/bundles/`): - - ``` - mkdir -p templates/bundles/SyliusAdminBundle/ - mkdir -p templates/bundles/SyliusShopBundle/ - - cp -R vendor/bitbag/sylius-imoje-plugin/tests/Application/templates/bundles/SyliusAdminBundle/* templates/bundles/SyliusAdminBundle/ - cp -R vendor/bitbag/sylius-imoje-plugin/tests/Application/templates/bundles/SyliusShopBundle/* templates/bundles/SyliusShopBundle/ - ``` - - **Note.** If you have overridden at least one template from the directories above, please adjust your code to include our changes. - -9. Add logging to your environment by editing your {dev, prod, staging}/monolog.yaml: - - ```yaml - monolog: - channels: ['imoje'] - handlers: - imoje: - type: stream - path: "%kernel.logs_dir%/%kernel.environment%_imoje.log" - level: debug - channels: [ 'imoje' ] - ``` - -10. Clear the cache: - - ```bash - $ bin/console cache:clear - ``` - -11. Install assets: - - ``` - $ bin/console assets:install - ``` - - **Note:** If you are running it on production, add the `-e prod` flag to this command. - -12. Synchronize the database: - - ``` - $ bin/console doctrine:migrations:migrate - ``` - -### Webpack configuration - -#### Installing Webpack package - -1. Before Webpack installation, please create the `config/packages/webpack_encore.yaml` file with a content of: - - ```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' - imoje_shop: '%kernel.project_dir%/public/build/bitbag/imoje/shop' - imoje_admin: '%kernel.project_dir%/public/build/bitbag/imoje/admin' - ``` - -2. To install Webpack in your application, please run the command below: - - ```bash - $ composer require "symfony/webpack-encore-bundle" - ``` - -3. After installation, please add the line below into `config/bundles.php` file: - - ```php - return [ - ... - Symfony\WebpackEncoreBundle\WebpackEncoreBundle::class => ['all' => true], - ]; - ``` - -#### Configuring Webpack - -By a standard, the `webpack.config.js` file should be available in your repository. If not, please use [the Sylius-Standard one](https://github.com/Sylius/Sylius-Standard/blob/1.11/webpack.config.js). - -1. 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: - - ```javascript - const [bitbagImojeShop, bitbagImojeAdmin] = require('./vendor/bitbag/sylius-imoje-plugin/webpack.config.js'); - ``` - -2. As next step, please add the imported consts into final module exports: - - ```javascripts - module.exports = [shopConfig, adminConfig, bitbagImojeShop, bitbagImojeAdmin]; - ``` - -3. Next thing is to add the asset configuration into `config/packages/framework.yaml`: - - ```yaml - framework: - assets: - packages: - shop: - json_manifest_path: '%kernel.project_dir%/public/build/shop/manifest.json' - admin: - json_manifest_path: '%kernel.project_dir%/public/build/admin/manifest.json' - imoje_shop: - json_manifest_path: '%kernel.project_dir%/public/build/bitbag/imoje/shop/manifest.json' - imoje_admin: - json_manifest_path: '%kernel.project_dir%/public/build/bitbag/imoje/admin/manifest.json' - ``` - -4. Additionally, please add the `"@symfony/webpack-encore": "^1.5.0",` dependency into your `package.json` file. - -5. Now you can run the commands: - - ```bash - $ yarn install - $ yarn encore dev # or prod, depends on your environment - ``` +# Installation + +## Overview: +GENERAL +- [Requirements](#requirements) +- [Dependencies](#dependencies) +- [Composer](#composer) +- [Basic configuration](#basic-configuration) +--- +FRONTEND +- [Templates](#templates) +- [Webpack](#webpack) +--- +ADDITIONAL +- [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/refund-plugin | ^1.0.0 | +| sylius/sylius | ~1.12.x or ~1.13.x | + +## Dependencies +### Refund Plugin +The [Sylius Refund Plugin](https://github.com/Sylius/RefundPlugin) is our plugin dependency. +Please complete [its installation steps](https://github.com/Sylius/RefundPlugin?tab=readme-ov-file#installation) before continuing. + +### IMPORTANT +> **Note:** After installation of the `RefundPlugin`, please remove Refund configuration from your project. +Imoje plugin already has this configuration and doubling it will cause and error. + +### To remove `RefundPlugin` configuration: +Remove `config/packages/sylius_refund.yaml` file if exists. + +## Composer: +```bash +composer require bitbag/sylius-imoje-plugin --no-scripts +``` + +## Basic configuration: +Add plugin dependencies to your `config/bundles.php` file: + +```php +# config/bundles.php + +return [ + ... + BitBag\SyliusImojePlugin\BitBagSyliusImojePlugin::class => ['all' => true], +]; +``` + +Import required config in your `config/packages/_sylius.yaml` file: + +```yaml +# config/packages/_sylius.yaml + +imports: + ... + - { resource: "@BitBagSyliusImojePlugin/Resources/config.yaml" } +``` + +Add `imoje` as a supported refund gateway in `config/packages/_sylius.yaml`: +```yaml +# config/packages/_sylius.yaml + + parameters: + sylius_refund.supported_gateways: + - offline + - bitbag_imoje +``` + +Add routing to your `config/routes.yaml` file: +```yaml +# config/routes.yaml + +bitbag_sylius_imoje_plugin: + resource: "@BitBagSyliusImojePlugin/Resources/config/routing.yaml" +``` + +Add logging to your environment by editing your `{dev, prod, staging}/monolog.yaml`: +```yaml +monolog: + channels: ['imoje'] + handlers: + imoje: + type: stream + path: "%kernel.logs_dir%/%kernel.environment%_imoje.log" + level: debug + channels: [ 'imoje' ] +``` + +### Clear application cache by using command: +```bash +bin/console cache:clear +``` + +### IMPORTANT +> **Note**: If you receive an error related to `Twig\Extra\Intl\IntlExtension` class, +please go to `config/packages/twig.yaml` file and remove the mentioned service definition. +In some cases, multiple dependencies redefine the service, so it results the error message. +After removing it, please run the composer command second time, to finish the step. + +### 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. + +## Templates +Copy required templates into correct directories in your project. + +**AdminBundle** (`templates/bundles/SyliusAdminBundle`): +``` +vendor/bitbag/sylius-imoje-plugin/tests/Application/templates/bundles/SyliusAdminBundle/Order/Show/_payment.html.twig +vendor/bitbag/sylius-imoje-plugin/tests/Application/templates/bundles/SyliusAdminBundle/Order/Show/_payments.html.twig +``` + +**ShopBundle** (`templates/bundles/SyliusShopBundle`): +``` +vendor/bitbag/sylius-imoje-plugin/tests/Application/templates/bundles/SyliusShopBundle/Checkout/Complete/_form.html.twig +vendor/bitbag/sylius-imoje-plugin/tests/Application/templates/bundles/SyliusShopBundle/Checkout/Complete/_navigation.html.twig +vendor/bitbag/sylius-imoje-plugin/tests/Application/templates/bundles/SyliusShopBundle/Checkout/complete.html.twig +vendor/bitbag/sylius-imoje-plugin/tests/Application/templates/bundles/SyliusShopBundle/Checkout/SelectPayment/_choiceImoje.html.twig +vendor/bitbag/sylius-imoje-plugin/tests/Application/templates/bundles/SyliusShopBundle/Checkout/SelectPayment/_payment.html.twig +vendor/bitbag/sylius-imoje-plugin/tests/Application/templates/bundles/SyliusShopBundle/Order/show.html.twig +``` + +### Install assets by running: +```bash +bin/console assets:install +``` + +## 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 +const [bitbagImojeShop, bitbagImojeAdmin] = require('./vendor/bitbag/sylius-imoje-plugin/webpack.config.js'); +``` +As next step, please add the imported consts into final module exports: +```js +module.exports = [..., bitbagImojeShop, bitbagImojeAdmin]; +``` + +### Assets +Add the asset configuration into `config/packages/assets.yaml`: +```yaml +framework: + assets: + packages: + # ... + imoje_shop: + json_manifest_path: '%kernel.project_dir%/public/build/bitbag/imoje/shop/manifest.json' + imoje_admin: + json_manifest_path: '%kernel.project_dir%/public/build/bitbag/imoje/admin/manifest.json' +``` + +### Webpack Encore +Add the webpack configuration into `config/packages/webpack_encore.yaml`: + +```yaml +webpack_encore: + output_path: '%kernel.project_dir%/public/build/default' + builds: + # ... + imoje_shop: '%kernel.project_dir%/public/build/bitbag/imoje/shop' + imoje_admin: '%kernel.project_dir%/public/build/bitbag/imoje/admin' +``` + +### Encore functions +Add encore functions to your templates: + +SyliusAdminBundle: +```php +{# @SyliusAdminBundle/_scripts.html.twig #} +{{ encore_entry_script_tags('bitbag-imoje-admin', null, 'imoje_admin') }} + +{# @SyliusAdminBundle/_styles.html.twig #} +{{ encore_entry_link_tags('bitbag-imoje-admin', null, 'imoje_admin') }} +``` +SyliusShopBundle: +```php +{# @SyliusShopBundle/_scripts.html.twig #} +{{ encore_entry_script_tags('bitbag-imoje-shop', null, 'imoje_shop') }} + +{# @SyliusShopBundle/_styles.html.twig #} +{{ encore_entry_link_tags('bitbag-imoje-shop', null, 'imoje_shop') }} +``` + +### Run commands +```bash +yarn install +yarn encore dev # or prod, depends on your environment +``` + +## Known issues +### Translations not displaying correctly +For incorrectly displayed translations, execute the command: +```bash +bin/console cache:clear +```