Platform Laravel Package

Getting Started

Minimal Setup

1. Install via Composer Requires a Symfony-based application (e.g., platform-application skeleton).

   composer create-project orocrm/platform-application my-app
   

   • Follow the official docs for DB/config setup.

2. First Use Case: Scaffold a Basic Entity Use Oro’s CLI or YAML-based definitions to create a Product entity:

   php bin/console oro:generate:entity Product
   

   • Define fields in app/config/oro/entity-definitions.yml:

     Oro\Bundle\EntityBundle\Entity\Entity:
         fields:
             name: ~
             price: { type: decimal }
     

3. Key Initial Commands

   • php bin/console oro:navigation:update → Sync UI navigation.
   • php bin/console oro:entity:generate → Auto-generate CRUD.
   • php bin/console oro:workflow:generate → Bootstrap workflows.

Implementation Patterns

Core Workflows

1. Entity-Centric Development

   • Field Types: Extend with custom types (e.g., oro_entity_config for dynamic fields).

     // app/Resources/OroEntityConfig/fields.yml
     Oro\Bundle\ProductBundle\Entity\Product:
         fields:
             sku: { type: string, form_type: oro_form_field_text }
     

   • Business Logic: Use events (oro_entity.pre_update, oro_entity.post_remove) or services (oro_entity.manager).

2. UI Customization

   • Layouts: Override templates in app/Resources/OroLayout/ (e.g., default.html.twig).
   • Themes: Extend via app/Resources/public/css/ or SASS variables in app/Resources/OroTheme/.
   • Dynamic Menus: Configure in app/config/oro/navigation.yml:

     items:
         product_index:
             label: Products
             route: oro_product_index
             position: 10
     

3. API Integration

   • JSON:API: Auto-generated via oro_rest bundle. Extend with custom serializers:

     // src/Acme/ProductBundle/Serializer/ProductNormalizer.php
     use Oro\Bundle\SoapBundle\Serializer\Normalizer\AbstractNormalizer;
     class ProductNormalizer extends AbstractNormalizer { ... }
     

   • GraphQL: Use oro_graphql for complex queries (requires oro-platform-graphql package).

4. Permissions & Security

   • Scopes: Restrict data access via oro_entity_config:

     Oro\Bundle\ProductBundle\Entity\Product:
         scopes:
             default: { label: Default, type: entity }
             mine: { label: My Products, type: user }
     

   • ACL: Define rules in app/config/oro/acl.yml:

     Oro\Bundle\ProductBundle\Entity\Product:
         view: ROLE_USER
         edit: ROLE_ADMIN
     

5. Workflows & Automation

   • State Machines: Define workflows in app/config/oro/workflow.yml:

     Oro\Bundle\ProductBundle\Entity\Product:
         workflows:
             product_lifecycle:
                 steps:
                     draft: { label: Draft }
                     published: { label: Published, transition: publish }
     

   • Triggers: Use oro_workflow events (e.g., oro_workflow.entity.transition).

Gotchas and Tips

Pitfalls

1. Entity Generation Quirks

   • Issue: oro:entity:generate may skip fields if Entity class isn’t properly namespaced. Fix: Ensure use Oro\Bundle\EntityBundle\Entity\Entity; is present.
   • Issue: Custom field types require oro_entity_config updates and a FormType class. Fix: Implement Oro\Bundle\EntityConfigBundle\Form\Type\AbstractEntityFieldType.

2. Caching Headaches

   • Problem: Layout/theme changes don’t reflect until cache is cleared. Solution: Use php bin/console cache:clear or debug with:

     php bin/console debug:config oro_layout
     

3. Permission Overrides

   • Gotcha: ACL rules in acl.yml override Symfony’s voter system. Test with:

     php bin/console debug:acl
     

4. API Serialization

   • Issue: Custom fields may not serialize by default. Fix: Extend oro_rest serializers or use @ORM\Expose annotations.

5. Workflow Debugging

   • Tip: Enable workflow logging in app/config/config.yml:

     oro_workflow:
         debug: true
     

   • Common Error: Missing transition definitions in workflow YAML.

Pro Tips

1. Dynamic Field Types Use oro_entity_config to toggle fields at runtime:

   Oro\Bundle\ProductBundle\Entity\Product:
       fields:
           discount:
               form_type: oro_form_field_percentage
               enabled: false  # Disable via config
   

2. Bulk Operations Leverage oro_entity batch processing:

   $entityManager = $this->get('oro_entity.entity_manager');
   $batch = $entityManager->getRepository(Product::class)->findAll();
   $entityManager->updateBatch($batch, ['price' => 19.99]);
   

3. Localization Translate labels via oro_translation:

   # app/Resources/translations/messages.en.yml
   Oro\Bundle\ProductBundle: Product
   Oro\Bundle\ProductBundle:Field:price: Price (USD)
   

4. Testing Use Oro’s test utilities:

   $this->get('oro_entity.entity_manager')->getRepository(Product::class)->create(['name' => 'Test']);
   $this->get('oro_workflow.workflow_manager')->transition($entity, 'publish');
   

5. Extending OroCRM/OroCommerce

   • Tip: Override bundles in composer.json:

     "replace": {
         "orocrm/product": "path/to/your-bundle"
     }
     

   • Tip: Use oro:platform:update to sync core changes post-upgrade.

6. Performance

   • Query Optimization: Use oro_entity DQL helpers:

     $qb = $entityManager->getRepository(Product::class)->createQueryBuilder('p');
     $qb->select('p.id, p.name')->where('p.price > :min')->setParameter('min', 10);
     

   • Avoid N+1: Enable Doctrine’s ORM\Query\Query::HYDRATE_ARRAY for bulk loads.