Getting Started

Minimal Setup

Installation:

composer require artox-lab/clarc-bundle

Enable the bundle in config/bundles.php:

ArtoxLab\Bundle\ClarcBundle\ArtoxLabClarcBundle::class => ['all' => true],

Basic Configuration (config/packages/artox_lab_clarc.yaml):

artox_lab_clarc:
    api:
        serializer:
            class: \ArtoxLab\Bundle\ClarcBundle\Core\Interfaces\UI\API\Transformers\Serializers\NullObjectArraySerializer
    security:
        rbac:
            permissions:
                ROLE_MAINTAINER:
                    - show

First Use Case: RBAC Permissions Check Inject AuthorizationChecker in a controller:

use ArtoxLab\Bundle\ClarcBundle\Core\Entity\Security\AuthorizationChecker;

class SomeController {
    public function __construct(private AuthorizationChecker $authorizationChecker) {}

    public function index() {
        if (!$this->authorizationChecker->isGranted('show')) {
            throw new AccessDeniedException();
        }
        // ...
    }
}

Implementation Patterns

1. RBAC & Security

Workflow:

Define roles/permissions in artox_lab_clarc.yaml under security.rbac.permissions.

Secure routes in security.yaml:

access_control:
    - { path: ^/admin, roles: ROLE_MAINTAINER }

Check permissions in controllers/services:

$this->authorizationChecker->isGranted('permission_name');

Expose user permissions via API endpoint:

# config/routes.yaml
artox_lab_clarc_bundle_user_permissions:
    path: /v1/user/permissions
    controller: ArtoxLab\Bundle\ClarcBundle\Core\Interfaces\UI\API\Controllers\PermissionController::permissions

Integration Tip: Use IS_AUTHENTICATED_FULLY for API routes requiring authentication.

2. Navigation Menu

Workflow:

Configure menu structure in artox_lab_clarc.navigation.left_menu:

left_menu:
    items:
        - icon: dashboard
          title: Dashboard
          permissions: dashboard.view
          children:
              - link: /dashboard/analytics
                title: Analytics
                permissions: analytics.view

Add API route:

# config/routes.yaml
artox_lab_admin_user_navigations:
    path: /user/navigations
    controller: ArtoxLab\Bundle\ClarcBundle\Core\Interfaces\UI\API\Controllers\NavigationController::userNavigation

Fetch filtered menu via GET /user/navigations (permissions auto-filter items).

Integration Tip: Use show_orphaned_root: true to display root-level items without children.

3. Messaging (AMQP)

Workflow for Async Communication:

Producer Setup:

Require protobuf messages package (e.g., artox-lab/example-protobuf-messages).

Configure messenger.yaml:

framework:
    messenger:
        transports:
            broadcasting:
                dsn: '%env(BROADCASTING_MESSENGER_TRANSPORT_DSN)%'
                serializer: artox_lab_clarc.messenger.transport.serializer.protobuf_self_origin_stamps
        routing:
            'Google\Protobuf\Internal\Message': broadcasting

Dispatch messages via BroadcastingBus:

$this->broadcastingBus->dispatch(new \ArtoxLab\ExampleMessage\V1\Order\Created());

Consumer Setup:

Create a handler:

#[AsMessageHandler]
class OrderCreatedHandler {
    public function __invoke(Order\Created $message) {
        // Process message
    }
}

Run consumer:

php bin/console messenger:consume listening

Integration Tips:
- Use listening.bus for external messages (pre-configured in the bundle).
- Set up failure transport (e.g., Doctrine) for retries:
```
failure_listening:
    dsn: doctrine://default
    serializer: artox_lab_clarc.messenger.transport.serializer.protobuf
```

4. CQRS Pattern

Usage:

Commands: Use CommandBus for write operations.
Queries: Use QueryBus for read operations.
Events: Publish via EventBus for async workflows.

Example:

// Command
$this->commandBus->dispatch(new CreateCompanyCommand());

// Query
$result = $this->queryBus->ask(new GetCompanyQuery($id));

// Event
$this->eventBus->dispatch(new CompanyCreatedEvent($company));

Integration Tip: Extend AbstractApiController for auto-injected buses:

class CompanyController extends AbstractApiController {
    public function create(CreateCompanyCommand $command) {
        $this->commandBus->dispatch($command);
        // ...
    }
}

Gotchas and Tips

1. RBAC Pitfalls

Permission Caching: The AuthorizationChecker caches permissions. Clear cache after dynamic role updates:
```
php bin/console cache:clear
```
Role Hierarchy: Define roles in security.yaml before using them in artox_lab_clarc.yaml:
```
security:
    role_hierarchy:
        ROLE_ADMIN: [ROLE_MAINTAINER, ROLE_USER]
```

2. Messaging Quirks

Protobuf Validation: The protobuf_self_origin_stamps serializer validates message origin. Ensure messages include a @type annotation to avoid validation errors.
Consumer Lifecycle: Run consumers before producers to ensure exchanges/queues exist:
```
php bin/console messenger:consume listening -vv
```
Environment Variables: Use .env for transport DSNs (e.g., BROADCASTING_MESSENGER_TRANSPORT_DSN). Avoid hardcoding credentials.

3. Navigation Gotchas

Permission Filtering: Menu items are filtered client-side based on the response from /user/navigations. Ensure permissions are correctly defined in the config.

Route Security: Secure navigation routes in security.yaml:

access_control:
    - { path: ^/user/navigations, roles: IS_AUTHENTICATED_FULLY }

4. Bus/Command Patterns

Middleware Order: Add custom middleware before validation middleware to avoid bypassing checks:

# config/packages/messenger.yaml
framework:
    messenger:
        buses:
            command.bus:
                middleware:
                    - artox_lab_clarc.messenger.middleware.validation
                    - your_custom_middleware

Exception Handling: Use DomainHttpException for HTTP-friendly errors in domain logic:
```
throw new DomainHttpException(403, 'Permission denied');
```

5. Debugging Tips

Messenger Logs: Enable verbose logging for consumers:
```
php bin/console messenger:consume listening -vv
```

RBAC Debugging: Dump user permissions in a controller:

dump($this->authorizationChecker->getUserPermissions());

Protobuf Messages: Validate message schemas using protoc:
```
protoc --php_out=. path/to/message.proto
```

6. Extension Points

Custom Serializers: Extend NullObjectArraySerializer for custom API responses:

class CustomSerializer implements SerializerInterface {
    public function serialize($data): array {
        // Custom logic
    }
}

Custom Middleware: Add middleware to buses in messenger.yaml:

framework:
    messenger:
        buses:
            command.bus:
                middleware:
                    - your_namespace.middleware

Protobuf Messages: Create shared message packages for cross-service communication:
```
composer require artox-lab/example-protobuf-messages
```

Clarc Bundle Laravel Package