add php/laravel example, update README

Author: razvanphp

README.md

@@ -35,7 +35,7 @@ RabbitMQ already excels at message durability and routing, but traditionally the
 ## Installation
 
 This plugin works only with modern versions of RabbitMQ 4.x based on AMQP 1.0.
-You can [build from source](https://www.rabbitmq.com/plugin-development.html) or you can download the latest release build from GitHub. Then, unzip and place the `rabbitmq_web_ocpp-4.x.x.ez` file into your `/etc/rabbitmq/plugins/` folder.
+You can [build from source](https://www.rabbitmq.com/plugin-development.html) or you can download the latest release build from GitHub. Unzip and place the `rabbitmq_web_ocpp-4.x.x.ez` file into your `/etc/rabbitmq/plugins/` folder.
 Like all plugins, it [must be enabled](https://www.rabbitmq.com/plugins.html) before it can be used:
 
 ``` bash
@@ -48,10 +48,23 @@ Detailed instructions on how to install a plugin into RabbitMQ broker can be fou
 Note that release branches (`v4.1.x` vs. `main`) and target RabbitMQ version need to be taken into account
 when building plugins from source.
 
+## How It Works
+
+The communication flow is straightforward: 
+1. Messages arriving from the EVSE are sent to the configured exchange (default: `amq.topic`) with `correlation_id` set to the OCPP `messageId` and `reply_to` set to the EVSE ID.
+2. Configure backend worker routing on the CSMS side by creating a queue bound to the same exchange. Use routing keys in the format: `protocolver.actionname.req/conf/error`. Examples: `ocpp16.BootNotification.req`, `ocpp16.Heartbeat.conf`, `ocpp201.StatusNotification.req`. Common patterns include `ocpp16.#` for all v1.6 traffic or `*.StartTransaction.#` for billing-specific workers. See the [RabbitMQ Topics tutorial](https://www.rabbitmq.com/tutorials/tutorial-five-python#topic-exchange) for details.
+3. After processing and validating the message in your async worker, build a valid OCPP Response (or error) and publish it back to the same exchange with the routing key set to the EVSE ID and `correlation_id` set to the original request's OCPP `messageId`. The plugin handles sending this message back to the EVSE via the correct WebSocket connection.
+4. Queues can be consumed by multiple identical, stateless workers written in any programming language. Monitor queues using built-in tools (e.g., Grafana) and configure auto-scaling based on message latency or queue depth.
+5. If a worker throws an exception before sending a valid OCPP response, standard AMQP ACK/NACK principles apply: unconfirmed messages return to the queue for processing by another worker. Handle failure scenarios (e.g., database outages) gracefully to avoid infinite retry loops.
+
 ## Documentation
 
 For all configuration options, please refer to the nearly identical plugin, [RabbitMQ Web MQTT guide](https://www.rabbitmq.com/web-mqtt.html).
 
+## Screenshots
+
+![RabbitMQ Web OCPP Management Interface](examples/screenshots/Screenshot_RabbitMQ_1.png)
+
 ## Enterprise-Grade Hosting & SLA Support
 
 For CPOs or platform operators that need to onboard fleets of tens of thousands of chargers, our team offers cloud-native RabbitMQ HA deployments in AWS, Azure or GCP, complete with 24/7 monitoring, incident response, rolling upgrades, and expert assistance for PKI, Prometheus dashboards and OCPP-specific queue policies; we can also deliver custom feature work; we tailor service levels and cluster topologies so you can scale from pilot projects to nationwide networks without re-architecting.

examples/php/.gitattributes

@@ -0,0 +1,11 @@
+* text=auto eol=lf
+
+*.blade.php diff=html
+*.css diff=css
+*.html diff=html
+*.md diff=markdown
+*.php diff=php
+
+/.github export-ignore
+CHANGELOG.md export-ignore
+.styleci.yml export-ignore

examples/php/.gitignore

@@ -0,0 +1,24 @@
+*.log
+.DS_Store
+.env
+.env.backup
+.env.production
+.phpactor.json
+.phpunit.result.cache
+/.fleet
+/.idea
+/.nova
+/.phpunit.cache
+/.vscode
+/.zed
+/auth.json
+/node_modules
+/public/build
+/public/hot
+/public/storage
+/storage/*.key
+/storage/pail
+/vendor
+Homestead.json
+Homestead.yaml
+Thumbs.db

examples/php/README.md

@@ -0,0 +1,35 @@
+# OCPP AMQP Server (PHP/Laravel)
+
+This directory contains a PHP/Laravel example for handling OCPP (Open Charge Point Protocol) messages using the RabbitMQ native OCPP to AMQP plugin. It leverages Laravel's queue system and the [solution-forest/ocpp-php](https://github.com/solution-forest/ocpp-php) library.
+
+## Files
+
+- `app/Jobs/OcppMessageProxy.php` - The main entry point (Job) that consumes raw OCPP messages from RabbitMQ and dispatches them to specific action handlers.
+- `app/Jobs/Ocpp/v16/` - Directory containing individual Job classes for each OCPP 1.6 action (e.g., `BootNotification`, `Heartbeat`).
+- `config/queue.php` - Configuration for the RabbitMQ connection and queue settings.
+- `composer.json` - PHP dependencies.
+
+## Dependencies
+
+- [Laravel](https://laravel.com) - The web application framework.
+- [laravel-queue-rabbitmq](https://github.com/vyuldashev/laravel-queue-rabbitmq) - RabbitMQ driver for Laravel queues.
+- [ocpp-php](https://github.com/solution-forest/ocpp-php) - Library for parsing and validating OCPP messages.
+
+## Key Features
+
+- **Laravel Queue Integration**: Uses the standard `php artisan queue:work` or `rabbitmq:consume` commands to process OCPP messages.
+- **Proxy Job Pattern**: `OcppMessageProxy` acts as a router, intercepting raw OCPP JSON arrays from the queue and dispatching them to dedicated classes.
+- **Schema Validation**: Incoming messages are validated against OCPP 1.6 JSON schemas using the `ocpp-php` library.
+- **Separation of Concerns**: Each OCPP action (like `BootNotification`, `Heartbeat`) is handled by its own Job class.
+
+## Running the Worker
+
+To start consuming messages from the queue:
+
+```bash
+# Standard Laravel worker (polling)
+php artisan queue:work rabbitmq --queue=ocpp.worker --sleep=0.01
+
+# Or using the RabbitMQ consumer (push-based, recommended for lower latency)
+php artisan rabbitmq:consume rabbitmq --queue=ocpp.worker
+```

examples/php/app/Jobs/Ocpp/v16/BootNotification.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace App\Jobs\Ocpp\v16;
+
+use Illuminate\Support\Facades\Log;
+use SolutionForest\OcppPhp\Ocpp\v16\CallResults\BootNotification as BootNotificationResponse;
+
+class BootNotification
+{
+    /**
+     * Handle BootNotification request.
+     *
+     * @param string $messageId
+     * @param array $data
+     * @return array OCPP CALLRESULT: [3, messageId, payload]
+     */
+    public function handle(string $messageId, array $data): array
+    {
+        Log::info('BootNotification received', [
+            'messageId' => $messageId,
+            'vendor' => $data['chargePointVendor'] ?? 'unknown',
+            'model' => $data['chargePointModel'] ?? 'unknown',
+            'serialNumber' => $data['chargePointSerialNumber'] ?? null,
+        ]);
+
+        $response = new BootNotificationResponse($messageId);
+        $response->status = 'Accepted'; // Options: Accepted, Pending, Rejected
+        $response->currentTime = now()->toIso8601String();
+        $response->interval = 60; // Heartbeat interval in seconds
+
+        return $response->toArray();
+    }
+}

examples/php/app/Jobs/Ocpp/v16/Heartbeat.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Jobs\Ocpp\v16;
+
+use Illuminate\Support\Facades\Log;
+use SolutionForest\OcppPhp\Ocpp\v16\CallResults\Heartbeat as HeartbeatResponse;
+
+class Heartbeat
+{
+    /**
+     * Handle Heartbeat request.
+     *
+     * @param string $messageId
+     * @param array $data
+     * @return array OCPP CALLRESULT: [3, messageId, payload]
+     */
+    public function handle(string $messageId, array $data): array
+    {
+        Log::debug('Heartbeat received', ['messageId' => $messageId]);
+
+        $response = new HeartbeatResponse($messageId);
+        $response->currentTime = now()->toIso8601String();
+
+        return $response->toArray();
+    }
+}

examples/php/app/Jobs/Ocpp/v16/StatusNotification.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Jobs\Ocpp\v16;
+
+use Illuminate\Support\Facades\Log;
+use SolutionForest\OcppPhp\Ocpp\v16\CallResults\StatusNotification as StatusNotificationResponse;
+
+class StatusNotification
+{
+    /**
+     * Handle StatusNotification request.
+     *
+     * @param string $messageId
+     * @param array $data
+     * @return array OCPP CALLRESULT: [3, messageId, payload]
+     */
+    public function handle(string $messageId, array $data): array
+    {
+        Log::info('StatusNotification received', [
+            'messageId' => $messageId,
+            'connectorId' => $data['connectorId'] ?? null,
+            'status' => $data['status'] ?? 'unknown',
+            'errorCode' => $data['errorCode'] ?? 'NoError',
+            'timestamp' => $data['timestamp'] ?? null,
+        ]);
+
+        $response = new StatusNotificationResponse($messageId);
+        // StatusNotification response has no additional fields
+
+        return $response->toArray();
+    }
+}

examples/php/app/Jobs/OcppMessageProxy.php

@@ -0,0 +1,122 @@
+<?php
+
+namespace App\Jobs;
+
+use Illuminate\Support\Facades\Log;
+use SolutionForest\OcppPhp\Ocpp\Exceptions\NotImplementedError;
+use SolutionForest\OcppPhp\Ocpp\JsonSchemaValidator;
+use SolutionForest\OcppPhp\Ocpp\Messages\CallError;
+use VladimirYuldashev\LaravelQueueRabbitMQ\Queue\Jobs\RabbitMQJob;
+
+class OcppMessageProxy extends RabbitMQJob
+{
+    protected $actionName = '';
+
+    /**
+     * Fire the job - dispatches to specific OCPP action jobs.
+     *
+     * @return void
+     */
+    public function fire()
+    {
+        $payload = $this->payload();
+
+        dump('OcppMessageJob received:', $payload);
+
+        // OCPP CALL format: [messageTypeId, messageId, action, payload]
+        if (! is_array($payload) || count($payload) < 3) {
+            Log::error('Invalid OCPP message format', ['payload' => $payload]);
+            $this->delete();
+            return false;
+        }
+
+        [$messageType, $messageId, $action] = $payload;
+        $data = $payload[3] ?? [];
+
+        // Only handle CALL messages (2); ignore CALLRESULT/CALLERROR
+        if ($messageType !== 2) {
+            Log::debug('Ignoring non-CALL message', ['messageType' => $messageType]);
+            $this->delete();
+            return false;
+        }
+
+        // Resolve Call Class from Library
+        $callClass = "SolutionForest\\OcppPhp\\Ocpp\\v16\\Calls\\{$action}";
+
+        if (!class_exists($callClass)) {
+            Log::warning("Unknown OCPP Action (Library class not found): {$action}");
+            $error = new NotImplementedError($messageId);
+            $response = $error->toArray();
+            dump('OcppMessageJob response (NotImplemented - Unknown Action):', $response);
+            Log::info('OCPP Response ready to send', ['response' => $response]);
+            $this->delete();
+            return false;
+        }
+
+        // Instantiate and hydrate Call object for validation
+        /** @var \SolutionForest\OcppPhp\Ocpp\Messages\Call $callObject */
+        $callObject = new $callClass();
+        $callObject->messageId = $messageId;
+        foreach ($data as $key => $value) {
+            $callObject->$key = $value;
+        }
+
+        // Validate incoming OCPP message using built-in JSON schema validator
+        $validationResult = JsonSchemaValidator::validate($callObject, 'v1.6', false);
+
+        // If validation fails, validator already built a proper CallError
+        if ($validationResult instanceof CallError) {
+            Log::warning("OCPP message validation failed for action: {$action}", [
+                'messageId' => $messageId,
+                'errorCode' => $validationResult->errorCode,
+                'errorDescription' => $validationResult->errorDescription,
+            ]);
+            $response = $validationResult->toArray();
+        }
+
+        // Build job class name: App\Jobs\Ocpp\v16\{Action}
+        $jobClass = "App\\Jobs\\Ocpp\\v16\\{$action}";
+
+        if (!class_exists($jobClass)) {
+            Log::warning("No job found for action: {$action}, sending NotImplemented");
+            $error = new NotImplementedError($messageId);
+            $response = $error->toArray();
+        }
+
+        // Instantiate and execute the specific OCPP job
+        $job = app($jobClass);
+        $response = $job->handle($messageId, $data);
+
+        if ($response) {
+            dump('OcppMessageJob response:', $response);
+            Log::info('OCPP Response ready to send', ['response' => $response]);
+
+            $this->respond($response);
+        }
+
+        $this->delete();
+        return true;
+    }
+
+    public function getName()
+    {
+        return $this->actionName;
+    }
+
+    public function respond($response)
+    {
+        $broker = $this->getRabbitMQ();
+        $message = $this->getRabbitMQMessage();
+
+        if ($message->has('reply_to')) {
+            $broker->getChannel()->basic_publish(
+                new \PhpAmqpLib\Message\AMQPMessage(
+                    json_encode($response),
+                    ['correlation_id' => $message->get('correlation_id') ?? '']
+                ),
+                'amq.topic',
+                $message->get('reply_to')
+            );
+        }
+    }
+}

examples/php/artisan

@@ -0,0 +1,18 @@
+#!/usr/bin/env php
+<?php
+
+use Illuminate\Foundation\Application;
+use Symfony\Component\Console\Input\ArgvInput;
+
+define('LARAVEL_START', microtime(true));
+
+// Register the Composer autoloader...
+require __DIR__.'/vendor/autoload.php';
+
+// Bootstrap Laravel and handle the command...
+/** @var Application $app */
+$app = require_once __DIR__.'/bootstrap/app.php';
+
+$status = $app->handleCommand(new ArgvInput);
+
+exit($status);

examples/php/bootstrap/app.php

@@ -0,0 +1,18 @@
+<?php
+
+use Illuminate\Foundation\Application;
+use Illuminate\Foundation\Configuration\Exceptions;
+use Illuminate\Foundation\Configuration\Middleware;
+
+return Application::configure(basePath: dirname(__DIR__))
+    ->withRouting(
+        // web: __DIR__.'/../routes/web.php',
+        // commands: __DIR__.'/../routes/console.php',
+        health: '/up',
+    )
+    ->withMiddleware(function (Middleware $middleware): void {
+        //
+    })
+    ->withExceptions(function (Exceptions $exceptions): void {
+        //
+    })->create();