Getting Started

Minimal Setup

Install the CRM Application:
```
composer create-project orocrm/crm-application my_crm_project
cd my_crm_project
```
This provides a pre-configured Laravel/Symfony-based environment with OroCRM integrated.
Configure Database & Environment: Update .env with your database credentials and run:
```
php bin/console oro:crm:install
```
This sets up the database schema, fixtures, and initial configurations.

First Use Case: Create a Lead Use the CLI to generate a lead entity (if not already included):

php bin/console oro:generate:entity --entity=Lead

Then interact via the admin UI at /admin or programmatically:

$lead = new \Oro\CRM\Bundle\LeadBundle\Entity\Lead();
$lead->setFirstName('John');
$lead->setLastName('Doe');
$lead->setEmail('john@example.com');
$em->persist($lead);
$em->flush();

Where to Look First

Documentation: OroCRM Docs (especially the CRM Bundle).
Admin UI: /admin for pre-built dashboards, lists, and forms.
Entity Structure: src/Oro/CRM/Bundle/*/Entity/ for core entities (e.g., Lead, Account, Contact).
Services: src/Oro/CRM/Bundle/*/Services/ for business logic (e.g., lead conversion, email tracking).

Implementation Patterns

Core Workflows

Entity Management:

CRUD Operations: Use Doctrine ORM or Oro’s EntityManager wrappers.

$account = $this->entityManager->find('OroCRMAccountBundle:Account', 1);
$account->addContact($contact); // Business logic via entity methods
$this->entityManager->flush();

Custom Fields: Extend entities with custom fields via YAML/annotations:

# config/oro/entity_config.yml
Oro\CRM\Bundle\AccountBundle\Entity\Account:
    fields:
        custom_field:
            type: text
            form:
                type: text

Business Processes:

Lead Conversion: Use the LeadConverter service to automate workflows:

$converter = $this->container->get('oro_crm.lead.converter');
$account = $converter->convertLeadToAccount($lead);

Email Integration: Leverage the Email bundle to track customer interactions:

$email = new \Oro\Bundle\EmailBundle\Entity\Email();
$email->setFrom('sales@example.com');
$email->setTo('customer@example.com');
$email->setSubject('Follow-up');
$this->emailManager->save($email);

APIs & Extensions:
- REST API: Enable via oro_rest bundle and expose CRM entities:
```
# config/oro/api.yml
Oro\CRM\Bundle\LeadBundle\Entity\Lead:
    operations:
        - GET
        - POST
```
- Webhooks: Use Symfony’s HttpClient or Oro’s event system to trigger actions (e.g., Slack notifications on lead creation).

Integration Tips

Laravel Compatibility:
- OroCRM is Symfony-based but can coexist with Laravel via laravel/symfony-bridge. Use Laravel’s service container to bind Oro services:
```
$this->app->bind('oro_crm.lead.manager', function ($app) {
    return $app->make('oro_crm.lead.manager.default');
});
```
Event-Driven Architecture:
- Subscribe to Oro’s events (e.g., oro_crm.lead.create) to extend functionality:
```
$dispatcher->addListener('oro_crm.lead.create', function ($event) {
    // Send welcome email
});
```
Data Migrations:
- Use Oro’s DataFixtures for initial data or custom migrations:
```
php bin/console oro:data-fixtures:load
```

Gotchas and Tips

Pitfalls

Deprecated OroPlatform:
- OroCRM relies on OroPlatform (last updated 2017), which may have outdated dependencies (e.g., Symfony 3.x). Ensure compatibility with your PHP/Laravel version.
- Fix: Pin versions in composer.json or use a Docker container with matching PHP/Symfony versions.
Entity Inheritance:
- Oro uses single-table inheritance (STI) for some entities (e.g., AccountAddress). Overriding these requires careful handling of discriminator columns.
- Tip: Use oro:generate:entity to scaffold extensions safely.
Caching Quirks:
- Oro caches entity metadata aggressively. Clear caches after schema changes:
```
php bin/console cache:clear
php bin/console oro:cache:clear --all
```
UI Customization:
- The admin UI is tightly coupled to Oro’s templates. Overriding views requires copying template files from vendor/orocrm/ to app/Resources/OroCRMBundle/ and extending them.
- Tip: Use oro:theme:dump to regenerate assets after changes.

Debugging Tips

Symfony Profiler:
- Enable the profiler (APP_DEBUG=true) to inspect Doctrine queries, events, and service calls.

Logging:

Configure Oro’s logger in config/packages/monolog.yaml:

handlers:
    oro_crm:
        type: stream
        path: "%kernel.logs_dir%/oro_crm.log"
        level: debug

Database Schema:

Use oro:database:dump-schema to inspect the current schema:

php bin/console oro:database:dump-schema --entity="OroCRMAccountBundle:Account" > schema.sql

Extension Points

Custom Entities:

Extend existing entities (e.g., Account) by creating a child class and updating the mapping:

# config/oro/entity_extensions.yml
Oro\CRM\Bundle\AccountBundle\Entity\Account:
    extensions:
        custom:
            class: App\Entity\Extension\Account\CustomFields

Workflow Customization:

Modify business processes via Oro’s WorkflowBundle:

php bin/console oro:workflow:generate:transition --entity=Lead --transition=qualify

API Extensions:

Add custom API actions by extending the ApiConfigProvider:

public function getConfig()
{
    return [
        'Oro\CRM\Bundle\LeadBundle\Entity\Lead' => [
            'operations' => ['GET', 'POST', 'CUSTOM_ACTION'],
        ],
    ];
}

Pro Tips

Use the CLI Generators: Oro provides CLI tools for common tasks (e.g., oro:generate:entity, oro:generate:form). Always check php bin/console list oro for available commands.

Leverage Oro’s DataGrid: Customize list views without writing raw SQL by extending the Datagrid configuration:

# config/oro/datagrid.yml
Oro\CRM\Bundle\LeadBundle\Entity\Lead:
    actions:
        view:
            type: navigate
            route: oro_crm_lead_view
            acl_resource: oro_crm_lead_view

Test with Fixtures: Use Oro’s built-in fixtures to seed test data:
```
php bin/console oro:data-fixtures:load --append --env=test
```

Crm Laravel Package