README

Bidirectional bridge between PHP and Node.js — call Node.js handlers from PHP and PHP handlers from Node.js. Framework agnostic with first-class Laravel and Symfony support.

Works with: Laravel, Symfony, Slim, Zend/Laminas, vanilla PHP ↔ Express, Next.js, Nuxt.js, Fastify, NestJS.

How It Works

Your PHP App                       Your Node App
(Laravel / Symfony / Slim)        (Express / Next / Nuxt)

   PhpBridge  ◄──── HTTP ────►    NodeBridge
   :5556                           :5555

   register() ← Node can call      register() ← PHP can call
   call()     → calls Node         call()     → calls PHP

Both sides register named handlers and communicate over local HTTP. JSON payloads, shared-secret auth, timeout handling, middleware support.

Installation

composer require anandpilania/php-node-bridge

Quick Start

Vanilla PHP

<?php
require 'vendor/autoload.php';

use PhpNodeBridge\Bridge\PhpBridge;

$bridge = new PhpBridge([
    'port'     => 5556,
    'nodePort' => 5555,
    'secret'   => 'my-secret',
]);

// Register handlers Node.js can call
$bridge
    ->register('invoice.create', function (array $payload): array {
        // your DB logic here
        return ['id' => 123, 'total' => 99.99];
    })
    ->register('user.find', function (array $payload): array {
        return ['id' => $payload['id'], 'name' => 'Alice'];
    });

// Call Node.js (e.g. generate a PDF)
$pdf = $bridge->call('pdf.generate', [
    'template' => 'invoice',
    'data'     => ['invoiceId' => 123],
]);

// Start listener (blocking — run as a separate daemon)
$bridge->listen();

Laravel Integration

1. Install & auto-discover

The service provider is auto-discovered via composer.json. Just install and publish config:

composer require anandpilania/php-node-bridge
php artisan vendor:publish --tag=bridge-config

2. Configure .env

BRIDGE_PORT=5556
NODE_BRIDGE_PORT=5555
NODE_BRIDGE_HOST=127.0.0.1
BRIDGE_SECRET=your-super-secret-key
BRIDGE_TIMEOUT=10

3. Register handlers

// app/Providers/AppServiceProvider.php
public function boot(PhpBridge $bridge): void
{
    $bridge->register('invoice.create', function (array $p): array {
        return Invoice::create($p)->toArray();
    });
}

4. Use in controllers

use PhpNodeBridge\Laravel\Bridge; // Facade

class DocumentController extends Controller
{
    public function sign(Request $request)
    {
        $result = Bridge::call('esign.sign', $request->all());
        return response()->json($result);
    }

    public function sendEmail(Request $request)
    {
        Bridge::fire('email.send', $request->all()); // fire-and-forget
        return response()->json(['queued' => true]);
    }
}

5. Start the bridge daemon

php artisan bridge:listen

Symfony Integration

1. Register bundle

// config/bundles.php
return [
    PhpNodeBridge\Symfony\PhpNodeBridgeBundle::class => ['all' => true],
];

2. Configure

# config/packages/php_node_bridge.yaml
php_node_bridge:
    port: '%env(int:BRIDGE_PORT)%'
    node_port: '%env(int:NODE_BRIDGE_PORT)%'
    node_host: '%env(NODE_BRIDGE_HOST)%'
    secret: '%env(BRIDGE_SECRET)%'
    timeout: 10
    log_level: 'info'

3. Inject and use

use PhpNodeBridge\Bridge\PhpBridge;

class DocumentController extends AbstractController
{
    public function __construct(private PhpBridge $bridge) {}

    #[Route('/api/pdf', methods: ['POST'])]
    public function pdf(Request $request): JsonResponse
    {
        $result = $this->bridge->call('pdf.generate', json_decode($request->getContent(), true));
        return $this->json($result);
    }
}

4. Start daemon

php bin/console bridge:listen

API Reference

new PhpBridge(config)

$bridge->register(string $name, callable $fn): static

Register a handler Node.js can call.

$bridge->registerAll(array $handlers): static

Register multiple handlers: ['name' => fn, ...].

$bridge->unregister(string $name): static

Remove a handler.

$bridge->call(string $handler, array $payload, ?int $timeout): mixed

Call a handler on the Node.js side.

$bridge->fire(string $handler, array $payload): static

Fire-and-forget call to Node.js.

$bridge->use(callable $fn): static

Add middleware: function(string $name, array $payload): void. Throw to reject.

$bridge->listen(): void

Start listening (blocking). Run in a separate daemon process.

$bridge->listHandlers(): string[]

List all registered handler names.

Exceptions

Running as a Daemon

Supervisor (recommended)

; /etc/supervisor/conf.d/php-bridge.conf
[program:php-node-bridge]
command=php /var/www/html/artisan bridge:listen
directory=/var/www/html
autostart=true
autorestart=true
startretries=3
user=www-data
stdout_logfile=/var/log/supervisor/bridge.log
stderr_logfile=/var/log/supervisor/bridge-err.log

systemd

[Unit]
Description=PHP Node Bridge
After=network.target

[Service]
User=www-data
WorkingDirectory=/var/www/html
ExecStart=/usr/bin/php artisan bridge:listen
Restart=always

[Install]
WantedBy=multi-user.target

Docker Compose

services:
  php:
    build: ./php-app
    environment:
      NODE_BRIDGE_HOST: node
      BRIDGE_SECRET: ${BRIDGE_SECRET}
    ports:
      - "8000:8000"
      - "5556:5556"

  node:
    build: ./node-app
    environment:
      PHP_BRIDGE_HOST: php
      BRIDGE_SECRET: ${BRIDGE_SECRET}
    ports:
      - "3000:3000"
      - "5555:5555"

Testing

php tests/run.php

License

MIT