Log

Reference for the Log module: write typed log messages gated by a configured level, record named numeric counters aggregated into per-minute timeslots, time callbacks, and buffer counter increments in shared memory. Every class and function, with its full signature, parameters and return type.

This page is a pure reference. For how the framework fits together, see the Guide.

Classes

Log - static functions for writing typed log messages, gated by the configured log level.
LogConfig - registers callbacks invoked when an alert is logged.
LogCounter - records named numeric values and increments, buffered or written straight to the database.
LogCounterBuffer - an APCu-backed write buffer that folds counter increments into the database once per minute.
LogCounterCountByDayData - a counter total for one calendar day.
LogCounterCountByHourData - a counter total for one hour of the day.
LogCounterCountByMonthData - a counter total for one calendar month.
LogCounterData - one aggregated counter row for a module, identifier, argument and timeslot.
LogCounterDatabase - the database layer for counters: upserts, time-bucketing and aggregate reads.
LogDatabase - the database layer for log messages.
LogTimer - times a callback and records the elapsed seconds as a counter value.
LogTypeEnum - the numeric log level constants, from alert down to debug.

Log

Static functions for writing log messages. Each level is only written when the configured LOG_LEVEL is at least that level; every message also increments a counter for its level. Writes go to the database, with a fallback to the error file and then the registered alert callbacks.

Functions

Alert Debug encodeDetails Error Exception Info

Alert

Log::Alert(string $moduleName, string $message, mixed $details = []): void

Log an alert: write it to the database and the error file, then run every registered alert callback. Also increments the ALERT counter.

Name	Type	Description
`$moduleName`	`string`	The module the alert relates to.
`$message`	`string`	The alert message.
`$details`	`mixed`	Extra detail, encoded into the log entry. Defaults to an empty array.

Returns void

Debug

Log::Debug(string $moduleName, string $message, mixed $details = []): void

Log a debug message when the log level allows it. Also increments the DEBUG counter.

Name	Type	Description
`$moduleName`	`string`	The module the message relates to.
`$message`	`string`	The debug message.
`$details`	`mixed`	Extra detail, encoded into the log entry. Defaults to an empty array.

Returns void

encodeDetails

Log::encodeDetails(array $details): string

Encode an associative details array to text, tolerating individual entries that cannot be JSON encoded (a bad value becomes an error marker; a bad key is dropped).

Name	Type	Description
`$details`	`array`	The details to encode.

Returns string The encoded details text.

Error

Log::Error(string $moduleName, string $message, array $details = []): void

Log an error when the log level allows it, falling back to the error file and then the alert callbacks if the database write fails. Also increments the ERROR counter.

Name	Type	Description
`$moduleName`	`string`	The module the error relates to.
`$message`	`string`	The error message.
`$details`	`array`	Extra detail, encoded into the log entry. Defaults to an empty array.

Returns void

Exception

Log::Exception(string $moduleName, string $message, Throwable $ex, array $details = []): void

Log a caught throwable, recording its type, message, code, file, line and stack trace alongside the given details. Also increments the EXCEPTION counter.

Name	Type	Description
`$moduleName`	`string`	The module the exception relates to.
`$message`	`string`	A message describing the context.
`$ex`	`Throwable`	The caught throwable to record.
`$details`	`array`	Extra detail, encoded into the log entry. Defaults to an empty array.

Returns void

Info

Log::Info(string $moduleName, string $message, array $details = []): void

Log an informational message when the log level allows it. Also increments the INFO counter.

Name	Type	Description
`$moduleName`	`string`	The module the message relates to.
`$message`	`string`	The informational message.
`$details`	`array`	Extra detail, encoded into the log entry. Defaults to an empty array.

Returns void

LogConfig

The configuration surface for the Log module: register callbacks that run whenever an alert is logged. The registered callbacks are also used as a last-resort fallback when a log write and the error file both fail.

Properties

Property	Type	Description
`LogConfig::$onAlerts`	`array`	The registered alert callbacks, in registration order.

Functions

OnAlert

LogConfig::OnAlert(callable $callback): void

Name	Type	Description
`$callback`	`callable`	The callback to register.

Returns void

LogCounter

Records named numeric values, aggregated over time. Value and Increment are buffered: increments accumulate in shared memory and are folded into the database once per completed one-minute timeslot. For a counter that must never lose a value, the Exact variants write straight to the database. When APCu is not loaded the buffered calls fall back to the direct path.

Functions

Increment IncrementExact Value ValueExact

Increment

LogCounter::Increment(string $moduleName, string $counterIdentifier, string|null $optionalArgumentString = null): void

Increment a counter by one for the current timeslot, buffered. A failure is logged rather than thrown, so counting never breaks the caller.

Name	Type	Description
`$moduleName`	`string`	The module the counter belongs to.
`$counterIdentifier`	`string`	The counter name; dots are allowed.
`$optionalArgumentString`	`string\|null`	An optional argument that further distinguishes the counter. Defaults to null.

Returns void

IncrementExact

LogCounter::IncrementExact(string $moduleName, string $counterIdentifier, string|null $optionalArgumentString = null): void

Like Increment but exact and durable: never buffered, written straight to the database. A failure is swallowed so the counter never breaks the caller.

Name	Type	Description
`$moduleName`	`string`	The module the counter belongs to.
`$counterIdentifier`	`string`	The counter name; dots are allowed.
`$optionalArgumentString`	`string\|null`	An optional argument that further distinguishes the counter. Defaults to null.

Returns void

Value

LogCounter::Value(string $moduleName, string $counterIdentifier, string|null $optionalArgumentString, float $value): void

Aggregate a value into the current timeslot, buffered. The timeslot accumulates the total, count, minimum and maximum.

Name	Type	Description
`$moduleName`	`string`	The module the counter belongs to.
`$counterIdentifier`	`string`	The counter name; dots are allowed.
`$optionalArgumentString`	`string\|null`	An optional argument that further distinguishes the counter.
`$value`	`float`	The value to aggregate.

Returns void

ValueExact

LogCounter::ValueExact(string $moduleName, string $counterIdentifier, string|null $optionalArgumentString, float $value): void

Like Value but written straight to the database: never buffered, never lost. Slower under high concurrency; use for durable counters.

Name	Type	Description
`$moduleName`	`string`	The module the counter belongs to.
`$counterIdentifier`	`string`	The counter name; dots are allowed.
`$optionalArgumentString`	`string\|null`	An optional argument that further distinguishes the counter.
`$value`	`float`	The value to aggregate.

Returns void

LogCounterBuffer

An APCu-backed write buffer in front of the counter table. Increments accumulate in shared memory bucketed by one-minute timeslot; once a minute completes its slot is frozen and folded into the database in a single batched write. Falls back to a direct write wherever APCu is not loaded.

Functions

Add Available Flush MaybeFlush

Add

LogCounterBuffer::Add(string $moduleName, string $counterIdentifier, string|null $argument, float $value): void

Buffer one value into the current timeslot, then opportunistically flush any completed timeslots. Assumes the caller has already validated the identifiers.

Name	Type	Description
`$moduleName`	`string`	The module the counter belongs to.
`$counterIdentifier`	`string`	The counter name.
`$argument`	`string\|null`	An optional argument that further distinguishes the counter.
`$value`	`float`	The value to buffer.

Returns void

Available

LogCounterBuffer::Available(): bool

Whether the APCu extension is loaded and its cache is enabled, so buffering is used rather than direct writes. The result is cached for the request.

Returns bool True when buffering is available.

Flush

LogCounterBuffer::Flush(): void

Force-flush every completed timeslot to the database. A no-op when buffering is not available. Used from the shutdown handler.

Returns void

MaybeFlush

LogCounterBuffer::MaybeFlush(int $currentSlot): void

If the minute has rolled over since the last seen slot, a single winner takes a short-lived lock and flushes every completed timeslot.

Name	Type	Description
`$currentSlot`	`int`	The current timeslot timestamp.

Returns void

LogCounterCountByDayData

A data object holding a counter total for one calendar day, returned by LogCounterDatabase::GetCountsByDay.

Properties

Property	Type	Description
`$date`	`string`	The day, as YYYY-MM-DD (readonly).
`$count`	`int`	The total count for the day (readonly).

Functions

FromJson ToJson

FromJson

LogCounterCountByDayData::FromJson(string $json): LogCounterCountByDayData

Build a LogCounterCountByDayData from its JSON representation.

Name	Type	Description
`$json`	`string`	The JSON string.

Returns LogCounterCountByDayData The decoded data object.

ToJson

LogCounterCountByDayData::ToJson(): string

Serialise the day total to JSON.

Returns string The JSON representation.

LogCounterCountByHourData

A data object holding a counter total for one hour of the day, returned by LogCounterDatabase::GetCountsByHour.

Properties

Property	Type	Description
`$hour`	`int`	The hour of the day, 0 to 23 (readonly).
`$count`	`int`	The total count for the hour (readonly).

Functions

FromJson ToJson

FromJson

LogCounterCountByHourData::FromJson(string $json): LogCounterCountByHourData

Build a LogCounterCountByHourData from its JSON representation.

Name	Type	Description
`$json`	`string`	The JSON string.

Returns LogCounterCountByHourData The decoded data object.

ToJson

LogCounterCountByHourData::ToJson(): string

Serialise the hour total to JSON.

Returns string The JSON representation.

LogCounterCountByMonthData

A data object holding a counter total for one calendar month, returned by LogCounterDatabase::GetCountsByMonth.

Properties

Property	Type	Description
`$year`	`int`	The year (readonly).
`$month`	`int`	The month, 1 to 12 (readonly).
`$count`	`int`	The total count for the month (readonly).

Functions

FromJson ToJson

FromJson

LogCounterCountByMonthData::FromJson(string $json): LogCounterCountByMonthData

Build a LogCounterCountByMonthData from its JSON representation.

Name	Type	Description
`$json`	`string`	The JSON string.

Returns LogCounterCountByMonthData The decoded data object.

ToJson

LogCounterCountByMonthData::ToJson(): string

Serialise the month total to JSON.

Returns string The JSON representation.

LogCounterData

A data object for one aggregated counter row: the module, identifier and optional argument, its hash and timeslot, and the accumulated total, minimum, maximum and count.

Properties

Property	Type	Description
`$id`	`int`	The row id (readonly).
`$moduleName`	`string`	The module the counter belongs to (readonly).
`$counterIdentifier`	`string`	The counter name (readonly).
`$hash`	`string`	The unique hash key for the counter and timeslot (readonly).
`$argument`	`?string`	The optional distinguishing argument, or null (readonly).
`$timeslotTimestamp`	`int`	The start timestamp of the timeslot (readonly).
`$total`	`float`	The sum of values in the timeslot (readonly).
`$minimum`	`float`	The smallest value in the timeslot (readonly).
`$maximum`	`float`	The largest value in the timeslot (readonly).
`$count`	`int`	The number of values aggregated (readonly).

Functions

FromJson ToJson

FromJson

LogCounterData::FromJson(string $json): LogCounterData

Build a LogCounterData from its JSON representation.

Name	Type	Description
`$json`	`string`	The JSON string.

Returns LogCounterData The decoded data object.

ToJson

LogCounterData::ToJson(): string

Serialise the counter row to JSON.

Returns string The JSON representation.

LogCounterDatabase

The database layer for counters: upserting values into the current timeslot, time-bucketing and hashing, and aggregate reads grouped by hour, day, month or timeslot. Counters are bucketed into fixed-length timeslots.

Constants

Constant	Value	Description
`LogCounterDatabase::TIMESLOT_LENGTH_SECONDS`	`60`	The length in seconds of each counter timeslot.

Functions

BulkFetchCounters FetchTimeSeriesForCounter fromRow GetCountsByDay GetCountsByHour GetCountsByMonth getCurrentTimeslot GetIdentifiersByModuleName Hash Value ValueBatch

BulkFetchCounters

LogCounterDatabase::BulkFetchCounters(int $startTimestamp, ?string $optionalModuleName = null, ?string $optionalCounterIdentifier = null, ?string $optionalArgument = null): array

Fetch counter rows from a start time, optionally filtered by module, identifier and argument.

Name	Type	Description
`$startTimestamp`	`int`	The earliest timeslot timestamp to include.
`$optionalModuleName`	`?string`	A module to filter by, or null for all. Defaults to null.
`$optionalCounterIdentifier`	`?string`	A counter identifier to filter by, or null for all. Defaults to null.
`$optionalArgument`	`?string`	An argument to filter by, or null for all. Defaults to null.

Returns array A list of LogCounterData rows.

FetchTimeSeriesForCounter

LogCounterDatabase::FetchTimeSeriesForCounter(int $startTimestamp, string $moduleName, string $counterIdentifier): array

Sum a counter total per timeslot from a start time, ready for charting. The result holds a totals map keyed by timeslot timestamp and the summed totalCount.

Name	Type	Description
`$startTimestamp`	`int`	The earliest timeslot timestamp to include.
`$moduleName`	`string`	The module the counter belongs to.
`$counterIdentifier`	`string`	The counter name.

Returns array A map with a totals array and a totalCount.

fromRow

LogCounterDatabase::fromRow(object $row): LogCounterData

Build a LogCounterData from a database row.

Name	Type	Description
`$row`	`object`	The database row.

Returns LogCounterData The mapped data object.

GetCountsByDay

LogCounterDatabase::GetCountsByDay(int $startTimestamp, ?string $optionalModuleName = null, ?string $optionalCounterIdentifier = null, ?string $optionalArgument = null): array

Counter counts grouped by calendar day from a start time, sorted by date.

Name	Type	Description
`$startTimestamp`	`int`	The earliest timeslot timestamp to include.
`$optionalModuleName`	`?string`	A module to filter by, or null for all. Defaults to null.
`$optionalCounterIdentifier`	`?string`	A counter identifier to filter by, or null for all. Defaults to null.
`$optionalArgument`	`?string`	An argument to filter by, or null for all. Defaults to null.

Returns array A list of LogCounterCountByDayData.

GetCountsByHour

LogCounterDatabase::GetCountsByHour(int $startTimestamp, ?string $optionalModuleName = null, ?string $optionalCounterIdentifier = null, ?string $optionalArgument = null): array

Counter counts grouped by hour of the day from a start time, one entry for each of the 24 hours.

Name	Type	Description
`$startTimestamp`	`int`	The earliest timeslot timestamp to include.
`$optionalModuleName`	`?string`	A module to filter by, or null for all. Defaults to null.
`$optionalCounterIdentifier`	`?string`	A counter identifier to filter by, or null for all. Defaults to null.
`$optionalArgument`	`?string`	An argument to filter by, or null for all. Defaults to null.

Returns array A list of LogCounterCountByHourData.

GetCountsByMonth

LogCounterDatabase::GetCountsByMonth(int $startTimestamp, ?string $optionalModuleName = null, ?string $optionalCounterIdentifier = null, ?string $optionalArgument = null): array

Counter counts grouped by calendar month from a start time, sorted by year then month.

Name	Type	Description
`$startTimestamp`	`int`	The earliest timeslot timestamp to include.
`$optionalModuleName`	`?string`	A module to filter by, or null for all. Defaults to null.
`$optionalCounterIdentifier`	`?string`	A counter identifier to filter by, or null for all. Defaults to null.
`$optionalArgument`	`?string`	An argument to filter by, or null for all. Defaults to null.

Returns array A list of LogCounterCountByMonthData.

getCurrentTimeslot

LogCounterDatabase::getCurrentTimeslot(): int

The current time rounded down to the start of its timeslot, as a Unix timestamp.

Returns int The current timeslot timestamp.

GetIdentifiersByModuleName

LogCounterDatabase::GetIdentifiersByModuleName(string $moduleName): array

The distinct counter identifiers recorded for a module, sorted.

Name	Type	Description
`$moduleName`	`string`	The module to read identifiers for.

Returns array A list of counter identifier strings.

Hash

LogCounterDatabase::Hash(string $moduleName, string $counterIdentifier, string|null $optionalArgumentString, int $timeslotTimestamp): string

The unique hash key for a counter, derived from its module, identifier, optional argument and timeslot.

Name	Type	Description
`$moduleName`	`string`	The module the counter belongs to.
`$counterIdentifier`	`string`	The counter name.
`$optionalArgumentString`	`string\|null`	An optional argument that further distinguishes the counter.
`$timeslotTimestamp`	`int`	The timeslot timestamp.

Returns string The counter hash.

Value

LogCounterDatabase::Value(string $moduleName, string $counterIdentifier, string|null $optionalArgumentString, float $value): void

Upsert a value into the current timeslot row for a counter, adding to the total and count and updating the minimum and maximum.

Name	Type	Description
`$moduleName`	`string`	The module the counter belongs to.
`$counterIdentifier`	`string`	The counter name.
`$optionalArgumentString`	`string\|null`	An optional argument that further distinguishes the counter.
`$value`	`float`	The value to aggregate.

Returns void

ValueBatch

LogCounterDatabase::ValueBatch(array $rows): void

Upsert many pre-aggregated counter deltas in one statement, each folded additively into its existing row. Used when the buffer flushes a completed timeslot.

Name	Type	Description
`$rows`	`array`	A list of rows, each with module, identifier, argument, slot, total, count, min and max.

Returns void

LogDatabase

The database layer for log messages: inserting a message row for the Log functions, and a per-minute named counter.

Functions

Add Count

Add

LogDatabase::Add(int $type, string $moduleName, string $message, string $details): int

Insert a log message row, recording its type, module, message, details and the current timestamp, and return its new id.

Name	Type	Description
`$type`	`int`	The message type, one of the LogTypeEnum constants.
`$moduleName`	`string`	The module the message relates to.
`$message`	`string`	The message text.
`$details`	`string`	The encoded details.

Returns int The new row id.

Count

LogDatabase::Count(string $moduleName, string $counterName): void

Increment a named per-minute counter row for a module, ensuring the row exists first.

Name	Type	Description
`$moduleName`	`string`	The module the counter belongs to.
`$counterName`	`string`	The counter name.

Returns void

LogTimer

Times a callback and records the elapsed seconds as a counter value.

Functions

Time

LogTimer::Time(string $moduleName, string $timerName, string|null $optionalArgumentString, callable $code, array ...$argutments): mixed

Run the callback, then record its elapsed run time in seconds as a counter value, even if the callback throws. Returns whatever the callback returns.

Name	Type	Description
`$moduleName`	`string`	The module the timer belongs to.
`$timerName`	`string`	The timer name, used as the counter identifier.
`$optionalArgumentString`	`string\|null`	An optional argument that further distinguishes the counter.
`$code`	`callable`	The callback to run and time.
`...$argutments`	`array`	Arguments passed through to the callback.

Returns mixed The value returned by the callback.

LogTypeEnum

The numeric log level constants. A lower number is a higher severity; the configured LOG_LEVEL is the highest number that is written. This class has no functions.

Constants

Constant	Value	Description
`LogTypeEnum::TYPE_ALERT`	`1`	An alert, the highest severity.
`LogTypeEnum::TYPE_EXCEPTION`	`2`	A caught exception.
`LogTypeEnum::TYPE_ERROR`	`3`	An error.
`LogTypeEnum::TYPE_INFO`	`4`	An informational message.
`LogTypeEnum::TYPE_DEBUG`	`5`	A debug message, the lowest severity.