ServerDataVariable
in package
Class ServerRepository
Provides read/write access to server records stored by binary IP address. Supports PSR-16 caching, dynamic metric updates, and automatic timestamp management.
Table of Contents
Constants
- CACHE_TTL_SECONDS : mixed = 86400
Properties
- $cache : CacheInterface
- $connection : Database
- $datetime : DateTime
- $ipBinaryColumn : string
- $ipOutputKey : string
- $lastActiveAtColumn : string
- $lastUpdateAtColumn : string
- $mutableColumns : array<string|int, mixed>
- $tableName : string
Methods
- __construct() : mixed
- binaryToIp() : string
- Converts a binary IP representation to its textual form.
- clearCache() : void
- Removes the cached entry for the given IP address.
- exists() : bool
- Checks whether a server record exists for the given IP address.
- get() : array<string, mixed>
- Returns full server data for the given IP address.
- getValue() : mixed
- Returns a single value from the server record.
- ipToBinary() : string
- Converts a textual IP address to binary representation.
- refresh() : array<string, mixed>
- Forces a fresh database read and stores the result in cache.
- set() : array<string, mixed>
- Inserts or updates a server record.
- touchLastActiveAt() : bool
- Updates only the last_active_at timestamp.
- touchLastUpdateAt() : bool
- Updates only the last_update_at timestamp.
- updateLiveStats() : array<string, mixed>
- Updates live server metrics such as CPU, RAM, disk usage, load, or network statistics.
- arrayGetByDotPath() : mixed
- Reads a nested value from an array using dot notation.
- cacheServerRow() : array<string, mixed>
- Stores a row in cache and returns it unchanged.
- fetchByBinaryIp() : array<string, mixed>
- Fetches a server record by binary IP address.
- fetchByIp() : array<string, mixed>
- Fetches a server record by textual IP address.
- getCacheKey() : string
- Builds the cache key for a given IP address.
- hasChanges() : bool
- Determines whether the payload differs from the current database row.
- insertRow() : void
- Inserts a new database row.
- isMutableColumn() : bool
- Checks whether the given column is allowed to be updated dynamically.
- mapDataValues() : array<string, mixed>
- Maps database values to their corresponding PHP types.
- normalizeFetchedRow() : array<string, mixed>
- Adds the human-readable IP address to a fetched database row.
- normalizePayload() : array<string, mixed>
- Filters and normalizes incoming payload values.
- normalizeValue() : mixed
- Normalizes a value before database storage or comparison.
- now() : string
- Returns the current timestamp string used for persistence.
- updateRowByBinaryIp() : int
- Updates a database row identified by binary IP address.
Constants
CACHE_TTL_SECONDS
private
mixed
CACHE_TTL_SECONDS
= 86400
Properties
$cache read-only
private
CacheInterface
$cache
$connection read-only
private
Database
$connection
$datetime read-only
private
DateTime
$datetime
$ipBinaryColumn read-only
private
string
$ipBinaryColumn
= 'ip_address'
$ipOutputKey read-only
private
string
$ipOutputKey
= 'ip'
$lastActiveAtColumn read-only
private
string
$lastActiveAtColumn
= 'last_online_at'
$lastUpdateAtColumn read-only
private
string
$lastUpdateAtColumn
= 'updated_at'
$mutableColumns read-only
private
array<string|int, mixed>
$mutableColumns
= ['hostname', 'os_name', 'os_version', 'ip_address', 'is_active', 'cpu_cores', 'total_ram_mb', 'total_disk_gb', 'cpu_load', 'used_ram_mb', 'used_disk_gb', 'last_online_at', 'metadata']
$tableName read-only
private
string
$tableName
= 'servers'
Methods
__construct()
public
__construct(Database $connection, CacheInterface $cache, DateTime $datetime[, string $tableName = 'servers' ][, string $ipBinaryColumn = 'ip_address' ][, string $ipOutputKey = 'ip' ][, string $lastActiveAtColumn = 'last_online_at' ][, string $lastUpdateAtColumn = 'updated_at' ][, array<string|int, string> $mutableColumns = ['hostname', 'os_name', 'os_version', 'ip_address', 'is_active', 'cpu_cores', 'total_ram_mb', 'total_disk_gb', 'cpu_load', 'used_ram_mb', 'used_disk_gb', 'last_online_at', 'metadata'] ]) : mixed
Parameters
- $connection : Database
-
Doctrine DBAL connection instance.
- $cache : CacheInterface
-
PSR-16 cache implementation.
- $datetime : DateTime
-
Atom Datetime class suit
- $tableName : string = 'servers'
-
Database table name.
- $ipBinaryColumn : string = 'ip_address'
-
Column name that stores the binary IP address.
- $ipOutputKey : string = 'ip'
-
Array key used for the human-readable IP address.
- $lastActiveAtColumn : string = 'last_online_at'
-
Column name storing the last activity timestamp.
- $lastUpdateAtColumn : string = 'updated_at'
-
Column name storing the last data update timestamp.
- $mutableColumns : array<string|int, string> = ['hostname', 'os_name', 'os_version', 'ip_address', 'is_active', 'cpu_cores', 'total_ram_mb', 'total_disk_gb', 'cpu_load', 'used_ram_mb', 'used_disk_gb', 'last_online_at', 'metadata']
-
List of columns that can be updated dynamically.
binaryToIp()
Converts a binary IP representation to its textual form.
public
binaryToIp(string $binaryIp) : string
Parameters
- $binaryIp : string
-
Binary IP value.
Return values
string —IPv4 or IPv6 string representation.
clearCache()
Removes the cached entry for the given IP address.
public
clearCache(string $ip) : void
Parameters
- $ip : string
-
Server IP address in IPv4 or IPv6 format.
exists()
Checks whether a server record exists for the given IP address.
public
exists(string $ip) : bool
Parameters
- $ip : string
-
Server IP address in IPv4 or IPv6 format.
Return values
bool —True if the record exists, false otherwise.
get()
Returns full server data for the given IP address.
public
get(string $ip[, bool $forceRefresh = false ]) : array<string, mixed>
The method reads from cache first and falls back to the database when the cache is empty or a refresh is forced.
Parameters
- $ip : string
-
Server IP address in IPv4 or IPv6 format.
- $forceRefresh : bool = false
-
When true, bypasses cache and reloads data from the database.
Return values
array<string, mixed> —Server record data.
getValue()
Returns a single value from the server record.
public
getValue(string $ip, string $key[, mixed $default = null ]) : mixed
Dot notation is supported for nested arrays, for example: "meta.cpu.model".
Parameters
- $ip : string
-
Server IP address in IPv4 or IPv6 format.
- $key : string
-
Value key or dot-notated path.
- $default : mixed = null
-
Default value returned when the key does not exist.
ipToBinary()
Converts a textual IP address to binary representation.
public
ipToBinary(string $ip) : string
Parameters
- $ip : string
-
Server IP address in IPv4 or IPv6 format.
Return values
string —Binary IP representation.
refresh()
Forces a fresh database read and stores the result in cache.
public
refresh(string $ip) : array<string, mixed>
Parameters
- $ip : string
-
Server IP address in IPv4 or IPv6 format.
Return values
array<string, mixed> —Fresh server record.
set()
Inserts or updates a server record.
public
set(string $ip, array<string, mixed> $data[, bool $touchLastActive = true ]) : array<string, mixed>
Only columns listed in $mutableColumns are accepted. When any mutable value changes, last_update_at is refreshed automatically. When $touchLastActive is true, last_active_at is also updated.
Parameters
- $ip : string
-
Server IP address in IPv4 or IPv6 format.
- $data : array<string, mixed>
-
Associative array of columns and values.
- $touchLastActive : bool = true
-
Whether to update last_active_at as well.
Return values
array<string, mixed> —Fresh server record after persistence.
touchLastActiveAt()
Updates only the last_active_at timestamp.
public
touchLastActiveAt(string $ip) : bool
Parameters
- $ip : string
-
Server IP address in IPv4 or IPv6 format.
Return values
bool —True on successful update, false otherwise.
touchLastUpdateAt()
Updates only the last_update_at timestamp.
public
touchLastUpdateAt(string $ip) : bool
Parameters
- $ip : string
-
Server IP address in IPv4 or IPv6 format.
Return values
bool —True on successful update, false otherwise.
updateLiveStats()
Updates live server metrics such as CPU, RAM, disk usage, load, or network statistics.
public
updateLiveStats(string $ip, array<string, mixed> $metrics[, bool $touchLastActive = true ]) : array<string, mixed>
This is a semantic wrapper around set() intended for real-time monitoring data.
Parameters
- $ip : string
-
Server IP address in IPv4 or IPv6 format.
- $metrics : array<string, mixed>
-
Associative array of live metrics.
- $touchLastActive : bool = true
-
Whether to update last_active_at as well.
Return values
array<string, mixed> —Fresh server record after persistence.
arrayGetByDotPath()
Reads a nested value from an array using dot notation.
private
arrayGetByDotPath(array<string, mixed> $data, string $path[, mixed $default = null ]) : mixed
Parameters
- $data : array<string, mixed>
-
Source array.
- $path : string
-
Dot-notated key path.
- $default : mixed = null
-
Default value when the path does not exist.
cacheServerRow()
Stores a row in cache and returns it unchanged.
private
cacheServerRow(string $ip, array<string, mixed> $row) : array<string, mixed>
Parameters
- $ip : string
-
Server IP address in IPv4 or IPv6 format.
- $row : array<string, mixed>
-
Server record.
Return values
array<string, mixed> —Cached server record.
fetchByBinaryIp()
Fetches a server record by binary IP address.
private
fetchByBinaryIp(string $binaryIp) : array<string, mixed>
Parameters
- $binaryIp : string
-
Binary IP representation.
Return values
array<string, mixed> —Server record or an empty array when not found.
fetchByIp()
Fetches a server record by textual IP address.
private
fetchByIp(string $ip) : array<string, mixed>
Parameters
- $ip : string
-
Server IP address in IPv4 or IPv6 format.
Return values
array<string, mixed> —Server record or an empty array when not found.
getCacheKey()
Builds the cache key for a given IP address.
private
getCacheKey(string $ip) : string
Parameters
- $ip : string
-
Server IP address in IPv4 or IPv6 format.
Return values
string —Cache key.
hasChanges()
Determines whether the payload differs from the current database row.
private
hasChanges(array<string, mixed> $current, array<string, mixed> $payload) : bool
Parameters
- $current : array<string, mixed>
-
Current database row.
- $payload : array<string, mixed>
-
Incoming payload.
Return values
bool —True when at least one value differs.
insertRow()
Inserts a new database row.
private
insertRow(array<string, mixed> $data) : void
Parameters
- $data : array<string, mixed>
-
Associative array of column names and values.
isMutableColumn()
Checks whether the given column is allowed to be updated dynamically.
private
isMutableColumn(string $column) : bool
Parameters
- $column : string
-
Column name.
Return values
bool —True when the column is mutable.
mapDataValues()
Maps database values to their corresponding PHP types.
private
mapDataValues(array<string, mixed> $row) : array<string, mixed>
Parameters
- $row : array<string, mixed>
-
Raw database row.
Return values
array<string, mixed> —Mapped row.
normalizeFetchedRow()
Adds the human-readable IP address to a fetched database row.
private
normalizeFetchedRow(array<string, mixed> $row, string $binaryIp) : array<string, mixed>
Parameters
- $row : array<string, mixed>
-
Raw database row.
- $binaryIp : string
-
Binary IP representation.
Return values
array<string, mixed> —Normalized row.
normalizePayload()
Filters and normalizes incoming payload values.
private
normalizePayload(array<string, mixed> $data) : array<string, mixed>
Parameters
- $data : array<string, mixed>
-
Input data.
Return values
array<string, mixed> —Normalized payload.
normalizeValue()
Normalizes a value before database storage or comparison.
private
normalizeValue(mixed $value) : mixed
Parameters
- $value : mixed
-
Input value.
Return values
mixed —Normalized value.
now()
Returns the current timestamp string used for persistence.
private
now() : string
Return values
string —Current datetime in Y-m-d H:i:s format.
updateRowByBinaryIp()
Updates a database row identified by binary IP address.
private
updateRowByBinaryIp(string $binaryIp, array<string, mixed> $data) : int
Parameters
- $binaryIp : string
-
Binary IP representation.
- $data : array<string, mixed>
-
Associative array of column names and values.
Return values
int —Number of affected rows.