Oro Platform Generic Address Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require "clickandmortar/oro-platform-generic-address-bundle" "1.1.*"
   

   Ensure compatibility with your OroPlatform version (e.g., 1.1.* for OroPlatform 4.1.*).

2. Enable JS Routing: Update config/packages/fos_js_routing.yaml:

   fos_js_routing:
       routes_to_expose: [..., 'candm_*', ...]
   

   Then regenerate routes:

   php bin/console fos:js-routing:dump
   

3. Database & Config Update:

   php bin/console doctrine:schema:update --force
   php bin/console oro:entity-config:update --filter="ClickAndMortar*" --force
   php bin/console oro:migration:data:load --bundles="ClickAndMortarGenericAddressBundle"
   

4. First Use Case: Add an addressable field to an entity (e.g., Customer) via Oro’s Entity Configuration:

   php bin/console oro:entity-config:add-field --entity=Customer --field=addresses --type=address
   

   Verify the field appears in the admin UI under the entity’s form.

Implementation Patterns

Core Workflows

1. Entity Integration:

   • Add Address Field: Use oro:entity-config:add-field to attach an addressable field to any entity (e.g., Order, Contact). Example:

     php bin/console oro:entity-config:add-field --entity=Order --field=shippingAddress --type=address
     

   • Field Configuration: Customize via YAML (e.g., config/packages/clickandmortar_generic_address.yaml):

     oro_entity_config:
         entity_definitions:
             Customer:
                 fields:
                     addresses:
                         form:
                             type: address
                             options:
                                 label: "Customer Addresses"
                                 required: false
     

2. Frontend Usage:

   • The bundle provides a generic address picker (JS-based) for selecting/saving addresses.
   • Expose routes for AJAX calls (e.g., candm_address_save, candm_address_list).
   • Use Twig to render the address field:

     {{ form_row(form.addresses) }}
     

3. Data Migration:

   • Pre-populate addresses via data migrations:

     php bin/console oro:migration:data:load --bundles="ClickAndMortarGenericAddressBundle"
     

   • Custom migrations can extend ClickAndMortar\GenericAddressBundle\Migrations\Data\ORM\LoadGenericAddressData.

4. API Exposure:

   • Addresses are auto-exposed via Oro’s REST API if the entity is API-enabled.
   • Customize serialization with @ApiResource annotations or oro_api config.

Gotchas and Tips

Pitfalls

1. Route Conflicts:

   • Ensure fos_js_routing exposes only candm_* routes to avoid JS conflicts.
   • Debug with:

     php bin/console debug:router | grep candm_
     

2. Entity Config Caching:

   • After adding/updating fields, clear config cache:

     php bin/console cache:clear
     php bin/console oro:entity-config:update --filter="ClickAndMortar*" --force
     

3. Database Schema:

   • The bundle creates a generic address table and a join table (entity_address) for many-to-many relationships.
   • Manual schema changes may break migrations. Use --force cautiously.

4. Validation:

   • Address fields inherit Oro’s validation (e.g., NotBlank for required fields).
   • Customize via oro_entity_config under fields.{field}.validation_groups.

Debugging Tips

• Check Logs:

  php bin/console debug:config clickandmortar_generic_address
  

• Frontend Errors: Verify JS routes are dumped (public/js/routing.js) and the address picker is loaded via require('candm-address') in your asset pipeline.

Extension Points

1. Custom Address Types: Extend the base Address entity by creating a subclass (e.g., BillingAddress) and override the bundle’s templates.

2. Field Customization: Override Twig templates in templates/ClickAndMortarGenericAddressBundle/ to modify the address picker UI.

3. Event Listeners: Hook into Oro’s lifecycle events (e.g., prePersist, preUpdate) to validate or modify addresses:

   use ClickAndMortar\GenericAddressBundle\Event\AddressEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class MyAddressSubscriber implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               AddressEvent::PRE_SAVE => 'onAddressPreSave',
           ];
       }
   }
   

4. API Customization: Use Oro’s oro_api config to add/remove address fields from API responses:

   oro_api:
       rest:
           Customer:
               attributes:
                   addresses: ~
   

```markdown
### Pro Tips
- **Bulk Address Updates**:
  Use Oro’s `oro:data-fixtures:load` to seed addresses for testing:
  ```bash
  php bin/console oro:data-fixtures:load --fixtures="vendor/clickandmortar/oro-platform-generic-address-bundle/Migrations/Data/Fixtures/ORM/LoadAddressData"

• Performance: For large datasets, add indexes to the entity_address join table:

  CREATE INDEX idx_entity_address_entity_id ON entity_address(entity_id);
  

• Localization: Address fields support Oro’s translation system. Extend translations in translations/messages.{locale}.yml:

  candm:
      address:
          street: "Street Address"
          city: "City"