From c85c0d824c3f30ddf53036e5c8bb83a7fc5453b2 Mon Sep 17 00:00:00 2001
From: Jeppe Bundgaard <jb@truckwash.dk>
Date: Thu, 4 Sep 2025 12:05:49 +0200
Subject: [PATCH] Extend License Plate Recognizer module with usage info
 endpoint and enhanced API handling

- Added `get_usage` method in `licenseplaterecognizer` to retrieve module usage statistics from the API.
- Introduced `licenseplaterecognizer_info` class to parse and manage API response data.
- Enhanced API request handling with updated default `api_url` and improved error handling.
- Refined cURL implementation for consistent API interaction.
---
 .../app/classes/licenseplaterecognizer.php    | 44 +++++++++++++++++--
 .../interfaces/licenseplaterecognizer_i.php   |  9 ++++
 .../helpers/licenseplaterecognizer_info.php   | 33 ++++++++++++++
 3 files changed, 83 insertions(+), 3 deletions(-)
 create mode 100644 services/nginx/app/modules/licenseplaterecognizer/helpers/licenseplaterecognizer_info.php

diff --git a/services/nginx/app/classes/licenseplaterecognizer.php b/services/nginx/app/classes/licenseplaterecognizer.php
index 6f1a7558..3538ff02 100644
--- a/services/nginx/app/classes/licenseplaterecognizer.php
+++ b/services/nginx/app/classes/licenseplaterecognizer.php
@@ -5,6 +5,7 @@ require_once WD . '/modules/licenseplaterecognizer/licenseplaterecognizer_c.php'
 
 use Exception;
 use interfaces\licenseplaterecognizer_i;
+use licenseplaterecognizer\helpers\licenseplaterecognizer_info;
 use licenseplaterecognizer\licenseplaterecognizer_c;
 
 class licenseplaterecognizer implements licenseplaterecognizer_i
@@ -18,7 +19,7 @@ class licenseplaterecognizer implements licenseplaterecognizer_i
      * API URL
      * @var string
      */
-    private string $api_url = 'https://api.platerecognizer.com/v1/plate-reader/';
+    private string $api_url = 'https://vs4sws0kg4sog4ssw8kwowk4.coolify.truckwash.dk'; // Default (cloud): 'https://api.platerecognizer.com'; (without /v1/plate-reader/)';
 
 
     public function __construct()
@@ -49,11 +50,12 @@ class licenseplaterecognizer implements licenseplaterecognizer_i
         //ADD PARAMETER IN REQUEST LIKE regions
         $data = array(
             'upload' => $base64_image,
-            'regions' => 'us-ca' // Optional
+            //'regions' => 'dk' // Optional
         );
 
         // Prepare new cURL resource
-        $ch = curl_init('https://api.platerecognizer.com/v1/plate-reader/');
+        //$ch = curl_init('https://api.platerecognizer.com/v1/plate-reader/');
+        $ch = curl_init($this->api_url . '/v1/plate-reader/');
         curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
         curl_setopt($ch, CURLINFO_HEADER_OUT, true);
         curl_setopt($ch, CURLOPT_POST, true);
@@ -69,6 +71,10 @@ class licenseplaterecognizer implements licenseplaterecognizer_i
         // Submit the POST request and close cURL session handle
         $result = curl_exec($ch);
         curl_close($ch);
+        // Print the response from the server
+        if ($result === false) {
+            throw new Exception('Error in API request.');
+        }
 
         $response_data = json_decode($result, true);
         if (isset($response_data['results']) && count($response_data['results']) > 0) {
@@ -86,4 +92,36 @@ class licenseplaterecognizer implements licenseplaterecognizer_i
             ];
         }
     }
+
+    /**
+     * @inheritDoc
+     * @throws Exception If the module is not enabled or if there is an error in the API request
+     * @throws Exception If the API response cannot be parsed
+     */
+    public function get_usage(): licenseplaterecognizer_info
+    {
+        // Require the module to be enabled
+        $this->requireModuleEnabled();
+        $curl = curl_init();
+        curl_setopt_array($curl, array(
+            CURLOPT_URL => $this->api_url . '/info/',
+            CURLOPT_RETURNTRANSFER => true,
+            CURLOPT_ENCODING => '',
+            CURLOPT_MAXREDIRS => 10,
+            CURLOPT_TIMEOUT => 0,
+            CURLOPT_FOLLOWLOCATION => true,
+            CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_2TLS,
+            CURLOPT_CUSTOMREQUEST => 'GET',
+            CURLOPT_HTTPHEADER => array(
+                'Authorization: Token ' . $this->config->api_key->getVariableValue()
+            ),
+        ));
+        $response = curl_exec($curl);
+        curl_close($curl);
+        $response_data = json_decode($response, true);
+        if ($response_data === null) {
+            throw new Exception('Error parsing API response.');
+        }
+        return new licenseplaterecognizer_info($response_data);
+    }
 }
\ No newline at end of file
diff --git a/services/nginx/app/interfaces/licenseplaterecognizer_i.php b/services/nginx/app/interfaces/licenseplaterecognizer_i.php
index 6eb8d1e0..202d7894 100644
--- a/services/nginx/app/interfaces/licenseplaterecognizer_i.php
+++ b/services/nginx/app/interfaces/licenseplaterecognizer_i.php
@@ -1,5 +1,8 @@
 <?php
 namespace interfaces;
+require_once WD . '/modules/licenseplaterecognizer/helpers/licenseplaterecognizer_info.php';
+use licenseplaterecognizer\helpers\licenseplaterecognizer_info;
+
 require_once WD . '/interfaces/universal_module_i.php';
 interface licenseplaterecognizer_i extends universal_module_i
 {
@@ -9,4 +12,10 @@ interface licenseplaterecognizer_i extends universal_module_i
      * @return array An array containing the plate number and other relevant information.
      */
     public function licenseplaterecognizer(string $base64_image): array;
+    /**
+     * Get usage information about the license plate recognizer module.
+     * @returns licenseplaterecognizer_info An object containing usage statistics and information.
+     * @see licenseplaterecognizer_info
+     */
+    public function get_usage(): licenseplaterecognizer_info;
 }
\ No newline at end of file
diff --git a/services/nginx/app/modules/licenseplaterecognizer/helpers/licenseplaterecognizer_info.php b/services/nginx/app/modules/licenseplaterecognizer/helpers/licenseplaterecognizer_info.php
new file mode 100644
index 00000000..672a0b46
--- /dev/null
+++ b/services/nginx/app/modules/licenseplaterecognizer/helpers/licenseplaterecognizer_info.php
@@ -0,0 +1,33 @@
+<?php
+
+namespace licenseplaterecognizer\helpers;
+
+/**
+ * @example raw response from license plate recognizer API
+ * {
+ *  "version": "1.54.0",
+ *  "usage": {
+ *      "calls": 98
+ *  },
+ * "license_key": "XXXXXXXXXX",
+ * "webhooks": [],
+ * "total_calls": 2500
+ * }
+ */
+class licenseplaterecognizer_info
+{
+    public string $version;
+    public object $usage; // e.g. {"calls": 98}
+    public string $license_key;
+    public array $webhooks;
+    public int $total_calls;
+
+    public function __construct($data)
+    {
+        $this->version = $data->version;
+        $this->usage = $data->usage ?? (object) ['calls' => 0];
+        $this->license_key = $data->license_key;
+        $this->webhooks = $data->webhooks;
+        $this->total_calls = $data->total_calls;
+    }
+}
\ No newline at end of file