Rpc Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require caseboxdev/rpc-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Casebox\RpcBundle\CaseboxRpcBundle::class => ['all' => true],
   ];
   

2. Configuration Follow the Casebox documentation for Symfony CMF integration. Key steps:

   • Configure casebox_rpc in config/packages/casebox_rpc.yaml (if provided).
   • Ensure your services.yaml includes the RPC service bindings:

     services:
         Casebox\RpcBundle\Service\RpcService: ~
     

3. First Use Case: RPC Endpoint Create a basic RPC controller extending CaseboxRpcBundle's base controller:

   // src/Controller/CaseboxRpcController.php
   namespace App\Controller;
   
   use Casebox\RpcBundle\Controller\AbstractRpcController;
   
   class CaseboxRpcController extends AbstractRpcController
   {
       public function indexAction()
       {
           return $this->rpcService->handleRequest('your_rpc_method', [/* params */]);
       }
   }
   

   Route it in config/routes.yaml:

   casebox_rpc:
       path: /api/rpc
       controller: App\Controller\CaseboxRpcController::indexAction
       methods: [POST]
   

4. ExtJS Client Setup Configure your ExtJS app to target the /api/rpc endpoint with JSON payloads:

   Ext.Ajax.request({
       url: '/api/rpc',
       method: 'POST',
       jsonData: {
           method: 'your_rpc_method',
           params: ['data1', 'data2']
       },
       success: function(response) {
           console.log(response.responseData);
       }
   });
   

Implementation Patterns

Core Workflows

1. Service Integration

   • Dependency Injection: Inject RpcService into controllers/services:

     public function __construct(private RpcService $rpcService) {}
     

   • Method Handling: Use handleRequest() to delegate RPC calls:

     $result = $this->rpcService->handleRequest('method_name', [$arg1, $arg2]);
     

2. Exception Handling

   • Extend Casebox\RpcBundle\Exception\RpcException for custom errors.
   • Override the default exception handler in config/packages/casebox_rpc.yaml:

     casebox_rpc:
         exception_handler: App\Service\CustomRpcExceptionHandler
     

3. Symfony CMF Integration

   • Use CaseboxRpcBundle's CMF listeners to sync data between Casebox and Symfony CMF routes.
   • Example: Extend Casebox\RpcBundle\EventListener\CmfListener for custom logic.

4. ExtJS RPC Patterns

   • Batch Requests: Send arrays of RPC calls in a single POST:

     jsonData: [
         { method: 'method1', params: [...] },
         { method: 'method2', params: [...] }
     ]
     

   • Async Handling: Use ExtJS Promise for async RPC calls:

     Ext.Ajax.request({...}).then(function(response) { ... });
     

Integration Tips

• Validation: Validate RPC inputs using Symfony’s Validator:

  use Symfony\Component\Validator\Validator\ValidatorInterface;
  
  public function __construct(private ValidatorInterface $validator) {}
  
  public function validateRpcParams(array $params): void
  {
      $errors = $this->validator->validate($params);
      if (count($errors)) {
          throw new RpcException('Validation failed', $errors);
      }
  }
  

• Authentication: Secure RPC endpoints with Symfony’s security component:

  # config/routes.yaml
  casebox_rpc:
      path: /api/rpc
      controller: App\Controller\CaseboxRpcController::indexAction
      methods: [POST]
      defaults: { _security: "authenticated" }
  

• Logging: Log RPC calls for debugging:

  use Psr\Log\LoggerInterface;
  
  public function __construct(private LoggerInterface $logger) {}
  
  public function logRpcCall(string $method, array $params): void
  {
      $this->logger->info('RPC Call', ['method' => $method, 'params' => $params]);
  }
  

Gotchas and Tips

Common Pitfalls

1. Deprecated Symfony 3

   • The bundle targets Symfony 3.x, which may cause compatibility issues with newer Symfony versions (e.g., autowiring, config structure).
   • Workaround: Use a compatibility layer or fork the bundle for Symfony 5/6.

2. ExtJS Version Mismatch

   • The bundle assumes ExtJS 4/5 RPC format. Modern ExtJS (6+) uses a different payload structure.
   • Fix: Normalize payloads in your controller:

     public function handleExtJsRequest(Request $request)
     {
         $data = json_decode($request->getContent(), true);
         if (isset($data['method'])) {
             // ExtJS 4/5 format
             return $this->handleRpc($data['method'], $data['params'] ?? []);
         } elseif (isset($data[0]['method'])) {
             // ExtJS 6+ batch format
             return array_map(function($call) {
                 return $this->handleRpc($call['method'], $call['params'] ?? []);
             }, $data);
         }
     }
     

3. CMF Route Conflicts

   • Overlapping routes between Symfony CMF and RPC endpoints can cause 404s.
   • Solution: Explicitly prefix RPC routes:

     casebox_rpc:
         path: /api/v1/rpc
         # ...
     

4. AGPL License Risks

   • The AGPL 3.0 license may conflict with proprietary software usage.
   • Mitigation: Review the license terms or seek legal advice before production use.

Debugging Tips

1. Enable RPC Logging Add to config/packages/monolog.yaml:

   handlers:
       casebox_rpc:
           type: stream
           path: "%kernel.logs_dir%/casebox_rpc.log"
           level: debug
           channels: ["casebox_rpc"]
   

   Then log in your RPC service:

   $this->logger->debug('RPC Request', ['data' => $requestData]);
   

2. Inspect Raw Requests Dump RPC payloads in a controller:

   public function debugRpc(Request $request)
   {
       file_put_contents(
           '/tmp/rpc_debug.log',
           print_r($request->toArray(), true)
       );
       return $this->rpcService->handleRequest(...);
   }
   

3. Test with curl Manually test RPC endpoints:

   curl -X POST http://localhost/api/rpc \
        -H "Content-Type: application/json" \
        -d '{"method":"test_method","params":["arg1"]}'
   

Extension Points

1. Custom RPC Methods Register new RPC methods in services.yaml:

   services:
       App\Rpc\CustomRpcMethod:
           tags: [casebox_rpc.method]
           arguments:
               $methodName: 'custom_method'
               $handler: '@app.service.custom_handler'
   

2. Override Exception Handler Create a custom handler:

   // src/Service/CustomRpcExceptionHandler.php
   namespace App\Service;
   
   use Casebox\RpcBundle\Exception\RpcExceptionHandlerInterface;
   
   class CustomRpcExceptionHandler implements RpcExceptionHandlerInterface
   {
       public function handle(RpcException $exception): array
       {
           return [
               'success' => false,
               'message' => $exception->getMessage(),
               'code' => $exception->getCode(),
               'details' => $exception->getDetails() ?? []
           ];
       }
   }
   

   Configure in config/packages/casebox_rpc.yaml:

   casebox_rpc:
       exception_handler: App\Service\CustomRpcExceptionHandler
   

3. Add Middleware Extend the RPC pipeline with middleware:

   // src/EventSubscriber/RpcMiddlewareSubscriber.php
   namespace App\EventSubscriber;
   
   use Casebox\RpcBundle\Event\RpcEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class RpcMiddlewareSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               RpcEvent::PRE_HANDLE => 'onPreHandle',
               RpcEvent::POST_HANDLE => 'onPostHandle'
           ];
       }
   
       public function onPreHandle(RpcEvent $event): void
       {
           // Pre-processing logic
       }
   
       public function onPostHandle(RpcEvent $event): void