Laminas Server Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require laminas/laminas-server:^2.19.0
   

   Add to composer.json under require-dev if only for testing. Note: PHP 8.5 is now required; PHP 8.1 support has been dropped.

2. First Use Case: Basic RPC Server Define a service class with annotated methods (unchanged):

   namespace App\Services;
   
   use Laminas\Server\Annotation\Rpc;
   
   class CalculatorService
   {
       /**
        * @Rpc
        */
       public function add(int $a, int $b): int
       {
           return $a + $b;
       }
   }
   

3. Bootstrap the Server (unchanged)

   use Laminas\Server\Server;
   use Laminas\Server\Reflection\ReflectionService;
   
   $server = new Server();
   $reflectionService = new ReflectionService();
   $server->addService($reflectionService->getService('App\Services\CalculatorService'));
   $server->run();
   

4. Test via CLI or HTTP (unchanged)

   curl -X POST http://localhost:8080/rpc -d '{"method":"add","params":[2,3]}'
   

Implementation Patterns

Workflows

1. Service Definition (unchanged)

   • Use @Rpc for public methods; @Rpc\Param and @Rpc\Return for type hints.
   • Group related services in a Services/ directory with clear namespaces.

2. Request Handling (unchanged)

   • JSON-RPC 2.0: Default format. Use Laminas\Server\JsonRpc\JsonRpcServer for customization.
   • HTTP Integration: Pair with laminas/laminas-http for middleware/routing:

     $request = new \Laminas\HttpPhpEnvironment\Request();
     $response = new \Laminas\HttpPhpEnvironment\Response();
     $server->handle($request, $response);
     

3. Authentication/Authorization (unchanged)

   • Extend Laminas\Server\Server to validate requests:

     $server->setAuthService(new CustomAuthService());
     

4. Error Handling (unchanged)

   • Implement Laminas\Server\Exception\ExceptionStrategy for custom error responses.

Integration Tips

• Laravel-Specific (unchanged) Bind the server to Laravel’s service container:

  $app->singleton(Server::class, function ($app) {
      $server = new Server();
      $server->addService(app(ReflectionService::class)->getService('App\Services\*'));
      return $server;
  });
  

• Dependency Injection (unchanged) Inject services into RPC methods via constructor:

  public function __construct(private LoggerInterface $logger) {}
  

Gotchas and Tips

Pitfalls

1. PHP Version Compatibility

   • Breaking Change: PHP 8.1 is no longer supported. Update your environment to PHP 8.2+ (preferably 8.5).
   • Fix: Run composer update laminas/laminas-server and verify PHP version:

     php -v
     

2. Reflection Overhead (unchanged)

   • Avoid overusing reflection on large classes; cache ReflectionService instances.
   • Fix: Use ReflectionService::setCacheDir(__DIR__.'/cache').

3. Type Safety (unchanged)

   • PHP’s loose typing may cause silent failures. Use @Rpc\Param(type="int") explicitly.

4. Circular Dependencies (unchanged)

   • RPC services cannot depend on each other directly (reflection limitation).
   • Workaround: Use Laravel’s container or a facade pattern.

Debugging

• Enable Verbose Logging (unchanged)

  $server->setLogger(new \Monolog\Logger('rpc', [new \Monolog\Handler\StreamHandler('php://stderr')]));
  

• Check Annotations (unchanged) Use laminas/laminas-code to validate annotations pre-deployment:

  ./vendor/bin/laminas-code validate --annotations App\Services
  

Extension Points

1. Custom Protocols (unchanged) Extend Laminas\Server\Server to support GraphQL, gRPC, etc.:

   class CustomServer extends Server {
       public function handleGraphQL(\Psr\Http\Message\RequestInterface $request) { ... }
   }
   

2. Middleware (unchanged) Integrate with Laravel middleware:

   $server->pipe(new class implements \Psr\Http\Server\RequestHandlerInterface {
       public function handle(\Psr\Http\Message\RequestInterface $request, \Psr\Http\Message\ResponseInterface $response) {
           // Pre-process request
           return $next($request, $response);
       }
   });
   

3. Performance (unchanged)

   • Batch Processing: Use Laminas\Server\Batch\BatchServer for bulk RPC calls.
   • Caching: Cache reflection data:

     $reflectionService->setCacheEnabled(true);