From 07c025ac5d270f11af295ce519d7ee55d896d355 Mon Sep 17 00:00:00 2001 From: Nikola Lardev Date: Fri, 13 Sep 2024 15:15:30 +0300 Subject: [PATCH 1/6] DEVDOCS-57 Add custom shipping carrier tutorial --- add-custom-shipping-carrier.md | 170 +++++++++++++++++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 add-custom-shipping-carrier.md diff --git a/add-custom-shipping-carrier.md b/add-custom-shipping-carrier.md new file mode 100644 index 0000000..265330a --- /dev/null +++ b/add-custom-shipping-carrier.md @@ -0,0 +1,170 @@ +# Add custom shipping carrier + +[TOC] + +Magento 2 allows the creation of custom shipping carriers to handle various shipping methods for different carriers or logistics providers. A custom shipping carrier can be added by creating a Magento 2 module and configuring the required fields to handle shipping calculations, carrier configurations, and frontend integration. + +## Module Setup + +The first step in adding a custom shipping carrier is creating the necessary directory structure for the Mage-OS module: + +```bash +app/code/Vendor/ShippingCarrier/ +├── registration.php +├── etc +│ ├── module.xml +│ ├── config.xml +│ ├── system.xml +├── Model +│ └── Carrier +│ └── CustomCarrier.php +``` + +Create register module file `app/code/Vendor/ShippingCarrier/registration.php` +```php + + + + +``` + +## Shipping Carrier Configuration + +In the `config.xml` file, define the shipping carrier's core settings, such as its active state, title, and allowed countries. Create `app/code/Vendor/ShippingCarrier/etc/config.xml`: + +```xml + + + + + + 1 + Custom Shipping Carrier + Custom Carrier + 0 + US,CA + Vendor\ShippingCarrier\Model\Carrier\CustomCarrier + F + 10.00 + 0 + + + + +``` + +Explanation: + +- active: Enables or disables the custom carrier. +- title: The name displayed in the checkout. +- name: Internal name of the carrier. +- model: The path to the custom shipping carrier model. +- handling_type: Type of handling fee (F for fixed or P for percent). +- handling_fee: The amount of the handling fee. + +# Admin Configuration for Carrier + +To allow store administrators to configure the shipping method, we define settings in `app/code/Vendor/ShippingCarrier/etc/adminhtml/system.xml.`: + +```xml + + + +
+ + + + + Magento\Config\Model\Config\Source\Yesno + + + + + + + + +
+ + +``` + +This configuration allows administrators to enable the carrier, set a title, and configure a handling fee through the Mage-OS admin panel. + +# Shipping Carrier Model + +The core logic for the custom shipping carrier is in the CustomCarrier.php model. This class extends Mage-OS's abstract shipping carrier class and implements the shipping calculation and rates. + +```php +getConfigFlag('active')) { + return false; + } + + /** @var \Magento\Shipping\Model\Rate\Result $result */ + $result = $this->_rateResultFactory->create(); + + // Set shipping cost + $shippingPrice = 10.00; + + /** @var \Magento\Quote\Model\Quote\Address\RateResult\Method $method */ + $method = $this->_rateMethodFactory->create(); + $method->setCarrier($this->_code); + $method->setCarrierTitle($this->getConfigData('title')); + + $method->setMethod($this->_code); + $method->setMethodTitle('Custom Carrier Method'); + + $method->setPrice($shippingPrice); + $method->setCost($shippingPrice); + + $result->append($method); + + return $result; + } + + public function getAllowedMethods() + { + return [$this->_code => $this->getConfigData('name')]; + } +} + +``` + +Explanation: + +- collectRates(): Calculates shipping rates based on the quote request and returns them. Here, a fixed rate of 10.00 is used. +- getAllowedMethods(): Returns the allowed shipping methods for this carrier. + +# Frontend Integration + +Once the backend logic is in place, the custom shipping carrier will automatically appear in the Mage-OS checkout if it's enabled and configured properly. The title and price will be displayed as defined in the carrier configuration. + +# Conclusion +This guide walks through the basic setup of a custom shipping carrier in Mage-OS. The carrier integrates with Mage-OS’s shipping framework, allowing you to customize the shipping calculation and display it during the checkout process. You can extend this basic structure to integrate with third-party APIs, offer dynamic shipping rates, or introduce more complex shipping logic based on cart contents or customer information. \ No newline at end of file From 3a5c23c2b79ab721f12e88e27988bd564eb167e9 Mon Sep 17 00:00:00 2001 From: Nikola Lardev Date: Sat, 28 Sep 2024 01:50:39 +0300 Subject: [PATCH 2/6] DEVDOCS-57 - Add custom shipping carrier --- add-custom-shipping-carrier.md | 126 +++++++++++++++++++++++---------- 1 file changed, 90 insertions(+), 36 deletions(-) diff --git a/add-custom-shipping-carrier.md b/add-custom-shipping-carrier.md index 265330a..7fe8ce5 100644 --- a/add-custom-shipping-carrier.md +++ b/add-custom-shipping-carrier.md @@ -2,25 +2,27 @@ [TOC] -Magento 2 allows the creation of custom shipping carriers to handle various shipping methods for different carriers or logistics providers. A custom shipping carrier can be added by creating a Magento 2 module and configuring the required fields to handle shipping calculations, carrier configurations, and frontend integration. +Mage-OS allows the creation of custom shipping carriers to handle various shipping methods for different carriers or logistics providers. A custom shipping carrier can be added by creating a Mage-OS module and configuring the required fields to handle shipping calculations, carrier configurations, and frontend integration. ## Module Setup The first step in adding a custom shipping carrier is creating the necessary directory structure for the Mage-OS module: ```bash -app/code/Vendor/ShippingCarrier/ +app/code/MageOS/ShippingCarrier/ ├── registration.php +├── composer.json ├── etc │ ├── module.xml │ ├── config.xml -│ ├── system.xml +│ ├── adminhtml + └── system.xml ├── Model │ └── Carrier │ └── CustomCarrier.php ``` -Create register module file `app/code/Vendor/ShippingCarrier/registration.php` +Create register module file `app/code/MageOS/ShippingCarrier/registration.php` ```php - + ``` ## Shipping Carrier Configuration -In the `config.xml` file, define the shipping carrier's core settings, such as its active state, title, and allowed countries. Create `app/code/Vendor/ShippingCarrier/etc/config.xml`: +In the `config.xml` file, define the shipping carrier's core settings, such as its active state, title, and allowed countries. Create `app/code/MageOS/ShippingCarrier/etc/config.xml`: ```xml @@ -53,13 +55,11 @@ In the `config.xml` file, define the shipping carrier's core settings, such as i 1 Custom Shipping Carrier - Custom Carrier - 0 - US,CA - Vendor\ShippingCarrier\Model\Carrier\CustomCarrier - F - 10.00 + Custom Shipping Method Name + 10 0 + 15 + MageOS\ShippingCarrier\Model\Carrier\CustomCarrier @@ -72,29 +72,51 @@ Explanation: - title: The name displayed in the checkout. - name: Internal name of the carrier. - model: The path to the custom shipping carrier model. -- handling_type: Type of handling fee (F for fixed or P for percent). -- handling_fee: The amount of the handling fee. +- shipping_cost: The amount of the handling fee. # Admin Configuration for Carrier -To allow store administrators to configure the shipping method, we define settings in `app/code/Vendor/ShippingCarrier/etc/adminhtml/system.xml.`: +To allow store administrators to configure the shipping method, we define settings in `app/code/MageOS/ShippingCarrier/etc/adminhtml/system.xml`: ```xml - +
- - - - + + + + Magento\Config\Model\Config\Source\Yesno - + - - + + + + + + validate-number validate-zero-or-greater + + + + shipping-applicable-country + Magento\Shipping\Model\Config\Source\Allspecificcountries + + + + Magento\Directory\Model\Config\Source\Country + 1 + + + + Magento\Config\Model\Config\Source\Yesno + shipping-skip-hide + + +
@@ -110,51 +132,83 @@ The core logic for the custom shipping carrier is in the CustomCarrier.php model ```php rateResultFactory = $rateResultFactory; + $this->rateMethodFactory = $rateMethodFactory; + } + + /** + * Custom Shipping Rates Collector + * + * @param RateRequest $request + * @return \Magento\Shipping\Model\Rate\Result|bool + */ public function collectRates(RateRequest $request) { if (!$this->getConfigFlag('active')) { return false; } - /** @var \Magento\Shipping\Model\Rate\Result $result */ - $result = $this->_rateResultFactory->create(); + /** @var Method $method */ + $method = $this->rateMethodFactory->create(); - // Set shipping cost - $shippingPrice = 10.00; - - /** @var \Magento\Quote\Model\Quote\Address\RateResult\Method $method */ - $method = $this->_rateMethodFactory->create(); $method->setCarrier($this->_code); $method->setCarrierTitle($this->getConfigData('title')); $method->setMethod($this->_code); - $method->setMethodTitle('Custom Carrier Method'); + $method->setMethodTitle($this->getConfigData('name')); + $shippingPrice = (float)$this->getConfigData('shipping_cost'); $method->setPrice($shippingPrice); $method->setCost($shippingPrice); + $method->setDataUsingMethod('cost', $shippingPrice); + /** @var Result $result */ + $result = $this->rateResultFactory->create(); $result->append($method); return $result; } - public function getAllowedMethods() + public function getAllowedMethods(): array { return [$this->_code => $this->getConfigData('name')]; } } - ``` Explanation: From 881ab8b8259f9b3affc53625c0175b1d96fce14b Mon Sep 17 00:00:00 2001 From: Nikola Lardev Date: Sat, 28 Sep 2024 01:53:33 +0300 Subject: [PATCH 3/6] DEVDOCS-57 - Add custom shipping carrier update documentation.md --- documentation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/documentation.md b/documentation.md index d10e17d..12bbc26 100644 --- a/documentation.md +++ b/documentation.md @@ -73,6 +73,7 @@ - ## Tutorials & Examples - [Collection of real-world examples, and step-by-step tutorials](/docs/{{version}}/collection-of-real-world-examples-and-step-by-step-tutorials) - [Case studies of problem-solving in Magento 2](/docs/{{version}}/case-studies-of-problem-solving-in-magento-2) + - [Add custom shipping carrier](/docs/{{version}}/add-custom-shipping-carrier) - ## Community & Support - [Get help and support](/docs/{{version}}/how-to-get-help-and-support) - [Community Contribution](/docs/{{version}}/how-to-contribute-to-the-magento-2-community) From 9f6ac4ec35ed2e5e8b3b829ba9fa59a588840c29 Mon Sep 17 00:00:00 2001 From: Fabrizio Balliano Date: Wed, 9 Oct 2024 11:19:40 +0200 Subject: [PATCH 4/6] lint: max 80 chars per line --- add-custom-shipping-carrier.md | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-) diff --git a/add-custom-shipping-carrier.md b/add-custom-shipping-carrier.md index 7fe8ce5..0855c05 100644 --- a/add-custom-shipping-carrier.md +++ b/add-custom-shipping-carrier.md @@ -2,11 +2,15 @@ [TOC] -Mage-OS allows the creation of custom shipping carriers to handle various shipping methods for different carriers or logistics providers. A custom shipping carrier can be added by creating a Mage-OS module and configuring the required fields to handle shipping calculations, carrier configurations, and frontend integration. +Mage-OS allows the creation of custom shipping carriers to handle various shipping methods for +different carriers or logistics providers. A custom shipping carrier can be added by creating a +Mage-OS module and configuring the required fields to handle shipping calculations, +carrier configurations, and frontend integration. ## Module Setup -The first step in adding a custom shipping carrier is creating the necessary directory structure for the Mage-OS module: +The first step in adding a custom shipping carrier is creating the necessary directory structure +for the Mage-OS module: ```bash app/code/MageOS/ShippingCarrier/ @@ -45,7 +49,8 @@ Next, you need to declare your module in `app/code/MageOS/ShippingCarrier/etc/mo ## Shipping Carrier Configuration -In the `config.xml` file, define the shipping carrier's core settings, such as its active state, title, and allowed countries. Create `app/code/MageOS/ShippingCarrier/etc/config.xml`: +In the `config.xml` file, define the shipping carrier's core settings, such as its active state, +title, and allowed countries. Create `app/code/MageOS/ShippingCarrier/etc/config.xml`: ```xml @@ -76,7 +81,8 @@ Explanation: # Admin Configuration for Carrier -To allow store administrators to configure the shipping method, we define settings in `app/code/MageOS/ShippingCarrier/etc/adminhtml/system.xml`: +To allow store administrators to configure the shipping method, we define settings in +`app/code/MageOS/ShippingCarrier/etc/adminhtml/system.xml`: ```xml @@ -124,11 +130,13 @@ To allow store administrators to configure the shipping method, we define settin ``` -This configuration allows administrators to enable the carrier, set a title, and configure a handling fee through the Mage-OS admin panel. +This configuration allows administrators to enable the carrier, set a title, and configure a handling +fee through the Mage-OS admin panel. # Shipping Carrier Model -The core logic for the custom shipping carrier is in the CustomCarrier.php model. This class extends Mage-OS's abstract shipping carrier class and implements the shipping calculation and rates. +The core logic for the custom shipping carrier is in the CustomCarrier.php model. +This class extends Mage-OS's abstract shipping carrier class and implements the shipping calculation and rates. ```php Date: Wed, 9 Oct 2024 11:36:32 +0200 Subject: [PATCH 5/6] more lint --- add-custom-shipping-carrier.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/add-custom-shipping-carrier.md b/add-custom-shipping-carrier.md index 0855c05..6d8cdf8 100644 --- a/add-custom-shipping-carrier.md +++ b/add-custom-shipping-carrier.md @@ -27,6 +27,7 @@ app/code/MageOS/ShippingCarrier/ ``` Create register module file `app/code/MageOS/ShippingCarrier/registration.php` + ```php Date: Wed, 9 Oct 2024 13:31:06 +0300 Subject: [PATCH 6/6] DEVDOCS-57 Fix lint issue --- add-custom-shipping-carrier.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/add-custom-shipping-carrier.md b/add-custom-shipping-carrier.md index 7fe8ce5..0f10315 100644 --- a/add-custom-shipping-carrier.md +++ b/add-custom-shipping-carrier.md @@ -74,7 +74,7 @@ Explanation: - model: The path to the custom shipping carrier model. - shipping_cost: The amount of the handling fee. -# Admin Configuration for Carrier +## Admin Configuration for Carrier To allow store administrators to configure the shipping method, we define settings in `app/code/MageOS/ShippingCarrier/etc/adminhtml/system.xml`: @@ -126,7 +126,7 @@ To allow store administrators to configure the shipping method, we define settin This configuration allows administrators to enable the carrier, set a title, and configure a handling fee through the Mage-OS admin panel. -# Shipping Carrier Model +## Shipping Carrier Model The core logic for the custom shipping carrier is in the CustomCarrier.php model. This class extends Mage-OS's abstract shipping carrier class and implements the shipping calculation and rates. @@ -216,9 +216,9 @@ Explanation: - collectRates(): Calculates shipping rates based on the quote request and returns them. Here, a fixed rate of 10.00 is used. - getAllowedMethods(): Returns the allowed shipping methods for this carrier. -# Frontend Integration +## Frontend Integration Once the backend logic is in place, the custom shipping carrier will automatically appear in the Mage-OS checkout if it's enabled and configured properly. The title and price will be displayed as defined in the carrier configuration. -# Conclusion +## Conclusion This guide walks through the basic setup of a custom shipping carrier in Mage-OS. The carrier integrates with Mage-OS’s shipping framework, allowing you to customize the shipping calculation and display it during the checkout process. You can extend this basic structure to integrate with third-party APIs, offer dynamic shipping rates, or introduce more complex shipping logic based on cart contents or customer information. \ No newline at end of file