Customer Portal Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require oro/customer-portal
   

   Ensure your project extends OroPlatformBundle and OroCustomerBundle in config/bundles.php.

2. First Use Case:

   • Customer Registration: Extend the default registration form by adding custom fields to CustomerUser entity.

     // src/Entity/CustomerUser.php
     use Oro\Bundle\UserBundle\Entity\User;
     use Doctrine\ORM\Mapping as ORM;
     
     #[ORM\Entity]
     class CustomerUser extends User
     {
         #[ORM\Column(type: 'string', length: 255, nullable: true)]
         private ?string $customField = null;
     
         // Getters/Setters...
     }
     

   • Frontend Integration: Override the registration template in templates/OroCustomerBundle/registration/register.html.twig.

3. Key Configuration:

   • Enable customer portal routes in config/routes/oro_customer_portal.yaml:

     oro_customer_portal:
         resource: "@OroCustomerBundle/Resources/config/routing.yml"
         prefix: /
     

Implementation Patterns

Core Workflows

1. Customer Management

• CRUD Operations: Use CustomerUserRepository and CustomerRepository for database interactions.

  $customer = $customerRepository->findOneBy(['email' => 'user@example.com']);
  $customerUser = $customer->getUser();
  

• Address Handling: Leverage CustomerAddress and CustomerUserAddress entities with validation:

  $address = new CustomerAddress();
  $address->setFirstName('John');
  $address->setValidatedAt(new \DateTime()); // Auto-populated via validation
  $customer->addAddress($address);
  $customerRepository->save($customer);
  

2. Frontend Customization

• Layout Overrides: Extend the default layout in templates/OroFrontendBundle/layouts/default/layout.html.twig.

  {# Add custom header #}
  {% block oro_frontend_header %}
      {{ parent() }}
      <div class="custom-header">{{ app.user }}</div>
  {% endblock %}
  

• Theme Configuration: Override theme settings in config/packages/oro_frontend.yaml:

  oro_frontend:
      theme_configuration:
          product_page_template: 'custom_template'
  

3. API Integration

• WSSE Authentication: Secure API endpoints with frontend_api_secured firewall (renamed from frontend_api_wsse_secured in v6.1).

  # config/packages/security.yaml
  firewalls:
      frontend_api_secured:
          pattern: ^/api/frontend
          wsse: true
  

• Absolute URLs in API: Enable absolute URLs for API responses:

  oro_frontend:
      frontend_api:
          use_absolute_urls_for_api: true
  

4. Address Validation

• Third-Party Integration: Implement AddressValidationClientInterface for FedEx/UPS:

  class FedExAddressValidator implements AddressValidationClientInterface
  {
      public function findSuggestions(string $address): array
      {
          // Call FedEx API
          return $suggestions;
      }
  }
  

  Register the service:

  services:
      oro_address_validation.fedex:
          class: App\Service\FedExAddressValidator
          tags:
              - { name: oro_address_validation.channel }
  

• Form Integration: Use FrontendCustomerTypedAddressType in forms:

  $builder->add('shippingAddress', FrontendCustomerTypedAddressType::class, [
      'label' => 'Shipping Address',
      'validation_groups' => ['Default', 'oro_address_validation'],
  ]);
  

5. Email Templates

• Inheritance: Extend base_storefront template for custom emails:

  {# templates/layouts/custom_theme/email-templates/customer_user_welcome_email.html.twig #}
  {% extends 'OroCustomerBundle:Emails:base_storefront.html.twig' %}
  {% block subject %}{{ parent() }} - Welcome to Our Store!{% endblock %}
  

Integration Tips

Symfony Events

• Listen to oro_customer.user.register for post-registration actions:

  $eventDispatcher->addListener('oro_customer.user.register', function (CustomerUserRegisterEvent $event) {
      $user = $event->getUser();
      // Send welcome email or log activity
  });
  

Datagrid Customization

• Extend CurrentCustomerUserViewList for filtered grids:

  $grid->setViewList('current_customer_user_view');
  

SVG Icons

• Enable SVG support in config/packages/oro_frontend.yaml:

  oro_frontend:
      theme_configuration:
          svg_icons_support: true
  

Sticky Elements

• Use sticky-element-view for persistent UI elements:

  require(['orofrontend/js/app/views/sticky-element-view'], function (StickyElementView) {
      new StickyElementView('.sticky-element', {
          offset: 100
      });
  });
  

Gotchas and Tips

Pitfalls

1. Deprecation Warnings

• FontAwesome Removal: Replace fa-icon mixin with SVG icons (e.g., <svg class="icon">...</svg>).
• Dialog Widget: Rename oro/frontend-dialog-widget to oro/dialog-widget in custom templates.
• Sticky Panel: Removed in v6.0; use sticky-element-view instead.

2. Configuration Quirks

• Absolute URLs: Ensure use_absolute_urls_for_api is set to true for API consistency.
• Address Validation: Validate system config options (oro_customer.validate_shipping_addresses__my_account) before enabling validation.

3. Common Issues

• CSRF Tokens: Frontend forms require CSRF tokens. Use oro_form_csrf_token Twig function:

  <input type="hidden" name="_csrf_token" value="{{ oro_form_csrf_token('register') }}">
  

• Theme Inheritance: Override theme.yml in config/packages/oro_frontend.yaml for global theme settings:

  oro_frontend:
      theme_configuration:
          product_page_template: 'custom_template'
  

• Email Template Paths: Place custom templates in templates/layouts/{theme}/email-templates/ for inheritance.

4. Debugging

• Frontend Assets: Clear cache after adding JS/CSS:

  php bin/console oro:asset:install --symlink
  

• API Responses: Check frontend_api.use_absolute_urls_for_api for URL issues in API responses.
• Address Validation: Verify AddressValidationClientInterface implementations are tagged with oro_address_validation.channel.

Extension Points

1. Custom Entities

• Extend CustomerUser or CustomerAddress:

  #[ORM\Entity]
  class CustomCustomerUser extends CustomerUser
  {
      #[ORM\Column(type: 'string', nullable: true)]
      private ?string $loyaltyTier;
  }
  

• Update forms and templates to include new fields.

2. Custom Content Providers

• Create storefront content providers:

  class CustomContentProvider implements ContentProviderInterface
  {
      public function getName(): string
      {
          return 'custom_provider';
      }
  
      public function getConfig(): array
      {
          return ['label' => 'Custom Content'];
      }
  }
  

• Tag the service:

  services:
      app.custom_content_provider:
          class: App\ContentProvider\CustomContentProvider
          tags:
              - { name: oro_frontend.content_provider }
  

3. Custom Email Templates

• Override existing templates or create new ones:

  {# templates/layouts/custom_theme/email-templates/customer_user_reset_password.html.twig #}
  {% extends 'OroCustomerBundle:Emails:customer_user_reset_password.html.twig' %}
  {% block content %}
      {{ parent() }}
      <p>Custom reset instructions here.</p>
  {% endblock %}
  

4. Custom Datagrid Actions

• Add actions to storefront grids:

  $grid->addAction(
      new FrontendResetCollectionAction(
          'reset',
          ['icon' => 'undo']
      )
  );
  

• Configure in theme.yml:

  grid_render_parameters:
      themeOptions:
          actionOptions:
              resetAction:
                  hiddenIfIsNotResettable: true
  

5. Custom Address Validation

• Extend AddressValidationClientInterface for custom providers: