<?php
/**
 * Network Helper Class
 *
 * @version     1.0.$Revision:$
 * @version     SVN: $Id:$
 * @package     bplan-base/globals
 * @subpackage  Support
 * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
 * @copyright   Copyright (C) 2025, 2026 bplan-solutions GmbH & Co. KG <https://www.bplan-solutions.de/>
 * /Δ\
 */

namespace BplanBase\Globals\Support;


/**
 * Network Helper Class
 *
 * Hilfsmethoden für netzwerkbezogene Operationen.
 *
 * @version     1.0.0 / 2026-05-10
 * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
 */
class Network
{


/* +++ TRAITS +++ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ */


/* +++ CLASS CONSTANTS +++ ++++++++++++++++++++++++++++++++++++++++++++++++++ */


/* +++ OBJECT MEMBERS +++ +++++++++++++++++++++++++++++++++++++++++++++++++++ */


/* +++ CLASS MEMBERS +++ ++++++++++++++++++++++++++++++++++++++++++++++++++++ */


/* +++ OBJECT METHODS +++ +++++++++++++++++++++++++++++++++++++++++++++++++++ */


/* +++ CLASS METHODS +++ ++++++++++++++++++++++++++++++++++++++++++++++++++++ */


    /**
     * Ermittelt die lokale IP-Adresse des Rechners über einen UDP-Socket.
     *
     * Der UDP-Trick öffnet einen Socket in Richtung einer Ziel-IP und liest
     * dann die lokale Absender-Adresse aus — ohne tatsächlich Daten zu senden.
     * Das liefert die IP des Netzwerk-Interfaces, das für die Route zur Ziel-IP
     * verwendet würde.
     *
     * Als Standard-Ziel wird 8.8.8.8 (Google DNS) verwendet. Auf Rechnern ohne
     * Internetzugang oder in geschlossenen Netzwerken sollte stattdessen die IP
     * eines erreichbaren Rechners im lokalen Netz übergeben werden — z.B. die IP
     * des PrintService-Rechners.
     *
     * @param       string|null $targetIp
     *              Ziel-IP für die Routen-Ermittlung. Standard: '8.8.8.8'.
     *
     * @return      string|null
     *              Lokale IP-Adresse, oder null wenn die Ermittlung fehlschlägt.
     *
     * @version     1.0.0 / 2026-05-10
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function getLocalIp(?string $targetIp = null): ?string
    {
        $target = $targetIp ?? '8.8.8.8';
        $ip     = null;

        $socket = @socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);

        if ($socket === false) {
            return null;
        }

        @socket_connect($socket, $target, 80);
        @socket_getsockname($socket, $ip);
        @socket_close($socket);

        return $ip ?: null;

    } // getLocalIp()


} // class Network {}
