Security: verwijder hardcoded wachtwoord, voeg random-wachtwoord-generator toe bij eerste installatie

cms/core/class/GeoIP.php

@@ -1,13 +1,40 @@
 <?php
 
 /**
- * GeoIP - Country lookup provider chain (Local binary, MMDB, and API)
+ * GeoIP country lookup provider chain.
+ *
+ * Ondersteunt drie providers voor het resolueren van een landcode op basis
+ * van een IP-adres: een lokale binaire database (DB-IP), een MaxMind MMDB
+ * bestand en een externe API. Providers vallen terug op de lokale database
+ * wanneer een lookup geen resultaat oplevert.
+ *
+ * @since 2.6.4
  */
 class GeoIP
 {
+    /**
+     * De analytics-configuratie uit config.json.
+     *
+     * @since 2.6.4
+     * @var array Bevat o.a. geoip_provider, geoip_mmdb_path en geoip_api_url.
+     */
     private array $config;
+
+    /**
+     * FileCache instantie voor het cachen van API-lookups.
+     *
+     * @since 2.6.4
+     * @var FileCache|null
+     */
     private ?FileCache $cache = null;
 
+    /**
+     * Initialiseert de GeoIP-provider met de analytics-configuratie.
+     *
+     * @since 2.6.4
+     *
+     * @param array $analyticsConfig De "analytics" sectie uit config.json. Default lege array.
+     */
     public function __construct(array $analyticsConfig = [])
     {
         $this->config = $analyticsConfig;
@@ -16,10 +43,16 @@ class GeoIP
     }
 
     /**
-     * Resolve country code (2-letter ISO alpha-2, upper-case) from an IP address
+     * Resolves een 2-letter ISO alpha-2 landcode uit een IP-adres.
      *
-     * @param string $ip IPv4 or IPv6 address
-     * @return string|null Country code or null if unresolved/private
+     * De gekozen provider wordt gelezen uit de configuratie. Private en
+     * gereserveerde ranges worden direct afgewezen. MMDB en API vallen
+     * terug op de lokale database bij een mislukte lookup.
+     *
+     * @since 2.6.4
+     *
+     * @param string $ip IPv4- of IPv6-adres.
+     * @return string|null Landcode in hoofdletters, of null bij onoplosbare/private adressen.
      */
     public function lookupCountry(string $ip): ?string
     {
@@ -53,7 +86,15 @@ class GeoIP
     }
 
     /**
-     * Normalize a country code; placeholder codes (ZZ/XX) count as unknown
+     * Normaliseert een landcode en verwerpt placeholder codes.
+     *
+     * Geldige codes zijn exact twee letters. De codes ZZ en XX worden
+     * beschouwd als onbekend en resulteren in null.
+     *
+     * @since 2.6.4
+     *
+     * @param string|null $code Ruwe landcode uit een provider.
+     * @return string|null Genormaliseerde landcode of null indien ongeldig/onbekend.
      */
     private static function normalizeCode(?string $code): ?string
     {
@@ -65,7 +106,16 @@ class GeoIP
     }
 
     /**
-     * Binary search lookup in local DB-IP IPv4/IPv6 binary files
+     * Binaire zoekopdracht in lokale DB-IP IPv4/IPv6 binaire bestanden.
+     *
+     * Leest de bestanden uit `admin/storage/geoip` en voert een binaire
+     * zoekopdracht uit op basis van het IP-adres. Ondersteunt zowel IPv4
+     * (10-byte records) als IPv6 (34-byte records).
+     *
+     * @since 2.6.4
+     *
+     * @param string $ip IPv4- of IPv6-adres.
+     * @return string|null Landcode in hoofdletters of null indien niet gevonden.
      */
     public function lookupLocal(string $ip): ?string
     {
@@ -161,7 +211,16 @@ class GeoIP
     }
 
     /**
-     * External API lookup with caching
+     * Externe API-lookup met caching.
+     *
+     * Stuurt een HTTP-verzoek naar de geconfigureerde GeoIP API en cachet
+     * het resultaat zeven dagen in een FileCache. De API-URL mag een
+     * optionele API-key bevatten.
+     *
+     * @since 2.6.4
+     *
+     * @param string $ip IPv4- of IPv6-adres.
+     * @return string|null Landcode of null indien de lookup faalt.
      */
     private function lookupApi(string $ip): ?string
     {
@@ -192,7 +251,16 @@ class GeoIP
     }
 
     /**
-     * Pure-PHP MaxMind MMDB reader
+     * Pure-PHP MaxMind MMDB reader.
+     *
+     * Opent een MMDB-bestand en extraheert de landcode via de ingebouwde
+     * MMDBReader. Fouten worden gesilenced en resulteren in null.
+     *
+     * @since 2.6.4
+     *
+     * @param string $ip       IPv4- of IPv6-adres.
+     * @param string $filePath Pad naar het MMDB-bestand.
+     * @return string|null Landcode of null bij een fout.
      */
     private function lookupMMDB(string $ip, string $filePath): ?string
     {
@@ -206,7 +274,12 @@ class GeoIP
     }
 
     /**
-     * Convert 2-letter ISO country code to regional indicator flag emoji
+     * Zet een 2-letter ISO landcode om naar een regionale vlag-emoji.
+     *
+     * @since 2.6.4
+     *
+     * @param string|null $code Landcode of null.
+     * @return string Vlag-emoji of een wereldbol bij ongeldige invoer.
      */
     public static function getCountryFlagEmoji(?string $code): string
     {
@@ -222,7 +295,17 @@ class GeoIP
     }
 
     /**
-     * Get country name in Dutch or English
+     * Geeft de landnaam in Nederlands of Engels.
+     *
+     * Bevat een statische mapping van de meest voorkomende landcodes naar
+     * hun naam in de gevraagde taal. Onbekende codes worden ongewijzigd
+     * teruggegeven.
+     *
+     * @since 2.6.4
+     *
+     * @param string|null $code Landcode of null.
+     * @param string      $lang Gewenste taal, 'nl' of 'en'. Default 'nl'.
+     * @return string Landnaam in de gevraagde taal of de code zelf.
      */
     public static function getCountryName(?string $code, string $lang = 'nl'): string
     {
@@ -275,14 +358,49 @@ class GeoIP
 }
 
 /**
- * Built-in pure-PHP MaxMind DB Reader
+ * Ingebouwde pure-PHP MaxMind DB reader.
+ *
+ * Minimale implementatie van de MaxMind DB binary reader, nodig omdat de
+ * externe GeoIP2 dependency optioneel is. Ondersteunt 28-bit record sizes
+ * en de veelvoorkomende datatypes (pointer, string, map, uint, bool).
+ *
+ * @since 2.6.4
  */
 class MMDBReader
 {
+    /**
+     * Pad naar het MMDB-bestand.
+     *
+     * @since 2.6.4
+     * @var string
+     */
     private string $file;
+
+    /**
+     * Bestandshandle voor het MMDB-bestand.
+     *
+     * @since 2.6.4
+     * @var resource|null
+     */
     private $handle;
+
+    /**
+     * Metadata uit de MMDB-header.
+     *
+     * @since 2.6.4
+     * @var array Bevat o.a. node_count, record_size en ip_version.
+     */
     private array $meta;
 
+    /**
+     * Opent het MMDB-bestand en laadt de metadata.
+     *
+     * @since 2.6.4
+     *
+     * @param string $file Pad naar het MMDB-bestand.
+     * @throws \InvalidArgumentException Als het bestand niet bestaat.
+     * @throws \RuntimeException Als het bestandformaat ongeldig is.
+     */
     public function __construct(string $file)
     {
         if (!file_exists($file)) {
@@ -293,6 +411,11 @@ class MMDBReader
         $this->loadMetadata();
     }
 
+    /**
+     * Sluit de bestandshandle bij het vernietigen van de instantie.
+     *
+     * @since 2.6.4
+     */
     public function __destruct()
     {
         if ($this->handle) {
@@ -300,6 +423,16 @@ class MMDBReader
         }
     }
 
+    /**
+     * Laadt de MMDB-metadata vanaf het einde van het bestand.
+     *
+     * Zoekt naar de MaxMind marker en decodeert de daaropvolgende data.
+     *
+     * @since 2.6.4
+     *
+     * @throws \RuntimeException Als de marker niet gevonden wordt.
+     * @return void
+     */
     private function loadMetadata(): void
     {
         $stat = fstat($this->handle);
@@ -319,6 +452,18 @@ class MMDBReader
         $this->meta = $this->decodeData($metaOffset)[0];
     }
 
+    /**
+     * Voert een lookup uit voor een IP-adres in de MMDB-boom.
+     *
+     * Werkt door de binaire boom te doorlopen op basis van de bits van het
+     * IP-adres. IPv4-adressen in een IPv6-boom worden correct afgehandeld
+     * via de ipv4_instance_count metadata.
+     *
+     * @since 2.6.4
+     *
+     * @param string $ip IPv4- of IPv6-adres.
+     * @return array|null Gedecodeerde datarecord of null indien niet gevonden.
+     */
     public function get(string $ip): ?array
     {
         $ipBin = inet_pton($ip);
@@ -355,6 +500,18 @@ class MMDBReader
         return null;
     }
 
+    /**
+     * Leest een kind-node (left/right) uit de MMDB-boom.
+     *
+     * Ondersteunt uitsluitend 28-bit record sizes.
+     *
+     * @since 2.6.4
+     *
+     * @param int $node       Huidig node-index.
+     * @param int $bit        Bitwaarde (0 voor left, 1 voor right).
+     * @param int $recordSize Record size in bits.
+     * @return int Doel-node-index of 0 bij niet-ondersteunde record sizes.
+     */
     private function readNode(int $node, int $bit, int $recordSize): int
     {
         $bytesPerRecord = $recordSize / 4; // 28-bit -> 3.5 bytes per record
@@ -372,6 +529,18 @@ class MMDBReader
         return 0;
     }
 
+    /**
+     * Decodeert een MMDB-datarecord vanaf de gegeven offset.
+     *
+     * Ondersteunt pointer, string, double, uint, map en bool. De array
+     * return value bevat de gedecodeerde waarde en de cursorpositie na
+     * het record.
+     *
+     * @since 2.6.4
+     *
+     * @param int $offset Start-offset in het bestand.
+     * @return array Pair [mixed $value, int $newOffset].
+     */
     private function decodeData(int $offset): array
     {
         fseek($this->handle, $offset);