Port parsing documentation

And new function method of defining a parser
convert default parser being careful to preserve functionality

Author: murrant

doc/Extensions/Interface-Description-Parsing.md

@@ -1,7 +1,7 @@
 # Interface Description Parsing
 
 Librenms can interpret, display and group certain additional information on ports.
-This is done based on the format that the port description is written
+This is done based on the format that the port description is written,
 although it's possible  to customise the parser to be specific for your setup.
 
 ## Keywords
@@ -63,11 +63,51 @@ It's also possible to write your own parser, the existing one is: includes/port-
 
 Once you've created your own then you can enable it with:
 
+!!! setting "webui/port-descr"
+    ```bash
+    lnms config:set port_descr_parser includes/custom/my-port-descr-parser.inc.php
+    ```
+
+Here is an example of a very simple file that parses type and descr.
 ```php
-$config['port_descr_parser'] = "includes/custom/my-port-descr-parser.inc.php";
+<?php
+
+return function (string $ifAlias): array {
+    if (! str_contains(':', $ifAlias)) {
+        return [];
+    }
+
+    $parts = explode(':', $ifAlias, 2);
+
+    return [
+        'type' => $parts[0],
+        'descr' => $parts[1],
+    ];
+};
 ```
 
-### Setup
+#### Fields
+
+Fields you can fill in your returned array
+
+ - type: port type (only defined types will show as graphs)
+ - descr: description of the port
+ - circuit: usually a circuit id
+ - speed: can be a plan name or a numeric speed 10G (or asymmetric 10G/500M), numeric speeds
+   can used by custom maps and some graphs
+ - notes: notes
+
+#### Variables
+
+Variables you can request for your function include:
+
+ - string $ifAlias
+ - int $port_id
+ - string $ifName
+ - int $ifIndex
+ - \App\Models\Device $device
+
+### Device Setup
 
 For Unix / Linux based systems, you need to run an additional script
 to support the parsing of interface information.

includes/polling/ports.inc.php

@@ -745,21 +745,27 @@
             ];
 
             $port_ifAlias = []; // for port descr parser mappings
-            include LibrenmsConfig::get('install_dir') . '/' . LibrenmsConfig::get('port_descr_parser');
+            $port_parser ??= include LibrenmsConfig::get('install_dir') . '/' . LibrenmsConfig::get('port_descr_parser');
+
+            // handle functional style parsers
+            if(is_callable($port_parser)) {
+                $port_ifAlias = app()->call($port_parser, [
+                    'ifAlias' => $this_port['ifAlias'] ,
+                    'ifIndex' => $port['ifIndex'],
+                    'ifName' => $this_port['ifName'],
+                    'port_id' => $port['port_id']
+                ]);
+            } else {
+                unset($port_parser);
+            }
 
             foreach ($port_attribs as $attrib) {
                 $attrib_key = 'port_descr_' . $attrib;
-                if (($port_ifAlias[$attrib] ?? null) != $port[$attrib_key]) {
-                    if (! isset($port_ifAlias[$attrib])) {
-                        $port_ifAlias[$attrib] = null;
-                        $log_port = 'NULL';
-                    } else {
-                        $log_port = $port_ifAlias[$attrib];
-                    }
+                $attrib_value = $port_ifAlias[$attrib] ?? null;
+                if ($attrib_value != $port[$attrib_key]) {
+                    $port['update'][$attrib_key] = $attrib_value;
 
-                    $port['update'][$attrib_key] = $port_ifAlias[$attrib];
-                    Eventlog::log($attrib . ': ' . $port[$attrib_key] . ' -> ' . $log_port, $device['device_id'], 'interface', Severity::Notice, $port['port_id']);
-                    unset($log_port);
+                    Eventlog::log($attrib . ': ' . $port[$attrib_key] . ' -> ' . ($attrib_value ?? 'NULL'), $device['device_id'], 'interface', Severity::Notice, $port['port_id']);
                 }
             }
         }//end if

includes/port-descr-parser.inc.php

@@ -1,25 +1,21 @@
 <?php
 
-// Parser should populate $port_ifAlias array with type, descr, circuit, speed and notes
-unset($port_ifAlias);
+// Parser should return an array with type, descr, circuit, speed and notes
 
-$split = preg_split('/[:\[\]{}()]/', (string) $this_port['ifAlias']);
-$type = isset($split[0]) ? trim($split[0]) : null;
-$descr = isset($split[1]) ? trim($split[1]) : null;
+return function (string $ifAlias): array {
+    $split = preg_split('/[:\[\]{}()]/', $ifAlias);
+    $type = trim($split[0] ?? '');
+    $descr = trim($split[1] ?? '');
 
-$circuit = trim(preg_split('/[{}]/', (string) $this_port['ifAlias'])[1] ?? '');
-$notes = trim(preg_split('/[()]/', (string) $this_port['ifAlias'])[1] ?? '');
-$speed = trim(preg_split('/[\[\]]/', (string) $this_port['ifAlias'])[1] ?? '');
+    if ($type && $descr) {
+        return [
+            'type' => strtolower($type),
+            'descr' => $descr,
+            'circuit' => trim(preg_split('/[{}]/', $ifAlias)[1] ?? ''),
+            'speed' => trim(preg_split('/[\[\]]/', $ifAlias)[1] ?? ''),
+            'notes' => trim(preg_split('/[()]/', $ifAlias)[1] ?? ''),
+        ];
+    }
 
-if ($type && $descr) {
-    $type = strtolower($type);
-    $port_ifAlias['type'] = $type;
-    $port_ifAlias['descr'] = $descr;
-    $port_ifAlias['circuit'] = $circuit;
-    $port_ifAlias['speed'] = substr($speed, 0, 32);
-    $port_ifAlias['notes'] = $notes;
-
-    d_echo($port_ifAlias);
-}
-
-unset($type, $descr, $circuit, $notes, $speed, $split);
+    return [];
+};