planeMapper/.claude/skills/oro-backend-dev/SKILL.md

---
name: oro-backend-dev
description: OroCommerce backend development reference covering entities, CRUD, datagrids, message queue, bundles, security, system configuration, workflows, cron, and integrations. Use when writing PHP code for Oro bundles, creating entities, building controllers, configuring datagrids, or implementing backend business logic.
---

# OroCommerce Backend Developer

Reference for backend PHP development on OroCommerce/OroPlatform.
Full docs: https://doc.oroinc.com/backend/

## Bundle Structure

All custom code lives in bundles under `src/Acme/Bundle/{Name}Bundle/`.
Bundle priority > 210 to load after Oro core bundles.

```
AcmeExampleBundle/
    AcmeExampleBundle.php            # extends Bundle
    DependencyInjection/
        AcmeExampleExtension.php     # loads services.yml
        Configuration.php               # config tree (if needed)
    Resources/
        config/
            oro/
                bundles.yml             # { name: FQCN, priority: 255 }
                datagrids.yml
                navigation.yml
                workflows.yml
                features.yml
                actions.yml             # operations/action buttons
                processes.yml           # entity lifecycle automation
                search.yml              # search index config
                placeholders.yml        # back-office UI injection
                dashboards.yml          # dashboard widgets
                api.yml                 # API entity config
                acls.yml                # YAML-based ACL definitions
            services.yml
        translations/messages.en.yml
    Entity/
    Controller/
    Form/Type/
    EventListener/
    Migrations/Schema/
    Tests/Unit/
```

Auto-registration via `Resources/config/oro/bundles.yml`:

```yaml
bundles:
    - { name: Acme\Bundle\ExampleBundle\AcmeExampleBundle, priority: 255 }
```

## Entities

Use PHP 8 ORM attributes. Oro entities need `#[Config]` for ACL, routing, and extend support.

```php
#[ORM\Entity]
#[ORM\Table(name: 'acme_example')]
#[Config(
    routeName: 'acme_example_index',
    routeView: 'acme_example_view',
    defaultValues: ['entity' => ['icon' => 'fa-cube']]
)]
class Example implements ExtendEntityInterface
{
    use ExtendEntityTrait;

    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column(type: 'integer')]
    private ?int $id = null;
}
```

### #[ConfigField] Attribute

Use `#[ConfigField]` on individual properties for field-level config:

```php
#[ORM\Column(name: 'subject', type: 'string', length: 255)]
#[ConfigField(defaultValues: [
    'dataaudit' => ['auditable' => true],
    'importexport' => ['identity' => true],
])]
private $subject;
```

Config commands: `oro:entity-config:update`, `oro:entity-config:cache:clear`,
`oro:entity-config:debug "FQCN"`.

### Extend Existing Oro Entities

Add fields to Oro entities via migrations with `oro_options`:

```php
$table = $schema->getTable('oro_order');
$table->addColumn('custom_field', 'string', [
    'oro_options' => [
        'extend' => ['is_extend' => true, 'owner' => ExtendScope::OWNER_CUSTOM],
        'entity' => ['label' => 'Custom Field'],
    ]
]);
```

Never modify Oro entity classes directly. Clear extend cache after:
`php bin/console oro:entity-extend:cache:clear`

## Migrations

Implement `Oro\Bundle\MigrationBundle\Migration\Migration` (incremental) or
`Installation` (full schema). Place in `Migrations/Schema/v{N}/`.

Run: `php bin/console oro:migration:load`

## Datagrids

Configure in `Resources/config/oro/datagrids.yml`. Key sections:
- `source`: ORM query (select, from, join); protect with `acl_resource`
- `columns`: display config with labels and `frontend_type`
- `sorters`: sortable columns with `data_name`
- `filters`: filter widgets (string, datetime, entity, boolean)
- `properties` + `actions`: row links (view, edit, delete); hide with `acl_resource`

Set `extended_entity_name` if entity supports dynamic fields.

### Customizing Existing Datagrids

Two approaches:
1. **YAML override**: add columns/sorters/filters in your bundle's `datagrids.yml`
   (Oro merges configs from all bundles by priority).
2. **Event listener**: listen to `oro_datagrid.datagrid.build.before.{grid-name}`
   and `oro_datagrid.orm_datasource.result.after.{grid-name}` for complex
   modifications (joins, computed columns, post-fetch decoration).

Custom filter types: implement filter class, register with
`oro_filter.extension.orm_filter.filter` tag.

## CRUD Controllers

Pattern: FormType + Controller + Twig templates.

- Controller uses `#[Acl]` attributes for permissions
- `UpdateHandlerFacade` handles form submission
- Templates extend `@OroUI/actions/{index,view,update}.html.twig`
- Routing in `Resources/config/oro/routing.yml`

## Doctrine Entity Listeners

For entity-specific event hooks (postPersist, preUpdate, postUpdate), use Doctrine entity listeners
instead of generic event subscribers. Register via service tags:

```yaml
services:
    acme.entity_listener.customer_sync:
        class: Acme\Bundle\EclipseBundle\EventListener\CustomerSync
        arguments: ['@oro_message_queue.client.message_producer', '@logger']
        tags:
            - { name: doctrine.orm.entity_listener, entity_manager: default, entity: Oro\Bundle\CustomerBundle\Entity\Customer, event: preUpdate }
            - { name: doctrine.orm.entity_listener, entity_manager: default, entity: Oro\Bundle\CustomerBundle\Entity\Customer, event: postUpdate }
            - { name: oro_featuretoggle.feature, feature: acme_eclipse_sync }
        calls:
            - [ addFieldToListenChanges, [ 'name' ] ]
            - [ addFieldToListenChanges, [ 'email' ] ]
```

Abstract base pattern for field-level change tracking:

```php
abstract class AbstractEntityModificationListener
{
    protected array $entitiesIdToSync = [];
    protected array $fieldsToListenChanges = [];

    public function __construct(
        protected MessageProducerInterface $messageProducer,
        protected LoggerInterface $logger
    ) {}

    public function addFieldToListenChanges(string $value): void
    {
        if (!in_array($value, $this->fieldsToListenChanges)) {
            $this->fieldsToListenChanges[] = $value;
        }
    }

    public function preUpdate(object $entity, PreUpdateEventArgs $event): void
    {
        foreach ($this->fieldsToListenChanges as $fieldName) {
            if ($event->hasChangedField($fieldName)) {
                $this->entitiesIdToSync[$entity->getId()] = $entity->getId();
                break;
            }
        }
    }
}
```

## Message Queue

Processors implement `MessageProcessorInterface` + `TopicSubscriberInterface`.
Return `self::ACK`, `self::REJECT`, or `self::REQUEUE`.
Tag service: `oro_message_queue.client.message_processor`.
Use `JobRunner::createUnique()` for non-duplicate jobs.

Transport: DBAL (default, polls DB) or RabbitMQ (EE, via `ORO_MQ_DSN`).

### Topic Registration Shorthand

Use `_defaults` in `mq_topics.yml` to auto-tag all topic classes:

```yaml
services:
    _defaults:
        tags:
            - { name: oro_message_queue.topic }

    Acme\Bundle\EclipseBundle\Async\Topic\SyncOrderStatusTopic: ~
    Acme\Bundle\EclipseBundle\Async\Topic\SyncOriginOrdersTopic: ~
    Acme\Bundle\CpnBundle\Async\Topic\SyncCpnFromEclipseTopic: ~
```

### Processor Auto-Tagging via TopicSubscriberInterface

Alternative to specifying `topicName` in the service tag -- implement `TopicSubscriberInterface`
and use `_instanceof` in `mq_processors.yml`:

```yaml
services:
    _instanceof:
        Oro\Component\MessageQueue\Client\TopicSubscriberInterface:
            tags:
                - { name: oro_message_queue.client.message_processor }

    acme.eclipse.processor.sync_order_status:
        class: Acme\Bundle\EclipseBundle\Async\SyncOrderStatusProcessor
        parent: acme.async.abstract_processor
```

The processor class must implement `getSubscribedTopics()` returning the topic name.

### Abstract Processor Pattern

For processors sharing common patterns (job uniqueness, redelivery limits, feature toggle):

```php
abstract class AbstractAcmeProcessor implements MessageProcessorInterface, TopicSubscriberInterface
{
    use FeatureCheckerHolderTrait;
    public const MAX_REDELIVERY_COUNT = 5;

    public function __construct(
        protected JobRunner $jobRunner,
        protected ManagerRegistry $registry,
        protected LoggerInterface $logger
    ) {}

    public function process(MessageInterface $message, SessionInterface $session): string
    {
        if (!$this->isFeaturesEnabled()) {
            return self::REJECT;
        }

        $redeliveryCount = $message->getProperty(RedeliveryMessageExtension::PROPERTY_REDELIVER_COUNT);
        if ($redeliveryCount !== null && $redeliveryCount >= static::MAX_REDELIVERY_COUNT) {
            $this->logger->critical('Redelivery limit reached', ['message' => $message]);
            return self::REJECT;
        }

        $result = $this->jobRunner->runUnique(
            $message->getMessageId(),
            $this->getJobName($message->getBody()),
            fn() => $this->processMessage($message->getBody())
        );

        return $result ? self::ACK : self::REJECT;
    }

    abstract protected function processMessage(array $body): bool;
    abstract protected function getJobName(array $body): string;
}
```

## Security & ACL

Entity ACL via `#[Config(defaultValues: ['security' => [...], 'ownership' => [...]])]`.
Controller ACL via `#[Acl(id: '...', type: 'entity', class: '...', permission: 'VIEW')]`.
Permissions: VIEW, CREATE, EDIT, DELETE, ASSIGN.

Also available:
- `#[AclAncestor('existing_acl_id')]` to reuse ACL definitions on controllers.
- `acls.yml` for YAML-based ACL definitions.
- `acl_resource` on navigation items to hide unauthorized menus.
- `is_granted('acl_id', entity)` in Twig for conditional rendering.
- `AclHelper::apply($queryBuilder)` for ACL-filtered ORM queries.

## System Configuration

Define settings via `SettingsBuilder::append()` in `Configuration.php`.
UI form in `Resources/config/oro/system_configuration.yml` (groups, fields, tree).
Access: `$configManager->get('acme_bundle.setting_name')`.

## Feature Toggles

Define in `Resources/config/oro/features.yml` with label, toggle (config key),
routes, navigation_items, api_resources, mq_topics.
Services implement `FeatureToggleableInterface` + `FeatureCheckerHolderTrait`.
Twig: `{% if feature_enabled('feature_name') %}`.

## Workflows

YAML-based state machines in `Resources/config/oro/workflows.yml`.
Define steps, attributes, transitions, conditions, and actions.
Triggers: user-initiated, cron-based, or entity-event-based.
Load: `php bin/console oro:workflow:definitions:load`

## Cron Jobs

Commands implement `CronCommandScheduleDefinitionInterface`.
Namespace: `oro:cron:acme:{name}`.
`getDefaultDefinition()` returns crontab string.
Load schedule: `php bin/console oro:cron:definitions:load`

## Navigation

`Resources/config/oro/navigation.yml` defines menu items and tree placement.
Trees: `application_menu` (main bar), `usermenu`, `shortcuts`.

## Import/Export

Register processors tagged `oro_importexport.processor` (type: export/import).
Provide template fixtures for download-template feature.
Buttons: `{% include '@OroImportExport/ImportExport/buttons_from_configuration.html.twig' %}`

## Logging

Use Monolog (PSR-3 LoggerInterface). Inject `@logger` via constructor.
Use `{placeholders}` in messages, pass variables in context array.
Pass exceptions as `['exception' => $e]`. Never log sensitive data.
Custom channels: tag with `{ name: monolog.logger, channel: acme_{bundle} }`.

## Email Templates

Create Twig templates in `Resources/emails/` with metadata comments
(`@entityName`, `@subject`, `@name`, `@isSystem`).
Load via fixture extending `AbstractEmailFixture`.
Send via `EmailModelSender::send()`.

## Commerce Extensions

- **Payment methods**: Settings entity + Transport + PaymentMethod + Provider + ViewProvider
  (https://doc.oroinc.com/backend/extend-commerce/payment/)
- **Shipping methods**: Settings entity + Transport + ShippingMethod + Types + Provider
  (https://doc.oroinc.com/backend/extend-commerce/shipping/)
- **Checkout**: extend or override the `b2b_flow_checkout` workflow
  (https://doc.oroinc.com/backend/extend-commerce/checkout-customization-methods/)

## Testing

| Level | Base class | Location |
|---|---|---|
| Unit | PHPUnit TestCase | Tests/Unit/ |
| Functional | WebTestCase | Tests/Functional/ |
| API | RestJsonApiTestCase | Tests/Functional/Api/ |
| BDD | Behat features | Tests/Behat/Features/ |

## Operations (Actions)

Define custom operations in `Resources/config/oro/actions.yml` for entity
buttons, datagrid mass actions, and route-based actions. Operations support
preconditions, conditions, form dialogs, and inline actions.

Disable default CRUD operations with `exclude_entities`; extend/substitute
with `extends` and `substitute_operation`.

Validate: `php bin/console oro:action:configuration:validate`

## Scopes

Scopes provide context-dependent behavior (customer, website, customer group).
Use `ScopeManager` to find/create scopes. Implement `ScopeCriteriaProviderInterface`
and register with `oro_scope.provider` tag. Apply scope criteria to queries with
`ScopeCriteria::applyToJoinWithPriority()`. Used by visibility, pricing, content.

## Dashboards

Create widgets in `Resources/config/oro/dashboards.yml`. Widget template extends
`@OroDashboard/Dashboard/widget.html.twig`. Route: `oro_dashboard_widget` with
`bundle` and `name` parameters (maps to `{Bundle}:Dashboard:{name}`).

## Data Audit

Enable change logging via `'dataaudit' => ['auditable' => true]` in `#[Config]`
on entity class and `#[ConfigField]` on individual fields.
Implements `AuditAdditionalFieldsInterface` for extra fields in audit log.
History accessible at `/audit/history/{entity}/{id}` and via REST API.

## Data Fixtures

Place in `Migrations/Data/ORM/` (main) or `Migrations/Data/Demo/ORM/` (demo).
Implement `FixtureInterface::load(ObjectManager $manager)`.
Use `OrderedFixtureInterface` for ordering, `DependentFixtureInterface` for deps.
Load: `php bin/console oro:migration:data:load` (add `--fixtures-type=demo`).

## File Storage

Oro uses KnpGaufretteBundle for filesystem abstraction (local FS or GridFS).
Two adapter types: `public` (direct URL via `/media/`) and `private` (no web access).
Register filesystems in `Resources/config/oro/app.yml`, create `FileManager`
services as children of `oro_gaufrette.file_manager`.
GridFS configured via `oro_gridfs` adapter or `gaufrette_adapter.*` parameters.

## Reports & Segments

Reports are datagrid-based. Configure in `datagrids.yml` with `source.acl_resource:
oro_report_view`, aggregations, totals, and `options.export: true`.
Add to Reports menu via `navigation.yml`.
Segments: dynamic (real-time) or static (snapshot in `oro_segment_snapshot`).

## Search Index

Configure `Resources/config/oro/search.yml` to make entities searchable.
Define alias, fields (target_type: text/integer/double/datetime), relation_fields,
route for result links, and search_template for custom rendering.
Reindex: `php bin/console oro:search:reindex --class="FQCN"`.

## Processes

Automated entity lifecycle tasks in `Resources/config/oro/processes.yml`.
Triggers fire on Doctrine events (create/update/delete) or cron schedules.
Can run immediately or deferred via MQ with priority and time_shift.
Use `exclude_definitions` to prevent recursion.
Load: `php bin/console oro:process:configuration:load`.

## Access Rules

Custom query-level access restrictions beyond standard ACL.
Implement `AccessRuleInterface` (isApplicable + process methods).
Register with `oro_security.access_rule` tag (type, entityClass, permission).
Modifies ORM queries via `AclHelper::apply()` + `AccessRuleWalker`.

## Field ACL

Field-level permissions (VIEW, CREATE, EDIT per field).
Enable with `'security' => ['field_acl_supported' => true]` in `#[Config]`.
Limit per-field permissions via `#[ConfigField(defaultValues: ['security' => ['permissions' => 'VIEW;CREATE']])]`.
Check: `isGranted('VIEW', new FieldVote($entity, 'fieldName'))`.
Twig: `{% if is_granted('VIEW', entity, 'fieldName') %}`.

## Notification Alerts

Log integration/sync errors visible in admin UI (System > Alerts).
Register `NotificationAlertManager` service with source and resource type.
Alerts track: source, resource, alert type, operation, step, item ID, external ID.
CLI: `oro:notification:alerts:list`, `oro:notification:alerts:cleanup`.
Auto-cleanup of resolved alerts older than 30 days via cron.

## Placeholders

Inject content into back-office page regions via `Resources/config/oro/placeholders.yml`.
Define items with template, order, and optional `applicable` filter.
Common targets: `oro_view_additional_data`, `oro_widget_side_bar`.
Different from Layout Updates (storefront only).

## Organization Types (EE)

Define in `Resources/config/oro/organization_types.yml`. Assign feature
restrictions per organization. Strategies: `exclude_list` (default) or
`include_list`. Verify: `php bin/console oro:organization-type:config:debug`.

## Additional Resources

- For detailed entity extension patterns, see [reference-entities.md](reference-entities.md)
- For integration patterns, see [reference-integrations.md](reference-integrations.md)
- For cloud deployment and operations, see the `oro-cloud` skill