diff --git a/README.md b/README.md index b384030..ebc5e56 100644 --- a/README.md +++ b/README.md @@ -34,520 +34,25 @@ This **open-source plugin was developed to help the Sylius community**. If you h [![](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_shipping_subscription) -# Installation ----- +## Installation +--- +### Requirements We work on stable, supported and up-to-date versions of packages. We recommend you to do the same. -```bash -$ composer require bitbag/shipping-subscription-plugin -``` - -Add plugin dependencies to your `config/bundles.php` file: -```php -return [ - ... - - BitBag\SyliusShippingSubscriptionPlugin\BitBagSyliusShippingSubscriptionPlugin::class => ['all' => true], -]; -``` -Import required config in your `config/packages/_sylius.yaml` file: - -```yaml -# config/packages/_sylius.yaml - -imports: - ... - - - { resource: "@BitBagSyliusShippingSubscriptionPlugin/Resources/config/services.xml" } - - { resource: "@BitBagSyliusShippingSubscriptionPlugin/Resources/config/resources.yml" } - - { resource: "@BitBagSyliusShippingSubscriptionPlugin/Resources/config/grids.yml" } -``` - -Add routing in your `config/routes.yaml` file: - -```yaml - -# config/routes.yaml -... - -bitbag_sylius_shipping_subscription_plugin: - resource: "@BitBagSyliusShippingSubscriptionPlugin/Resources/config/routing.yml" -``` - - -Extend `Product`(including Doctrine mapping): -If you want to extend entities via attribute mapping, see here: [Attributes](doc/attributes_mapping.md) - -```php - - - - - - - - - - - - ``` -Extend `Customer` (including Doctrine mapping): - -```php -|null */ - protected $shippingSubscriptions; - - /** @return Collection|null */ - public function getSubscriptions(): ?Collection - { - return $this->shippingSubscriptions; - } -} -``` - - Mapping (XML): - -```xml - - - - - - - - -``` - -Extend `ShippingMethod` (including Doctrine mapping): - -```php -availableFromTotal; - } - - public function setAvailableFromTotal(?int $availableFromTotal): void - { - $this->availableFromTotal = $availableFromTotal; - } - - public function isShippingSubscription(): ?bool - { - return $this->shippingSubscription; - } - - public function setShippingSubscription(?bool $shippingSubscription): void - { - $this->shippingSubscription = $shippingSubscription; - } -} -``` - Mapping (XML): - -```xml - - - - - - - - - - - - - - - - -``` -Extend `ProductVariant`: - -```php -subscriptionLength; - } - - public function setSubscriptionLength(?int $subscriptionLength): void - { - $this->subscriptionLength = $subscriptionLength; - } -} -``` -Mapping (XML): +| Package | Version | +|---------------|-----------------| +| PHP | \>=8.0 | +| sylius/sylius | 1.12.x - 1.13.x | +| MySQL | \>= 5.7 | +| NodeJS | \>= 20.x | -```xml - - - - - - - - - - - - - -``` - -Extend `OrderItemUnitRepository`: - -```php - -

{{ 'sylius.ui.details'|trans }}

- -
- {{ form_errors(form) }} - -
-
-
- {{ form_row(form.code) }} - {{ form_row(form.enabled) }} - {{ form_row(form.shippingSubscription) }} - {% if product.simple %} - {{ form_row(form.variant.shippingRequired) }} - {% else %} - {{ form_row(form.options, {'remote_url': path('sylius_admin_ajax_product_options_by_phrase'), 'load_edit_url': path('sylius_admin_ajax_find_product_options')}) }} - {{ form_row(form.variantSelectionMethod) }} - {% endif %} - - {# Nothing to see here. #} - -
-
-
- {{ form_row(form.channels) }} -
-
- {% if product.simple %} -
-
-

{{ 'sylius.ui.pricing'|trans }}

- {% include "@SyliusAdmin/Product/_channel_pricing.html.twig" with { product: product, variantForm: form.variant } only %} -
-
- {% endif %} - - {{ translationFormWithSlug(form.translations, '@SyliusAdmin/Product/_slugField.html.twig', product) }} - {% if product.simple %} - -
-
-

{{ 'sylius.ui.shipping'|trans }}

-
- {{ form_row(form.variant.shippingCategory) }} - {{ form_row(form.variant.width) }} - {{ form_row(form.variant.height) }} - {{ form_row(form.variant.depth) }} - {{ form_row(form.variant.weight) }} -
-
-
-

{{ 'sylius.ui.taxes'|trans }}

-
- {{ form_row(form.variant.taxCategory) }} -
-
-
- {% endif %} - - {{ sylius_template_event(['sylius.admin.product.' ~ action ~ '.tab_details', 'sylius.admin.product.tab_details'], {'form': form}) }} -
- -``` - - `templates/bundles/SyliusAdminBundle/ShippingMethod/_form.html.twig`: - -```twig -{% from '@SyliusAdmin/Macro/translationForm.html.twig' import translationForm %} - -
-
-
- {{ form_errors(form) }} -
- {{ form_row(form.code) }} - {{ form_row(form.zone) }} - {{ form_row(form.position) }} -
- {{ form_row(form.enabled) }} -

{{ 'sylius.ui.availability'|trans }}

- {{ form_row(form.channels) }} -

{{ 'bitbag_sylius_shipping_subscription.form.shipping.additional_requirements'|trans }}

- {{ form_row(form.shipping_subscription) }} -
- {{ form_row(form.availableFromTotal) }} -
-

{{ 'sylius.ui.category_requirements'|trans }}

- {{ form_row(form.category) }} - {% for categoryRequirementChoiceForm in form.categoryRequirement %} - {{ form_row(categoryRequirementChoiceForm) }} - {% endfor %} -

{{ 'sylius.ui.taxes'|trans }}

- {{ form_row(form.taxCategory) }} -

{{ 'sylius.ui.shipping_charges'|trans }}

- {{ form_row(form.calculator) }} - {% for name, calculatorConfigurationPrototype in form.vars.prototypes %} -
-
- {% endfor %} -
- {% if form.configuration is defined %} - {% for field in form.configuration %} - {{ form_row(field) }} - {% endfor %} - {% endif %} -
- -

{{ 'sylius.ui.rules'|trans }}

-
- {% include '@SyliusAdmin/ShippingMethod/_rules.html.twig' %} -
-
-
-
- {{ translationForm(form.translations) }} -
-
-``` - - `templates/bundles/SyliusAdminBundle/ProductVariant/Tab/_details.html.twig` - - **Note.** Depending on your Sylius version, it may be `templates/bundles/SyliusAdminBundle/Product/ProductVariant/Tab/_details.html.twig` file path. Please check the path in your vendor directory. - -```twig -{% from '@SyliusAdmin/Macro/translationForm.html.twig' import translationForm %} - -
- {% if form.subscriptionLength.vars.attr['is-subscription'] %} -

{{ 'bitbag_sylius_shipping_subscription.form.shipping.subscription_time'|trans }}

-
- {{ form_row(form.subscriptionLength) }} -
- {% endif %} -

{{ 'sylius.ui.details'|trans }}

-
- {{ translationForm(form.translations) }} - -
- {{ form_row(form.code) }} - {{ form_row(form.enabled) }} -
- {{ form_row(form.shippingCategory) }} -
-
-
-
- {{ form_row(form.shippingRequired) }} -
-
- {% if form.optionValues is defined and form.optionValues|length > 0 %} - -
-

{{ 'sylius.ui.options'|trans }}

- {% for option_form in form.optionValues %} - {{ form_row(option_form) }} - {% endfor %} -
- {% endif %} - -
-

{{ 'sylius.ui.properties'|trans }}

- {{ form_row(form.height) }} - {{ form_row(form.width) }} - {{ form_row(form.depth) }} - {{ form_row(form.weight) }} -
-
- - {{ sylius_template_event(['sylius.admin.product_variant.' ~ action ~ '.tab_details', 'sylius.admin.product_variant.tab_details'], {'form': form}) }} -
- -``` - -Add state machine configuration for example to `config/packages/state_machine.yaml`: - -```yaml -winzou_state_machine: - sylius_order: - callbacks: - after: - bitbag_order_cancellation_shipping_subscription: - on: [ "cancel" ] - do: [ "@bitbag_sylius_shipping_subscription.operator.shipping_subscription", "disable" ] - args: [ "object" ] - - sylius_order_checkout: - callbacks: - after: - bitbag_created_shipping_subscription: - on: [ "complete" ] - do: [ "@bitbag_sylius_shipping_subscription.operator.shipping_subscription", "create" ] - args: [ "object" ] - - sylius_order_payment: - callbacks: - after: - bitbag_shipping_subscription_enable: - on: [ "pay" ] - do: [ "@bitbag_sylius_shipping_subscription.operator.shipping_subscription", "enable" ] - args: [ "object" ] -``` +---- -Finish the installation by updating the database schema and installing assets: +### Full installation guide +- [See the full installation guide](doc/installation.md) -``` - $ bin/console doctrine:migrations:diff - $ bin/console doctrine:migrations:migrate -``` ## Usage ---- diff --git a/doc/installation.md b/doc/installation.md new file mode 100644 index 0000000..79117a3 --- /dev/null +++ b/doc/installation.md @@ -0,0 +1,167 @@ +# Installation + +## Overview: +GENERAL +- [Requirements](#requirements) +- [Composer](#composer) +- [Basic configuration](#basic-configuration) +--- +BACKEND +- [Entities](#entities) + - [Attribute mapping](#attribute-mapping) + - [XML mapping](#xml-mapping) +- [Repositories](#repositories) +--- +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/sylius | 1.12.x - 1.13.x | +| MySQL | \>= 5.7 | +| NodeJS | \>= 18.x | + +## Composer: +```bash +composer require bitbag/name-plugin +``` + +## Basic configuration: +Add plugin dependencies to your `config/bundles.php` file: + +```php +# config/bundles.php + +return [ + ... + BitBag\SyliusShippingSubscriptionPlugin\BitBagSyliusShippingSubscriptionPlugin::class => ['all' => true], +]; +``` + +Import required config in your `config/packages/_sylius.yaml` file: + +```yaml +# config/packages/_sylius.yaml + +imports: + ... + + - { resource: "@BitBagSyliusShippingSubscriptionPlugin/Resources/config/services.xml" } + - { resource: "@BitBagSyliusShippingSubscriptionPlugin/Resources/config/resources.yml" } + - { resource: "@BitBagSyliusShippingSubscriptionPlugin/Resources/config/grids.yml" } +``` + +Add routing to your `config/routes.yaml` file: +```yaml +# config/routes.yaml + +bitbag_sylius_shipping_subscription_plugin: + resource: "@BitBagSyliusShippingSubscriptionPlugin/Resources/config/routing.yml" +``` + +Add state machine configuration for example to `config/packages/state_machine.yaml`: +```yaml +# config/packages/state_machine.yaml + +winzou_state_machine: + sylius_order: + callbacks: + after: + bitbag_order_cancellation_shipping_subscription: + on: [ "cancel" ] + do: [ "@bitbag_sylius_shipping_subscription.operator.shipping_subscription", "disable" ] + args: [ "object" ] + + sylius_order_checkout: + callbacks: + after: + bitbag_created_shipping_subscription: + on: [ "complete" ] + do: [ "@bitbag_sylius_shipping_subscription.operator.shipping_subscription", "create" ] + args: [ "object" ] + + sylius_order_payment: + callbacks: + after: + bitbag_shipping_subscription_enable: + on: [ "pay" ] + do: [ "@bitbag_sylius_shipping_subscription.operator.shipping_subscription", "enable" ] + args: [ "object" ] +``` + +## 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) + +## Repositories +Add repository with following trait: +```php + 0])] + protected $shippingSubscription = false; + + // other methods +} +``` + +- `ProductVariant` entity + +`src/Entity/Product/ProductVariant.php` + + +```php + 0])] + protected ?int $subscriptionLength; + + public function getSubscriptionLength(): ?int + { + return $this->subscriptionLength; + } + + public function setSubscriptionLength(?int $subscriptionLength): void + { + $this->subscriptionLength = $subscriptionLength; + } + + // other methods +} +``` + +- `Customer` entity + +`src/Entity/Customer/Customer.php` + +```php +|null */ + public function getSubscriptions(): ?Collection + { + return $this->shippingSubscriptions; + } +} +``` + +- `ShippingMethod` entity + +`src/Entity/Shipping/ShippingMethod.php` + +```php + 0])] + protected ?bool $shippingSubscription; + + #[ORM\Column(type: 'integer', nullable: true)] + protected ?int $availableFromTotal; + + public function getAvailableFromTotal(): ?int + { + return $this->availableFromTotal; + } + + public function setAvailableFromTotal(?int $availableFromTotal): void + { + $this->availableFromTotal = $availableFromTotal; + } + + public function isShippingSubscription(): ?bool + { + return $this->shippingSubscription; + } + + public function setShippingSubscription(?bool $shippingSubscription): void + { + $this->shippingSubscription = $shippingSubscription; + } + + // other methods +} +``` diff --git a/doc/installation/xml-mapping.md b/doc/installation/xml-mapping.md new file mode 100644 index 0000000..413f440 --- /dev/null +++ b/doc/installation/xml-mapping.md @@ -0,0 +1,262 @@ +# XML-mapping + +Check the mapping settings in `config/packages/doctrine.yaml` and, if necessary, change them accordingly. +```yaml +doctrine: + # ... + orm: + entity_managers: + default: + # ... + mappings: + App: + # ... + type: xml + dir: '%kernel.project_dir%/src/Resources/config/doctrine' +``` + +Extend entities with parameters and methods using attributes and traits: + +- `Product` entity + +`src/Entity/Product.php` + +```php +subscriptionLength; + } + + public function setSubscriptionLength(?int $subscriptionLength): void + { + $this->subscriptionLength = $subscriptionLength; + } +} +``` + +- `Customer` entity + +`src/Entity/Customer.php` + +```php +|null */ + protected $shippingSubscriptions; + + /** @return Collection|null */ + public function getSubscriptions(): ?Collection + { + return $this->shippingSubscriptions; + } +} +``` + +- `ShippingMethod` entity + +`src/Entity/ShippingMethod.php` + +```php +availableFromTotal; + } + + public function setAvailableFromTotal(?int $availableFromTotal): void + { + $this->availableFromTotal = $availableFromTotal; + } + + public function isShippingSubscription(): ?bool + { + return $this->shippingSubscription; + } + + public function setShippingSubscription(?bool $shippingSubscription): void + { + $this->shippingSubscription = $shippingSubscription; + } +} +``` + + +Define new Entity mapping inside `c` directory. +- `Product` entity + +`src/Resources/config/doctrine/Product.orm.xml` +```xml + + + + + + + + + + + +``` + +- `ProductVariant` entity + +`src/Resources/config/doctrine/ProductVariant.orm.xml` +```xml + + + + + + + + + + + +``` + +- `Customer` entity + +`src/Resources/config/doctrine/Customer.orm.xml` + +```xml + + + + + + + + +``` + +- `ShippingMethod` entity + +`src/Resources/config/doctrine/ShippingMethod.orm.xml` + +```xml + + + + + + + + + + + + + + +``` + +Override `config/packages/_sylius.yaml` configuration: +```yaml +# config/_sylius.yaml + +sylius_product: + resources: + product: + classes: + model: App\Entity\Product + product_variant: + classes: + model: App\Entity\ProductVariant + +sylius_shipping: + resources: + shipping_method: + classes: + model: App\Entity\ShippingMethod + +sylius_customer: + resources: + customer: + classes: + model: App\Entity\Customer +```