Orocommerce Collect On Delivery Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require aivus/orocommerce-collect-on-delivery
   

   Ensure OroCommerce is already installed and configured in your project.

2. Enable Bundle: Add to config/bundles.php:

   Aivus\OroCommerceCollectOnDeliveryBundle\AivusOroCommerceCollectOnDeliveryBundle::class => ['all' => true],
   

3. Database Migration: Run:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

4. First Use Case:

   • Navigate to OroCommerce Admin Panel → Sales → Payment Methods.
   • Locate the "Collect on Delivery" payment method and enable it.
   • Test by creating an order with this payment method selected.

Implementation Patterns

Core Workflows

1. Payment Method Integration:

   • Extend or override the default payment method logic via event listeners (e.g., oro_integration.payment_method.update).
   • Example listener to validate COD eligibility:

     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     use Oro\Bundle\PaymentBundle\Event\PaymentMethodUpdateEvent;
     
     class CodValidationSubscriber implements EventSubscriberInterface
     {
         public static function getSubscribedEvents()
         {
             return [
                 'oro_integration.payment_method.update' => 'onPaymentMethodUpdate',
             ];
         }
     
         public function onPaymentMethodUpdate(PaymentMethodUpdateEvent $event)
         {
             $method = $event->getMethod();
             if ($method->getCode() === 'cod' && $method->isActive()) {
                 $event->setActive($this->isCodEligible($event->getOrder()));
             }
         }
     
         private function isCodEligible(Order $order): bool
         {
             // Custom logic (e.g., min order amount, specific regions)
             return $order->getTotal() >= 50;
         }
     }
     

2. Order Processing:

   • Use the oro_order.payment event to handle COD-specific logic (e.g., marking orders as "pending" until delivery confirmation).
   • Example:

     use Oro\Bundle\OrderBundle\Entity\Order;
     use Oro\Bundle\OrderBundle\Event\OrderPaymentEvent;
     
     $event->getOrder()->setPaymentStatus('pending_cod');
     

3. Frontend Integration:

   • Ensure the COD option is visible in checkout via Symfony Twig templates (oro_order_checkout_payment.html.twig).
   • Override the template if needed:

     {% extends 'OroOrderBundle:OrderCheckout:payment.html.twig' %}
     {% block cod_option %}
         {% if isCODEligible(order) %}
             <div class="cod-option">
                 <input type="radio" name="payment_method" value="cod" id="cod">
                 <label for="cod">{{ 'oro.order.payment_method.cod'|trans }}</label>
             </div>
         {% endif %}
     {% endblock %}
     

4. Delivery Confirmation:

   • Implement a custom workflow or API endpoint to mark COD payments as "paid" upon delivery confirmation.
   • Example API route (config/routes.yaml):

     aivus_cod_confirmation:
         path: /api/cod/confirm/{orderId}
         controller: Aivus\OroCommerceCollectOnDeliveryBundle\Controller\CodConfirmationController::confirm
         methods: [POST]
     

Gotchas and Tips

Common Pitfalls

1. Database Conflicts:

   • The bundle adds a cod_payment_method table. Ensure no naming collisions with existing tables.
   • Fix: Rename the table in the bundle’s Resources/config/doctrine if needed.

2. Payment Status Mismatch:

   • Orders with COD may appear as "unpaid" in reports. Override the getPaymentStatus() method in your Order entity or use a custom query builder to filter COD orders:

     $queryBuilder->andWhere('o.paymentStatus != :codStatus')
                  ->setParameter('codStatus', 'pending_cod');
     

3. Frontend Visibility:

   • The COD option may not appear if the bundle’s assets (JS/CSS) aren’t compiled. Run:

     php bin/console assets:install
     yarn encore dev
     

4. Archived Package Risks:

   • The package is archived with no stars or activity. Validate functionality by:
     • Checking the src/DependencyInjection/AivusOroCommerceCollectOnDeliveryExtension.php for configuration options.
     • Reviewing the EventListener/CodListener.php for core logic.

Debugging Tips

1. Enable Debugging: Add to config/packages/dev/oro_integration.yaml:

   oro_integration:
       debug: true
   

2. Log COD Events: Use Monolog to track COD-related events:

   $this->logger->info('COD Payment Initiated', ['order_id' => $order->getId()]);
   

3. Override Bundle Classes: If the bundle’s logic is insufficient, extend its services via config/services.yaml:

   Aivus\OroCommerceCollectOnDeliveryBundle\Service\CodService:
       class: App\Service\CustomCodService
       arguments:
           - '@=service("aivus.oro_commerce_collect_on_delivery.cod_service").originalService'
   

Extension Points

1. Custom Validation Rules: Extend the CodValidator service to add business logic (e.g., blacklisted products):

   class CustomCodValidator extends CodValidator
   {
       public function isValid(Order $order): bool
       {
           if (!$this->isMinAmountMet($order)) {
               return false;
           }
           return !$this->hasBlacklistedProduct($order);
       }
   
       private function hasBlacklistedProduct(Order $order): bool
       {
           // Custom logic
       }
   }
   

2. Delivery Confirmation Workflow: Create a custom command to bulk-process COD confirmations:

   php bin/console aivus:cod:confirm --order-id=123
   

3. Multi-Currency Support: Ensure COD is disabled for non-supported currencies by overriding the getSupportedCurrencies() method in the payment method entity.