Oro Platform Simple Item Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require clickandmortar/oro-platform-simple-item-bundle
   

   Ensure your oro-platform version aligns with the supported matrix (e.g., 4.2.* for OroPlatform 4.2.*).

2. Post-Install Commands: Run the following in sequence (critical for entity configuration and assets):

   php bin/console cache:clear
   php bin/console doctrine:schema:update --force
   php bin/console oro:entity-config:update --filter="ClickAndMortar*" --force
   php bin/console assets:install --symlink --relative --no-interaction
   php bin/console oro:assets:build --no-interaction
   

3. First Use Case:

   • Define a Simple Item Entity: Extend ClickAndMortar\SimpleItemBundle\Entity\SimpleItem and configure it via YAML (e.g., config/oro/entity/clickandmortar_simple_item.yml):

     ClickAndMortar\SimpleItemBundle\Entity\SimpleItem:
         list:
             title: 'Simple Items'
             icon: icon-list
             items_per_page: 20
     

   • Generate CRUD: Use Oro’s built-in generator or manually create a controller extending SimpleItemController (if provided by the bundle).

Implementation Patterns

Core Workflows

1. Entity Configuration:

   • Grid/Filter Customization: Override default grids via oro_entity_config.yml:

     ClickAndMortar\SimpleItemBundle\Entity\SimpleItem:
         grid:
             columns:
                 name: ~
                 description: ~
     

   • Form Fields: Extend the form type (SimpleItemType) or create a custom one:

     use ClickAndMortar\SimpleItemBundle\Form\Type\SimpleItemType;
     
     $builder->add('customField', TextType::class, ['required' => false]);
     

2. Integration with OroCRM:

   • Relationships: Link SimpleItem to Oro entities (e.g., Account, Product) via many-to-one/many-to-many associations:

     /**
      * @ORM\ManyToOne(targetEntity="Oro\AccountBundle\Entity\Account")
      */
     private $account;
     

   • Business Logic: Hook into Oro’s workflows (e.g., prePersist, preUpdate) via Doctrine lifecycle callbacks or Oro’s event system:

     $entityManager->getEventManager()->addEventListener(
         \Doctrine\ORM\Events::prePersist,
         [$this, 'onPrePersist']
     );
     

3. API/REST:

   • Enable API access via oro_api.yml:

     ClickAndMortar\SimpleItemBundle\Entity\SimpleItem:
         api:
             enabled: true
             collection:
                 fields:
                     - id
                     - name
     

4. Localization:

   • Translate labels/placeholders using Oro’s translation system:

     php bin/console oro:translation:dump
     

     Add translations in translations/messages.en.yml:

     ClickAndMortar\SimpleItemBundle:
         simple_item.name: 'Item Name'
     

Gotchas and Tips

Pitfalls

1. Schema Updates:

   • Mistake: Skipping doctrine:schema:update --force after adding fields.
   • Fix: Always run schema updates in a staging environment first. Use --dry-run to preview changes:

     php bin/console doctrine:schema:update --dry-run
     

2. Entity Config Caching:

   • Mistake: Changes to oro_entity_config.yml not reflecting.
   • Fix: Clear Oro’s entity config cache:

     php bin/console oro:entity-config:update --force
     

3. Asset Pipeline:

   • Mistake: JavaScript/CSS not loading after bundle installation.
   • Fix: Ensure assets:install and oro:assets:build are run. For development, use:

     php bin/console assets:install --watch
     

4. Version Conflicts:

   • Mistake: Using 4.2.* bundle with OroPlatform 4.1.*.
   • Fix: Pin versions explicitly in composer.json:

     "require": {
         "clickandmortar/oro-platform-simple-item-bundle": "4.2.*",
         "oro/platform": "4.2.*"
     }
     

Debugging Tips

1. Symfony Profiler:

   • Enable to inspect entity configurations, queries, and events:

     // config/packages/dev/oro_platform.yaml
     oro_platform:
         profiler: true
     

2. Doctrine Logging:

   • Log SQL queries to debug schema issues:

     // config/packages/dev/doctrine.yaml
     doctrine:
         dbal:
             logging: true
             profiling: true
     

3. Event Listeners:

   • Dump dispatched events to debug workflows:

     php bin/console debug:event-dispatcher
     

Extension Points

1. Custom Fields:

   • Add fields dynamically via SimpleItemExtension (if supported) or override the form type:

     public function buildForm(FormBuilderInterface $builder, array $options)
     {
         $builder->add('priority', EntityType::class, [
             'class' => Priority::class,
             'property' => 'name',
         ]);
     }
     

2. Grid Actions:

   • Extend the default grid actions (e.g., "Edit", "Delete") via oro_entity_config.yml:

     ClickAndMortar\SimpleItemBundle\Entity\SimpleItem:
         grid:
             actions:
                 view: ~
                 custom_action:
                     type: navigate
                     label: 'custom.label'
                     icon: icon-custom
                     route: clickandmortar_simpleitem_view
                     acl: true
     

3. Validation:

   • Add custom validation constraints to the entity:

     use Symfony\Component\Validator\Constraints as Assert;
     
     /**
      * @Assert\Length(max=255)
      */
     private $name;
     

4. API Extensions:

   • Customize API responses via oro_api.yml or create a custom serializer:

     ClickAndMortar\SimpleItemBundle\Entity\SimpleItem:
         api:
             enabled: true
             item:
                 fields:
                     - { name: 'fullName', type: 'string', data_name: 'name' }