From ce9a2f4f8b956aa30f5f5bccbf3199608755614b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Kali=C5=84ski?= Date: Tue, 3 Sep 2024 13:07:39 +0200 Subject: [PATCH] OP-511 - installation.md has been updated --- doc/installation.md | 436 ++++++++++---------------- doc/installation/attribute-mapping.md | 124 ++++++++ doc/installation/controllers.md | 95 ++++++ doc/installation/xml-mapping.md | 172 ++++++++++ 4 files changed, 550 insertions(+), 277 deletions(-) create mode 100644 doc/installation/attribute-mapping.md create mode 100644 doc/installation/controllers.md create mode 100644 doc/installation/xml-mapping.md diff --git a/doc/installation.md b/doc/installation.md index 3ed4773..04cfab1 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -1,16 +1,53 @@ -## Installation - +# Installation + +## Overview: +GENERAL +- [Requirements](#requirements) +- [Composer](#composer) +- [Basic configuration](#basic-configuration) +--- +BACKEND +- [Entities](#entities) + - [Attribute mapping](#attribute-mapping) + - [XML mapping](#xml-mapping) +- [Controllers](#controllers) +--- +FRONTEND +- [Templates](#templates) +- [Webpack](#webpack) +--- +ADDITIONAL +- [Additional configuration](#additional-configuration) +- [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.0 | +| sylius/sylius | 1.12.x - 1.13.x | +| MySQL | \>= 5.7 | +| NodeJS | \>= 18.x | + +--- +## Composer: ```bash -$ composer require bitbag/inpost-plugin +composer require bitbag/inpost-plugin ``` +--- +## Basic configuration: Add plugin dependencies to your `config/bundles.php` file: ```php +# config/bundles.php + return [ ... - - BitBag\SyliusInPostPlugin\BitBagSyliusInPostPlugin::class => ['all' => true] + BitBag\SyliusInPostPlugin\BitBagSyliusInPostPlugin::class => ['all' => true], ]; ``` @@ -20,327 +57,160 @@ Import required config in your `config/packages/_sylius.yaml` file: # config/packages/_sylius.yaml imports: - ... - - - { resource: "@BitBagSyliusInPostPlugin/Resources/config/config.yml" } + ... + - { resource: "@BitBagSyliusInPostPlugin/Resources/config/config.yml" } ``` Import routing in your `config/routes.yaml` file: - ```yaml - # config/routes.yaml -... bitbag_sylius_inpost_plugin: - resource: "@BitBagSyliusInPostPlugin/Resources/config/routes.yml" + resource: "@BitBagSyliusInPostPlugin/Resources/config/routes.yml" ``` -This plugin was made on top -of [SyliusShippingExportPlugin](https://github.com/BitBagCommerce/SyliusShippingExportPlugin). -Typically, Symfony Flex, if you agree, automatically adds the configuration files: -bitbag_shipping_export_plugin.yaml to the config/packages and config/routes directories. -It also adding the appropriate entry to config/bundles.php. -If it doesn't, so please remember to do the same as above for SyliusShippingExportPlugin configuration. +This plugin was made on top of [SyliusShippingExportPlugin](https://github.com/BitBagCommerce/SyliusShippingExportPlugin). +Usually, `Symfony Flex`, if you agree, automatically adds the configuration files: -### Extend entities with parameters +- `bitbag_shipping_export_plugin.yaml` to the `config/packages` directory +- `bitbag_shipping_export_plugin.yaml` to the `config/routes` directory -You can implement this using xml-mapping or attributes. Instructions for both settings are described below. +It also adding the appropriate entry to `config/bundles.php`. -#### For doctrine XML-MAPPING: -If you are using doctrine xml-mapping, you have probably already removed the entries -for the entity in config/_sylius.yaml and all entity extensions are in src/Entity. -Add the following entries to config/_sylius.yaml: -``` -sylius_order: - resources: - order: - classes: - model: App\Entity\Order - -sylius_shipping: - resources: - shipping_method: - classes: - model: App\Entity\ShippingMethod +If it doesn't, so please remember to do the same as above for `SyliusShippingExportPlugin` configuration. -``` +--- +## 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) -Add trait and interface to your Order and ShippingMethod entity classes: - -```php - - - - - - - - - - - - - - - - -``` -```xml - - - - - - - - - - - - - -``` -#### You can do it with attributes if you prefer. Remember to mark it appropriately in the config/doctrine.yaml configuration file. +### Update your database +First, please run legacy-versioned migrations by using command: +```bash +bin/console doctrine:migrations:migrate ``` -doctrine: - ... - orm: - ... - mappings: - App: - ... - type: attribute +After migration, please create a new diff migration and update database: +```bash +bin/console doctrine:migrations:diff +bin/console doctrine:migrations:migrate ``` -```php -point; - } - - public function setPoint(?InPostPointInterface $point): void - { - $this->point = $point; - } -} +**Note:** If you are running it on production, add the `-e prod` flag to this command. -``` +--- +## Controllers +Add the controller from the following instruction: -```php -image; - } - - public function setImage(?ImageInterface $image): void - { - $this->image = $image; - } -} +- [Adding controllers](installation/controllers.md) +### Clear application cache by using command: +```bash +bin/console cache:clear ``` -Finish the installation by updating the database schema (check in advance: [Known Issues](known_issues.md)): +**Note:** If you are running it on production, add the `-e prod` flag to this command. -``` -$ bin/console doctrine:migrations:diff -$ bin/console doctrine:migrations:migrate -$ bin/console assets:install --symlink -$ bin/console sylius:theme:assets:install --symlink -``` -### TWIG configuration -#### Adding files to the template -Copy the files below to the appropriate directories in your template. +--- +## Templates +Copy required templates into correct directories in your project. +**AdminBundle** (`templates/bundles/SyliusAdminBundle`): ``` vendor/bitbag/inpost-plugin/tests/Application/templates/bundles/SyliusAdminBundle/Order/Show/_addresses.html.twig vendor/bitbag/inpost-plugin/tests/Application/templates/bundles/SyliusAdminBundle/ShippingMethod/_form.html.twig ``` + +**ShopBundle** (`templates/bundles/SyliusShopBundle`): ``` vendor/bitbag/inpost-plugin/tests/Application/templates/bundles/SyliusShopBundle/Checkout/SelectShipping/_choice.html.twig vendor/bitbag/inpost-plugin/tests/Application/templates/bundles/SyliusShopBundle/Common/Order/_addresses.html.twig vendor/bitbag/inpost-plugin/tests/Application/templates/bundles/SyliusShopBundle/Grid/Action/quickReturn.html.twig ``` -### 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: - admin: '%kernel.project_dir%/public/build/admin' - shop: '%kernel.project_dir%/public/build/shop' - app.admin: '%kernel.project_dir%/public/build/app/admin' - app.shop: '%kernel.project_dir%/public/build/app/shop' - inpost_admin: '%kernel.project_dir%/public/build/bitbag/inpost/admin' - inpost_shop: '%kernel.project_dir%/public/build/bitbag/inpost/shop' - ``` +--- +## Webpack +### Webpack.config.js -2. To install Webpack in your application, please run the command below: +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 [bitbagInPostShop, bitbagInPostAdmin] = require('./vendor/bitbag/inpost-plugin/webpack.config.js'); +``` +As next step, please add the imported consts into final module exports: +```js +module.exports = [..., bitbagInPostShop, bitbagInPostAdmin]; +``` - ```bash - $ composer require "symfony/webpack-encore-bundle" - ``` +### Assets +Add the asset configuration into `config/packages/assets.yaml`: +```yaml +framework: + assets: + packages: + ... + inpost_shop: + json_manifest_path: '%kernel.project_dir%/public/build/bitbag/inpost/shop/manifest.json' + inpost_admin: + json_manifest_path: '%kernel.project_dir%/public/build/bitbag/inpost/admin/manifest.json' +``` -3. After installation, please add the line below into `config/bundles.php` file: +### Webpack Encore +Add the webpack configuration into `config/packages/webpack_encore.yaml`: - ```php - return [ +```yaml +webpack_encore: + output_path: '%kernel.project_dir%/public/build/default' + builds: ... - Symfony\WebpackEncoreBundle\WebpackEncoreBundle::class => ['all' => true], - ]; - ``` -#### Configuring Webpack + inpost_admin: '%kernel.project_dir%/public/build/bitbag/inpost/admin' + inpost_shop: '%kernel.project_dir%/public/build/bitbag/inpost/shop' +``` -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.12/webpack.config.js). +### Run commands +#### Install assets by using the following commands: +```bash +bin/console assets:install +bin/console sylius:theme:assets:install +``` +or (may cause errors): +```bash +bin/console assets:install --symlink +bin/console sylius:theme:assets:install --symlink +``` -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: +#### Run webpack by using the following commands: +```bash +yarn install +yarn encore dev # or prod, depends on your environment +``` - ```javascript - const [bitbagInPostShop, bitbagInPostAdmin] = require('./vendor/bitbag/inpost-plugin/webpack.config.js'); - ``` -2. As next step, please add the imported consts into final module exports: - ```javascripts - module.exports = [shopConfig, adminConfig, appShopConfig, appAdminConfig, bitbagInPostShop, bitbagInPostAdmin]; - ``` +--- +## Additional configuration +### Default parameters configuration +In the `.env` file, the default `parcel size` and `label type` can be specified by adding: -3. Next thing is to add the asset configuration into `config/packages/assets.yaml`: +```dotenv +BITBAG_INPOST_DEFAULT_PARCEL_TEMPLATE='medium' +BITBAG_INPOST_DEFAULT_LABEL_TYPE='normal' +``` - ```yaml - framework: - assets: - packages: - admin: - json_manifest_path: '%kernel.project_dir%/public/build/admin/manifest.json' - shop: - json_manifest_path: '%kernel.project_dir%/public/build/shop/manifest.json' - app.admin: - json_manifest_path: '%kernel.project_dir%/public/build/app/admin/manifest.json' - app.shop: - json_manifest_path: '%kernel.project_dir%/public/build/app/shop/manifest.json' - inpost_shop: - json_manifest_path: '%kernel.project_dir%/public/build/bitbag/inpost/shop/manifest.json' - inpost_admin: - json_manifest_path: '%kernel.project_dir%/public/build/bitbag/inpost/admin/manifest.json' - ``` -4. Additionally, please add the `"@symfony/webpack-encore": "^1.5.0",` dependency into your `package.json` file. +#### Three types of parcel templates are allowed: -5. Now you can run the commands: +- 'small' +- 'medium' +- 'large' - ```bash - $ yarn install - $ yarn encore dev # or prod, depends on your environment - ``` +#### Two types of labels are allowed: +- 'normal' +- 'A6' -## Testing & running the plugin +--- +## Tests +### Testing & running the plugin ```bash $ composer install @@ -355,3 +225,15 @@ $ open http://localhost:8080 $ vendor/bin/behat $ vendor/bin/phpspec run ``` + +--- +## Known issues +### Translations not displaying correctly +For incorrectly displayed translations, execute the command: +```bash +bin/console cache:clear +``` +**Note:** If you are running it on production, add the `-e prod` flag to this command. + +### Other known issues +- [check the other known issues](known_issues.md) diff --git a/doc/installation/attribute-mapping.md b/doc/installation/attribute-mapping.md new file mode 100644 index 0000000..5fd0861 --- /dev/null +++ b/doc/installation/attribute-mapping.md @@ -0,0 +1,124 @@ +# 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: + +- **Order entity:** +```php +requestConfigurationFactory->create($this->metadata, $request); + + Assert::implementsInterface($this->repository, ShippingExportRepositoryInterface::class); + $shippingExports = $this->repository->findAllWithNewOrPendingState(); + + if (0 === count($shippingExports)) { + /** @var FlashBagInterface $flashBag */ + $flashBag = $request->getSession()->getBag('flashes'); + $flashBag->add('error', 'bitbag.ui.no_new_shipments_to_export'); + + return $this->redirectToReferer($request); + } + + foreach ($shippingExports as $shippingExport) { + $this->eventDispatcher->dispatch( + ExportShipmentEvent::SHORT_NAME, + $configuration, + $shippingExport, + ); + } + + return $this->redirectToReferer($request); + } + + public function exportSingleShipmentAction(Request $request): RedirectResponse + { + $configuration = $this->requestConfigurationFactory->create($this->metadata, $request); + + /** @var ResourceInterface|null $shippingExport */ + $shippingExport = $this->repository->find($request->get('id')); + Assert::notNull($shippingExport); + + $this->eventDispatcher->dispatch( + ExportShipmentEvent::SHORT_NAME, + $configuration, + $shippingExport, + ); + + return $this->redirectToReferer($request); + } + + private function redirectToReferer(Request $request): RedirectResponse + { + $referer = $request->headers->get('referer'); + if (null !== $referer) { + return new RedirectResponse($referer); + } + + return $this->redirectToRoute($request->attributes->get('_route')); + } +} +``` + +Add controller in `config/packages/bitbag_shipping_export_plugin.yaml` configuration: +```yaml +# config/packages/bitbag_shipping_export_plugin.yaml + +imports: + ... +sylius_resource: + resources: + bitbag.shipping_export: + classes: + ... + controller: App\Controller\ShippingExportController +``` diff --git a/doc/installation/xml-mapping.md b/doc/installation/xml-mapping.md new file mode 100644 index 0000000..0c5e51f --- /dev/null +++ b/doc/installation/xml-mapping.md @@ -0,0 +1,172 @@ +# 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: +- **Order entity:** +```php + + + + + + + + + + + + + + + + +``` + +- **Shipping method entity:** + +`src/Resources/config/doctrine/ShippingMethod.orm.xml` + +```xml + + + + + + + + + + + + + +``` + +- **Shipping export entity:** + +`src/Resources/config/doctrine/ShippingExport.orm.xml` + +```xml + + + + + + + + +``` + +Override `config/packages/_sylius.yaml` configuration: +```yaml +# config/_sylius.yaml + +sylius_order: + resources: + order: + classes: + model: App\Entity\Order + +sylius_shipping: + resources: + shipping_method: + classes: + model: App\Entity\ShippingMethod +``` + +Add to `config/packages/bitbag_shipping_export_plugin.yaml` file: +```yaml +# config/packages/bitbag_shipping_export_plugin.yaml + +imports: + ... +sylius_resource: + resources: + bitbag.shipping_export: + classes: + model: App\Entity\ShippingExport +```