From 1d96cd69f15332ed0351f6489ef6fcbbb52de35a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Kali=C5=84ski?= Date: Fri, 30 Aug 2024 09:26:09 +0200 Subject: [PATCH] OP-505 - installation.md has been updated --- README.md | 153 ++------------------ doc/installation.md | 195 ++++++++++++++++++++++++++ doc/installation/attribute-mapping.md | 49 +++++++ doc/installation/xml-mapping.md | 71 ++++++++++ 4 files changed, 327 insertions(+), 141 deletions(-) create mode 100644 doc/installation.md create mode 100644 doc/installation/attribute-mapping.md create mode 100644 doc/installation/xml-mapping.md diff --git a/README.md b/README.md index 4b20123d..ec5f83fd 100644 --- a/README.md +++ b/README.md @@ -58,152 +58,23 @@ In plugin repository there is Docker Compose file that can be used to run Elasti # Installation ---- +### Requirements +**Note:** This Plugin supports ElasticSearch 7.0 and above. If you're looking for ElasticSearch Plugin for older versions check SyliusElasticSearchPlugin in version 1.x. We work on stable, supported and up-to-date versions of packages. We recommend you to do the same. -*Note*: This Plugin supports ElasticSearch 7.0 and above. If you're looking for ElasticSearch Plugin for older versions check SyliusElasticSearchPlugin in version `1.x`. +| Package | Version | +|---------------|-----------------| +| PHP | \>=8.1 | +| sylius/sylius | 1.12.x - 1.13.x | +| MySQL | \>= 5.7 | +| NodeJS | \>= 18.x | +| ElasticSearch | \>= 7.x | -```bash -$ composer require bitbag/elasticsearch-plugin --no-scripts -``` - - -Add plugin dependencies to your `config/bundles.php` file: -```php -return [ - ... - - FOS\ElasticaBundle\FOSElasticaBundle::class => ['all' => true], - BitBag\SyliusElasticsearchPlugin\BitBagSyliusElasticsearchPlugin::class => ['all' => true], -]; -``` - -Use trait `BitBag\SyliusElasticsearchPlugin\Model\ProductVariantTrait` in an overridden ProductVariant entity class. [see how to overwrite a sylius model](https://docs.sylius.com/en/1.9/customization/model.html) - -also Use `BitBag\SyliusElasticsearchPlugin\Model\ProductVariantInterface` interface in ProductVariant entity class. -The final effect should look like the following: - -``` -use BitBag\SyliusElasticsearchPlugin\Model\ProductVariantInterface as BitBagElasticsearchPluginVariant; -use BitBag\SyliusElasticsearchPlugin\Model\ProductVariantTrait; -use Sylius\Component\Core\Model\ProductVariantInterface as BaseProductVariantInterface; - -class ProductVariant extends BaseProductVariant implements BaseProductVariantInterface, BitBagElasticsearchPluginVariant -{ - use ProductVariantTrait; - - ... -} -``` - -Import required config in your `config/packages/_sylius.yaml` file: -```yaml -# config/packages/_sylius.yaml - -imports: - ... - - - { resource: "@BitBagSyliusElasticsearchPlugin/Resources/config/config.yml" } -``` - -Import routing **on top** of your `config/routes.yaml` file: -```yaml -# config/routes.yaml - -bitbag_sylius_elasticsearch_plugin: - resource: "@BitBagSyliusElasticsearchPlugin/Resources/config/routing.yml" -``` - -...and set up the redirection from the default Sylius shop products index page on top of your `config/routes/sylius_shop.yaml` -file. -``` -# config/routes/sylius_shop.yaml - -redirect_sylius_shop_product_index: - path: /{_locale}/taxons/{slug} - controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction - defaults: - route: bitbag_sylius_elasticsearch_plugin_shop_list_products - permanent: true - requirements: - _locale: ^[a-z]{2}(?:_[A-Z]{2})?$ - slug: .+ -``` -...and update installed assets with the following command: -``` -$ bin/console assets:install -``` -...and remove the default ElasticSearch index (`app`) defined by `FOSElasticaBundle` in `config/packages/fos_elastica.yaml`: -``` - -fos_elastica: - clients: - default: { url: '%env(ELASTICSEARCH_URL)%' } - indexes: - app: ~ -``` -should become: -``` - -fos_elastica: - clients: - default: { url: '%env(ELASTICSEARCH_URL)%' } -``` -In the end, with an elasticsearch server running, execute following commands: -``` -$ bin/console cache:clear -$ bin/console fos:elastica:populate -``` - -**Note:** If you are running it on production, add the `-e prod` flag to this command. Elastic are created with environment suffix. - -### Configuring Webpack - -1. Import plugin's `webpack.config.js` file - -```js -// webpack.config.js -const [ bitbagElasticSearchShop ] = require('./vendor/bitbag/elasticsearch-plugin/webpack.config.js') -... - -module.exports = [..., bitbagElasticSearchShop]; -``` - -2. Add new packages in `./config/packages/assets.yaml` - -```yml -# config/packages/assets.yaml - -framework: - assets: - packages: - # ... - elasticsearch_shop: - json_manifest_path: '%kernel.project_dir%/public/build/bitbag/elasticsearch/shop/manifest.json' -``` - -3. Add new build paths in `./config/packages/webpack_encore.yml` - -```yml -# config/packages/webpack_encore.yml - -webpack_encore: - builds: - # ... - elasticsearch_shop: '%kernel.project_dir%/public/build/bitbag/elasticsearch/shop' -``` - -4. Add encore functions to your templates - -```twig -{# @SyliusShopBundle/_scripts.html.twig #} -{{ encore_entry_script_tags('bitbag-elasticsearch-shop', null, 'elasticsearch_shop') }} - -{# @SyliusShopBundle/_styles.html.twig #} -{{ encore_entry_link_tags('bitbag-elasticsearch-shop', null, 'elasticsearch_shop') }} -``` +---- -5. Run `yarn encore dev` or `yarn encore production` +### Full installation guide +- [See the full installation guide](doc/installation.md) ## Functionalities diff --git a/doc/installation.md b/doc/installation.md new file mode 100644 index 00000000..82f0afac --- /dev/null +++ b/doc/installation.md @@ -0,0 +1,195 @@ +# Installation + +## Overview: +GENERAL +- [Requirements](#requirements) +- [Composer](#composer) +- [Basic configuration](#basic-configuration) +--- +BACKEND +- [Entities](#entities) +--- +FRONTEND +- [Webpack](#webpack) +--- +ADDITIONAL +- [Additional configuration](#additional-configuration) +- [Known Issues](#known-issues) +--- + +## Requirements: +**Note:** This Plugin supports ElasticSearch 7.0 and above. If you're looking for ElasticSearch Plugin for older versions check SyliusElasticSearchPlugin in version 1.x. + +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 | +| ElasticSearch | \>= 7.x | + +## Composer: +```bash +composer require bitbag/elasticsearch-plugin --no-scripts +``` + +## Basic configuration: +Add plugin dependencies to your `config/bundles.php` file: + +```php +# config/bundles.php + +return [ + ... + FOS\ElasticaBundle\FOSElasticaBundle::class => ['all' => true], + BitBag\SyliusElasticsearchPlugin\BitBagSyliusElasticsearchPlugin::class => ['all' => true], +]; +``` + +Import required config in your `config/packages/_sylius.yaml` file: + +```yaml +# config/packages/_sylius.yaml + +imports: + ... + - { resource: "@BitBagSyliusElasticsearchPlugin/Resources/config/config.yml" } +``` + +Import routing on top of your `config/routes.yaml` file: + +```yaml +# config/routes.yaml + +bitbag_sylius_elasticsearch_plugin: + resource: "@BitBagSyliusElasticsearchPlugin/Resources/config/routing.yml" +``` + +...and set up the redirection from the default Sylius shop products index page on top of your config/routes/sylius_shop.yaml file. +```yaml +# config/routes/sylius_shop.yaml + +redirect_sylius_shop_product_index: + path: /{_locale}/taxons/{slug} + controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction + defaults: + route: bitbag_sylius_elasticsearch_plugin_shop_list_products + permanent: true + requirements: + _locale: ^[a-z]{2}(?:_[A-Z]{2})?$ + slug: .+ +``` + +Remove the default ElasticSearch index (`app`) defined by `FOSElasticaBundle` in `config/packages/fos_elastica.yaml`: +```yaml +# config/packages/fos_elastica.yaml + +fos_elastica: + clients: + default: { url: '%env(ELASTICSEARCH_URL)%' } + indexes: + app: ~ +``` +should become: + +```yaml +fos_elastica: + clients: + default: { url: '%env(ELASTICSEARCH_URL)%' } +``` + +## Entities +Use `BitBag\SyliusElasticsearchPlugin\Model\ProductVariantTrait` and `BitBag\SyliusElasticsearchPlugin\Model\ProductVariantInterface` in an overridden ProductVariant entity class. +The configuration, depending on the mapping used, may vary. + +### Attribute mapping +- [Attribute mapping configuration](installation/attribute-mapping.md) +### XML mapping +- [XML mapping configuration](installation/xml-mapping.md) + +### Update installed assets with the following command: +```bash +bin/console assets:install +``` + +### Clear application cache by using command: +```bash +bin/console cache:clear +``` + +### Finally, with an elasticsearch server running, execute following command: +```bash +bin/console fos:elastica:populate +``` + +**Note:** If you are running it on production, add the `-e prod` flag to this command. Elastic are created with environment suffix. + +## 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 [ bitbagElasticSearchShop ] = require('./vendor/bitbag/elasticsearch-plugin/webpack.config.js') +``` +As next step, please add the imported consts into final module exports: +```js +module.exports = [..., bitbagElasticSearchShop]; +``` + +### Assets +Add the asset configuration into `config/packages/assets.yaml`: +```yaml +framework: + assets: + packages: + ... + elasticsearch_shop: + json_manifest_path: '%kernel.project_dir%/public/build/bitbag/elasticsearch/shop/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: + ... + elasticsearch_shop: '%kernel.project_dir%/public/build/bitbag/elasticsearch/shop' +``` + +### Encore functions +Add encore functions to your templates: + +SyliusShopBundle: +```php +{# @SyliusShopBundle/_scripts.html.twig #} +{{ encore_entry_script_tags('bitbag-elasticsearch-shop', null, 'elasticsearch_shop') }} + +{# @SyliusShopBundle/_styles.html.twig #} +{{ encore_entry_link_tags('bitbag-elasticsearch-shop', null, 'elasticsearch_shop') }} +``` + +### Run commands +```bash +yarn install +yarn encore dev # or prod, depends on your environment +``` + +## Additional configuration +Elasticsearch's port settings can be found in the `.env` file. + +```dotenv +###> friendsofsymfony/elastica-bundle ### +ELASTICSEARCH_URL=http://localhost:9200/ +###< friendsofsymfony/elastica-bundle ### +``` + +## Known issues +### Translations not displaying correctly +For incorrectly displayed translations, execute the command: +```bash +bin/console cache:clear +``` diff --git a/doc/installation/attribute-mapping.md b/doc/installation/attribute-mapping.md new file mode 100644 index 00000000..99f05319 --- /dev/null +++ b/doc/installation/attribute-mapping.md @@ -0,0 +1,49 @@ +# Attribute-mapping + +Check the mapping settings in `config/packages/doctrine.yaml`. +```yaml +doctrine: + ... + orm: + entity_managers: + default: + ... + mappings: + App: + ... + type: attribute +``` + +Update entity with traits: +```php + + + + + + +``` + +Override `config/packages/_sylius.yaml` configuration: +```yaml +# config/_sylius.yaml + +sylius_product: + resources: + product_variant: + classes: + model: App\Entity\ProductVariant +```