dolibarr.netdiag/lib/netdiag.lib.php

<?php
/* Copyright (C) 2026 Eduard Wisch <data@data-it-solution.de>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <https://www.gnu.org/licenses/>.
 */

/**
 *  \file       htdocs/custom/netdiag/lib/netdiag.lib.php
 *  \ingroup    netdiag
 *  \brief      Hilfsfunktionen für das Modul NetDiag
 */

/**
 * Tabs für die Admin-Seiten des Moduls vorbereiten
 *
 * @return array<int,array<int,string>> Tab-Array
 */
function netdiagAdminPrepareHead()
{
	global $langs, $conf;

	$langs->load("netdiag@netdiag");

	$h = 0;
	$head = array();

	$head[$h][0] = dol_buildpath("/netdiag/admin/setup.php", 1);
	$head[$h][1] = $langs->trans("Settings");
	$head[$h][2] = 'settings';
	$h++;

	$head[$h][0] = dol_buildpath("/netdiag/admin/about.php", 1);
	$head[$h][1] = $langs->trans("About");
	$head[$h][2] = 'about';
	$h++;

	complete_head_from_modules($conf, $langs, null, $head, $h, 'netdiag@netdiag');
	complete_head_from_modules($conf, $langs, null, $head, $h, 'netdiag@netdiag', 'remove');

	return $head;
}

/**
 * Tabs für die Detailansicht eines Diagnose-Protokolls vorbereiten
 *
 * @param  NetDiagProtocol $object Protokoll-Objekt
 * @return array<int,array<int,string>> Tab-Array
 */
function netdiagProtocolPrepareHead($object)
{
	global $langs, $conf;

	$langs->load("netdiag@netdiag");

	$h = 0;
	$head = array();

	$head[$h][0] = dol_buildpath("/netdiag/netdiagprotocol_card.php", 1).'?id='.$object->id;
	$head[$h][1] = $langs->trans("NetDiagProtocol");
	$head[$h][2] = 'card';
	$h++;

	complete_head_from_modules($conf, $langs, $object, $head, $h, 'netdiagprotocol@netdiag');
	complete_head_from_modules($conf, $langs, $object, $head, $h, 'netdiagprotocol@netdiag', 'remove');

	return $head;
}

/**
 * Ausgabeverzeichnis des Moduls ermitteln (für PDF-Dokumente)
 *
 * @return string Absoluter Pfad zum Dokumentenverzeichnis
 */
function netdiagGetOutputDir()
{
	global $conf;
	if (!empty($conf->netdiag->dir_output)) {
		return $conf->netdiag->dir_output;
	}
	return DOL_DATA_ROOT.'/netdiag';
}

/**
 * Ein Mess-Ergebnis (JSON) lesbar als HTML aufbereiten.
 *
 * Generisch: rendert flache Schlüssel/Wert-Paare und einfache Listen,
 * damit auch künftige Tools ohne Code-Änderung dargestellt werden. Jeder Wert
 * wird auf 200 Zeichen gekürzt (`dol_trunc`) — für Skalare unschädlich, aber
 * ein Dauertest mit vielen Ausfällen/Minuten-Buckets würde dabei mitten im
 * Satz abgeschnitten. Für `$tool === 'stresstest'` deshalb eigener, nicht
 * gekürzter Zweig (siehe netdiagFormatStressTest) — dieselbe Notlösung wie
 * netdiagPdfStressTest() im PDF-Generator.
 *
 * @param  string $json JSON-String des Ergebnisses
 * @param  string $tool Werkzeug-ID der Messung (optional, für Sonderfälle)
 * @return string       HTML-Schnipsel
 */
function netdiagFormatResult($json, $tool = '')
{
	if (empty($json)) {
		return '<span class="opacitymedium">-</span>';
	}
	$data = json_decode($json, true);
	if ($data === null) {
		return dol_escape_htmltag(dol_trunc($json, 120));
	}
	if (!is_array($data)) {
		return dol_escape_htmltag((string) $data);
	}
	if ($tool === 'stresstest') {
		return netdiagFormatStressTest($data);
	}
	if ($tool === 'wifikanal') {
		return netdiagFormatWifiKanal($data);
	}

	$out = '<div class="netdiag-result">';
	foreach ($data as $key => $val) {
		$label = dol_escape_htmltag(ucfirst((string) $key));
		if (is_array($val)) {
			$flat = array();
			foreach ($val as $item) {
				$flat[] = is_array($item) ? json_encode($item, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES) : (string) $item;
			}
			$valstr = implode(', ', $flat);
		} elseif (is_bool($val)) {
			$valstr = $val ? 'ja' : 'nein';
		} else {
			$valstr = (string) $val;
		}
		$out .= '<span class="netdiag-kv"><strong>'.$label.':</strong> '.dol_escape_htmltag(dol_trunc($valstr, 200)).'</span> ';
	}
	$out .= '</div>';
	return $out;
}

/**
 * Dauer-/Stresstest-Ergebnis strukturiert als HTML aufbereiten (Kennzahlen +
 * Ausfallliste, ungekürzt) statt es wie ein generisches Werkzeug zu
 * behandeln — sonst schneidet dol_trunc(...,200) die Ausfallliste eines
 * längeren Laufs mitten im Satz ab.
 *
 * @param  array<string,mixed> $data bereits dekodiertes result-JSON
 * @return string                    HTML-Schnipsel
 */
function netdiagFormatStressTest($data)
{
	if (!empty($data['hinweis']) || !empty($data['fehler'])) {
		return '<span class="opacitymedium">'.dol_escape_htmltag((string) ($data['hinweis'] ?? $data['fehler'])).'</span>';
	}

	$sum = array();
	if (isset($data['host'])) {
		$sum[] = 'Ziel: '.$data['host'];
	}
	if (isset($data['dauerSekunden'])) {
		$sum[] = 'Dauer: '.round($data['dauerSekunden'] / 60).' min';
	}
	if (isset($data['intervallSek'])) {
		$sum[] = 'Takt: '.$data['intervallSek'].' s';
	}
	if (isset($data['gesendet']) && isset($data['empfangen'])) {
		$sum[] = 'Proben: '.$data['empfangen'].'/'.$data['gesendet'];
	}
	if (isset($data['verlustProzent'])) {
		$sum[] = 'Verlust: '.$data['verlustProzent'].' %';
	}
	if (isset($data['avgMs']) && $data['avgMs'] !== null) {
		$sum[] = 'Ø '.$data['avgMs'].' ms';
	}
	if (isset($data['minMs']) && isset($data['maxMs']) && $data['minMs'] !== null) {
		$sum[] = 'Min/Max '.$data['minMs'].'/'.$data['maxMs'].' ms';
	}
	if (isset($data['p95Ms']) && $data['p95Ms'] !== null) {
		$sum[] = 'p95 '.$data['p95Ms'].' ms';
	}
	if (isset($data['laengsterAusfallSek']) && $data['laengsterAusfallSek'] !== null) {
		$sum[] = 'längster Ausfall '.$data['laengsterAusfallSek'].' s';
	}

	$out = '<div class="netdiag-result"><div class="netdiag-kv">'.dol_escape_htmltag(implode('  |  ', $sum)).'</div>';

	$ausfaelle = (isset($data['ausfaelle']) && is_array($data['ausfaelle'])) ? $data['ausfaelle'] : array();
	if (empty($ausfaelle)) {
		$out .= '<div class="opacitymedium">Kein Ausfall während des Laufs.</div>';
	} else {
		$out .= '<div><strong>Ausfälle ('.count($ausfaelle).'):</strong></div><ul class="netdiag-outages">';
		foreach ($ausfaelle as $line) {
			$out .= '<li>'.dol_escape_htmltag((string) $line).'</li>';
		}
		$out .= '</ul>';
	}
	$out .= '</div>';
	return $out;
}

/**
 * WLAN-Kanal-Momentaufnahme strukturiert als HTML aufbereiten.
 *
 * Wie beim Dauertest ein eigener Zweig statt der generischen Darstellung:
 * `netze` ist eine Liste von Objekten und würde dort als JSON-Text mit
 * dol_trunc(…,200) mitten im Satz abgeschnitten.
 *
 * @param  array<string,mixed> $data bereits dekodiertes result-JSON
 * @return string                    HTML-Schnipsel
 */
function netdiagFormatWifiKanal($data)
{
	$out = '<div class="netdiag-result">';

	$sum = array();
	if (isset($data['anzahlNetze'])) {
		$sum[] = $data['anzahlNetze'].' Netze sichtbar';
	}
	if (!empty($data['eigenesNetz']) && is_array($data['eigenesNetz'])) {
		$e = $data['eigenesNetz'];
		$teil = 'Eigenes Netz: '.($e['ssid'] ?? '?').' — Kanal '.($e['kanal'] ?? '?');
		if (!empty($e['band'])) {
			$teil .= ' ('.$e['band'].')';
		}
		if (isset($e['rssi'])) {
			$teil .= ', '.$e['rssi'].' dBm';
		}
		if (!empty($e['bewertung'])) {
			$teil .= ' — '.$e['bewertung'];
		}
		$sum[] = $teil;
	}
	if (!empty($data['empfehlung24GHz']) && is_array($data['empfehlung24GHz'])) {
		$best = reset($data['empfehlung24GHz']);
		if (is_array($best) && isset($best['kanal'])) {
			$sum[] = 'Störungsärmster 2,4-GHz-Kanal: '.$best['kanal'];
		}
	}
	if (!empty($sum)) {
		$out .= '<div class="netdiag-kv">'.dol_escape_htmltag(implode('  |  ', $sum)).'</div>';
	}

	if (!empty($data['warnungen']) && is_array($data['warnungen'])) {
		$out .= '<div><strong>Hinweise:</strong></div><ul class="netdiag-outages">';
		foreach ($data['warnungen'] as $w) {
			$out .= '<li>'.dol_escape_htmltag((string) $w).'</li>';
		}
		$out .= '</ul>';
	}

	$netze = (isset($data['netze']) && is_array($data['netze'])) ? $data['netze'] : array();
	if (!empty($netze)) {
		$out .= '<table class="noborder centpercent"><tr class="liste_titre">';
		$out .= '<th>SSID</th><th class="center">Kanal</th><th>Band</th>';
		$out .= '<th class="center">Breite</th><th>Standard</th><th>Sicherheit</th><th class="right">Pegel</th>';
		$out .= '</tr>';
		foreach ($netze as $n) {
			if (!is_array($n)) {
				continue;
			}
			$out .= '<tr class="oddeven">';
			$out .= '<td>'.dol_escape_htmltag((string) ($n['ssid'] ?? '')).'</td>';
			$out .= '<td class="center">'.dol_escape_htmltag((string) ($n['kanal'] ?? '')).'</td>';
			$out .= '<td>'.dol_escape_htmltag((string) ($n['band'] ?? '')).'</td>';
			$out .= '<td class="center">'.(isset($n['breiteMhz']) && $n['breiteMhz'] !== null ? dol_escape_htmltag($n['breiteMhz'].' MHz') : '-').'</td>';
			$out .= '<td>'.dol_escape_htmltag((string) ($n['standard'] ?? '-')).'</td>';
			$out .= '<td>'.dol_escape_htmltag((string) ($n['sicherheit'] ?? '-')).'</td>';
			$out .= '<td class="right">'.dol_escape_htmltag((string) ($n['rssi'] ?? '')).' dBm</td>';
			$out .= '</tr>';
		}
		$out .= '</table>';
	}

	$out .= '</div>';
	return $out;
}