Skip to content

armgit / Vvveb

Public Imported from GitHub
0

Powerful and easy to use cms to build websites, blogs or ecommerce stores.

Set table prefix on sqlite and pgsql connect, use DB_PREFIX for queue tables

Givanb3ade22499bf
diff --git a/system/db/mysqli.php b/system/db/mysqli.php
index edd1b0d..67523ff 100755
--- a/system/db/mysqli.php
+++ b/system/db/mysqli.php
@@ -24,114 +24,94 @@ namespace Vvveb\System\Db;
use Vvveb\System\Event;
-/*
- Define and use mysqli_result if native is missing
- */
-class mysqli_result {
- private $stmt;
-
- private $meta;
-
- public function __construct($stmt) {
- $this->stmt = $stmt;
- }
-
- public function fetch_all() {
- return $this->fetch_assoc();
- }
-
- public function fetch_array($resulttype) {
- return $this->fetch_assoc();
- }
-
- public function fetch_assoc() {
- //$meta = $this->stmt->store_result();
- $meta = $this->stmt->result_metadata();
- $row = [];
-
- while ($field = $meta->fetch_field()) {
- $params[] = &$row[$field->name];
- }
-
- call_user_func_array([$this->stmt, 'bind_result'], $params);
-
- while ($this->stmt->fetch()) {
- $c = [];
-
- foreach ($row as $key => $val) {
- $c[$key] = $val;
- }
- $result[] = $c;
- }
-
- //$this->stmt->free_result();
- //$this->stmt->close();
-
- return $result;
- }
-
- public function fetch_field() {
- }
-
- public function fetch_fields() {
- }
-
- public function fetchRow() {
- return $this->fetch_assoc();
- }
-}
-
class Mysqli extends DBDriver {
- private static $link = null;
-
- //public $error;
+ /** @var ?\MySQLi The shared database connection (singleton per process). */
+ private static ?\mysqli $link = null;
- private $stmt;
+ /** @var int Number of rows affected by the last query. */
+ public int $affected_rows = 0;
- public $affected_rows = 0;
+ /** @var ?int The auto-increment ID generated by the last INSERT. */
+ public ?int $insert_id = null;
- public $insert_id = null;
+ /** @var string Identifier quote character for MySQL. */
+ public string $quote = '`';
- public $quote = '`';
+ /** @var string Table name prefix. */
+ public string $prefix = ''; //'vv_';
- public $prefix = ''; //'vv_';
-
- public static function version() {
+ /**
+ * Get the MySQL server version as an integer.
+ *
+ * @return int|null The server version (e.g. 80031) or null if not connected.
+ */
+ public static function version(): ?int {
if (self :: $link) {
return mysqli_get_server_version(self :: $link);
}
+
+ return null;
}
- public static function info() {
+ /**
+ * Get the MySQL server version string.
+ *
+ * @return string|null The version string (e.g. '8.0.31') or null if not connected.
+ */
+ public static function info(): ?string {
if (self :: $link) {
return mysqli_get_server_info(self :: $link);
}
+
+ return null;
}
- public function error() {
+ /**
+ * Get the error message from the last MySQL operation.
+ *
+ * @return string|null The error message, or null if not connected.
+ */
+ public function error(): ?string {
if (self :: $link) {
return self :: $link->error;
}
+
+ return null;
}
- public function errorCode() {
+ /**
+ * Get the error code from the last MySQL operation.
+ *
+ * @return int|null The error code, or null if not connected.
+ */
+ public function errorCode(): ?int {
if (self :: $link) {
return self :: $link->errno;
}
- }
-
- public function get_result($stmt) {
- $result = new mysqli_result($stmt);
-
- return $result;
- }
- public function __construct($host = DB_HOST, $dbname = DB_NAME, $user = DB_USER, $pass = DB_PASS, $port = DB_PORT, $prefix = DB_PREFIX) {
- //return $this->connect($host, $dbname, $user, $pass, $port, $prefix);
+ return null;
}
- public function connect($host = DB_HOST, $dbname = DB_NAME, $user = DB_USER, $pass = DB_PASS, $port = DB_PORT, $prefix = DB_PREFIX) {
- //mysqli_report(MYSQLI_REPORT_OFF);
+ public function __construct() {}
+
+ /**
+ * Connect to the MySQL database.
+ *
+ * Uses a singleton pattern — returns the existing connection if already open.
+ * Throws an exception with a sanitised error message on failure.
+ *
+ * @param string $host Database host.
+ * @param string $dbname Database name.
+ * @param string $user Database user.
+ * @param string $pass Database password.
+ * @param int|null $port Database port.
+ * @param string $prefix Table name prefix.
+ *
+ * @throws \Exception On connection failure.
+ *
+ * @return ?\MySQLi The database connection, or null on failure.
+ */
+ public function connect(string $host = DB_HOST, string $dbname = DB_NAME, string $user = DB_USER, string $pass = DB_PASS, ?int $port = DB_PORT, string $prefix = DB_PREFIX): ?\mysqli {
//connect to database
if (self :: $link) {
return self :: $link;
@@ -141,10 +121,9 @@ class Mysqli extends DBDriver {
\mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
try {
- self :: $link = new \Mysqli(/*'p:' . */$host, $user, $pass, $dbname, $port);
- //self :: $link = $this;
+ self :: $link = new \mysqli($host, $user, $pass, $dbname, $port);
} catch (\mysqli_sql_exception $e) {
- $errorMessage = str_replace($pass,'*****', $e->getMessage());
+ $errorMessage = str_replace($pass, '*****', $e->getMessage());
throw new \Exception($errorMessage, $e->getCode());
}
@@ -152,27 +131,32 @@ class Mysqli extends DBDriver {
// check if a connection established
if (\mysqli_connect_errno()) {
$error = mysqli_connect_error();
- $errorMessage = str_replace($pass,'*****', $error);
+ $errorMessage = str_replace($pass, '*****', $error);
throw new \Exception($errorMessage, mysqli_connect_errno());
}
- if ((! self :: $link instanceof \MySQLi)) {
- throw new \Exception('Mysqli not an object', mysqli_connect_errno());
- }
+ //sync database time
+ //$this->execute('SET `time_zone` = :zone', ['zone' => $this->escape(date('P'))]);
return self :: $link;
}
- /*
- * Get all columns for a table used for sanitizing input
+ /**
+ * Get all columns for a table used for sanitizing input.
+ *
+ * @param string $tableName The table name to introspect.
+ * @param bool $comment Whether to include the column comment field.
+ *
+ * @return array<string, array{name: string, d: mixed, n: string, t: string, e: string, l: int|null, c?: string}>|false
+ * Associative array keyed by column name, or false on failure.
*/
- function getColumnsMeta($tableName, $comment = false) {
+ public function getColumnsMeta(string $tableName, bool $comment = false): array|false {
$sql =
'SELECT COLUMN_NAME as name, COLUMN_DEFAULT as d, IS_NULLABLE as n, DATA_TYPE as t, EXTRA as e, CHARACTER_MAXIMUM_LENGTH as l'
. ($comment ? ', COLUMN_COMMENT as c' : '') .
- ' FROM `INFORMATION_SCHEMA`.`COLUMNS`
- WHERE `TABLE_SCHEMA`= "' . DB_NAME . '"
+ ' FROM `INFORMATION_SCHEMA`.`COLUMNS`
+ WHERE `TABLE_SCHEMA`= "' . DB_NAME . '"
AND `TABLE_NAME`="' . $tableName . '"';
if ($result = $this->query($sql)) {
@@ -183,19 +167,25 @@ class Mysqli extends DBDriver {
$columns[$row['name']] = $row;
}
- /* free result set */
+ // free result set
$result->close();
return $columns;
- } else {
}
return false;
}
- function getTableNames($db = DB_NAME) {
- $sql ="SELECT table_name as name
- FROM information_schema.tables
+ /**
+ * Get all table names in the database.
+ *
+ * @param string $db The database name.
+ *
+ * @return array<int, string>|false List of table names, or false on failure.
+ */
+ public function getTableNames(string $db = DB_NAME): array|false {
+ $sql = "SELECT table_name as name
+ FROM information_schema.tables
WHERE table_schema = '$db' ORDER BY table_name";
if ($result = $this->query($sql)) {
@@ -206,22 +196,39 @@ class Mysqli extends DBDriver {
$names[] = $row['name'];
}
- /* free result set */
+ // free result set
$result->close();
return $names;
- } else {
}
return false;
}
- public function select_db($db) {
+ /**
+ * Select a different database on the current connection.
+ *
+ * @param string $db The database name.
+ *
+ * @return bool True on success, false on failure.
+ */
+ public function select_db(string $db): bool {
return self :: $link->select_db($db);
}
- public function query($sql) {
- if (! self :: $link) {
+ /**
+ * Execute a raw SQL query.
+ *
+ * Automatically connects if not connected. Updates affected_rows and insert_id.
+ *
+ * @param string $sql The SQL query to execute.
+ *
+ * @throws \Exception On query failure.
+ *
+ * @return bool|\mysqli_result Query result or true for success, false on failure.
+ */
+ public function query(string $sql): bool|\mysqli_result {
+ if (!self :: $link) {
$this->connect();
}
@@ -245,11 +252,18 @@ class Mysqli extends DBDriver {
return $result;
}
- public function multi_query($sql) {
- if (! self :: $link) {
+ /**
+ * Execute multiple SQL statements in a single call.
+ *
+ * @param string $sql The SQL statements to execute (semicolon-separated).
+ *
+ * @return bool True on success, false on failure.
+ */
+ public function multi_query(string $sql): bool {
+ if (!self :: $link) {
$this->connect();
}
-
+
$result = self :: $link->multi_query($sql);
if ($result) {
@@ -260,7 +274,17 @@ class Mysqli extends DBDriver {
return $result;
}
- public function escape($string) {
+ /**
+ * Escape a value for safe inclusion in a SQL query.
+ *
+ * Strings are escaped with real_escape_string. Null values become 'null'.
+ * All other types are returned as-is.
+ *
+ * @param mixed $string The value to escape.
+ *
+ * @return mixed The escaped value.
+ */
+ public function escape(mixed $string): mixed {
if (is_string($string)) {
return self :: $link->real_escape_string($string);
}
@@ -272,17 +296,39 @@ class Mysqli extends DBDriver {
return $string;
}
- public function escapeLiteral($string) {
+ /**
+ * Escape a string value for use in a SQL literal.
+ *
+ * @param string $string The string to escape.
+ *
+ * @return string The escaped string.
+ */
+ public function escapeLiteral(string $string): string {
return $this->escape($string);
}
- public function sqlLimit($start, $limit) {
+ /**
+ * Generate a MySQL-compatible LIMIT clause.
+ *
+ * @param int|string $start Offset (0-based).
+ * @param int|string $limit Maximum number of rows.
+ *
+ * @return string The LIMIT clause (e.g. 'LIMIT 0, 10').
+ */
+ public function sqlLimit(int|string $start, int|string $limit): string {
return "LIMIT $start, $limit";
}
- public function fetchArray($stmt) {
+ /**
+ * Fetch a single row from a statement or result set.
+ *
+ * @param \mysqli_stmt|\mysqli_result $stmt The statement or result to fetch from.
+ *
+ * @return array<string, mixed> The fetched row, or empty array if no rows.
+ */
+ public function fetchArray(\mysqli_stmt|\mysqli_result $stmt): array {
$data = [];
- $statement = (get_class($stmt) === 'mysqli_stmt');
+ $statement = ($stmt instanceof \mysqli_stmt);
if ($statement) {
$this->store_result();
@@ -292,19 +338,30 @@ class Mysqli extends DBDriver {
}
if ($result) {
- $data = $result->fetch_array(MYSQLI_ASSOC);
+ $result = $result->fetch_array(MYSQLI_ASSOC);
+
+ if ($result) {
+ $data = $result;
- if ($statement && $stmt->more_results()) {
- $stmt->next_result();
+ if ($statement && $stmt->more_results()) {
+ $stmt->next_result();
+ }
}
}
return $data;
}
- public function fetchAll($stmt) {
+ /**
+ * Fetch all rows from a statement or result set.
+ *
+ * @param \mysqli_stmt|\mysqli_result $stmt The statement or result to fetch from.
+ *
+ * @return array<int, array<string, mixed>> All result rows.
+ */
+ public function fetchAll(\mysqli_stmt|\mysqli_result $stmt): array {
$data = [];
- $statement = (get_class($stmt) === 'mysqli_stmt');
+ $statement = ($stmt instanceof \mysqli_stmt);
if ($statement) {
$this->store_result();
@@ -320,35 +377,71 @@ class Mysqli extends DBDriver {
return $data;
}
- public function store_result() {
+ /**
+ * Store the result of the last query in the client-side buffer.
+ *
+ * @return \mysqli_result|false The stored result, or false on failure.
+ */
+ public function store_result(): \mysqli_result|false {
return self :: $link->store_result();
}
- public function more_results() {
+ /**
+ * Check if the current statement has more result sets.
+ *
+ * @return bool True if more results are available.
+ */
+ public function more_results(): bool {
return self :: $link->more_results();
}
- public function next_result() {
+ /**
+ * Move to the next result set in a multi-query.
+ *
+ * @return bool True on success, false on failure.
+ */
+ public function next_result(): bool {
return self :: $link->next_result();
}
- public function close() {
- if ((self :: $link instanceof \MySQLi)/* && self :: $link->ping()*/) {
+ /**
+ * Close the database connection.
+ *
+ * @return ?bool True on success, null if not connected.
+ */
+ public function close(): ?bool {
+ if ((self :: $link instanceof \mysqli)/* && self :: $link->ping()*/) {
return self :: $link->close();
}
+
+ return null;
}
- // Prepare
- public function execute($sql, $params = [], $paramTypes = []) {
- list($sql, $params) = Event::trigger(__CLASS__,__FUNCTION__, $sql, $params);
+ /**
+ * Prepare and execute a parameterized query.
+ *
+ * Fires an Event::trigger hook before execution. Converts named parameters
+ * to positional placeholders, binds parameters, and executes the statement.
+ * Updates affected_rows and insert_id on success.
+ *
+ * @param string $sql The SQL query with :named parameters.
+ * @param array<string, mixed> $params Named parameter values.
+ * @param array<string, string> $paramTypes Optional explicit type overrides.
+ *
+ * @throws \Exception On prepare or execute failure.
+ *
+ * @return ?\mysqli_stmt The executed statement, or null on failure.
+ */
+ public function execute(string $sql, array $params = [], array $paramTypes = []): ?\mysqli_stmt {
+ [$sql, $params] = Event::trigger(__CLASS__, __FUNCTION__, $sql, $params);
//save orig sql for debugging info
$origSql = $sql;
- if (! self :: $link) {
+ if (!self :: $link) {
$this->connect();
}
- list($parameters, $types) = $this->paramsToQmark($sql, $params, $paramTypes);
+ [$parameters, $types] = $this->paramsToQmark($sql, $params, $paramTypes);
try {
$stmt = self::$link->prepare($sql);
@@ -358,7 +451,7 @@ class Mysqli extends DBDriver {
throw new \Exception($message, $e->getCode());
}
- if ($stmt && ! empty($types)) {
+ if ($stmt && !empty($types)) {
array_unshift($parameters, $types);
//hack for php 7.x bind_param "expected to be a reference, value given" stupid warning
@@ -383,24 +476,19 @@ class Mysqli extends DBDriver {
return $stmt;
} else {
- error_log(print_r($stmt, 1));
+ error_log(print_r($stmt, true));
error_log($this->debugSql($sql, $params, $paramTypes));
}
} catch (\mysqli_sql_exception $e) {
- $message = $e->getMessage() . "\n" . $origSql . "\n" . $this->debugSql($origSql, $params, $paramTypes) . "\n" . print_r($parameters, 1) . $types . "\n" . print_r(debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 1), true);
+ $message = $e->getMessage() . "\n" . $origSql . "\n" . $this->debugSql($origSql, $params, $paramTypes) . "\n" . print_r($parameters, true) . $types . "\n" . print_r(debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 1), true);
throw new \Exception($message, $e->getCode());
}
} else {
- error_log(print_r($stmt, 1));
+ error_log(print_r($stmt, true));
error_log($this->debugSql($origSql, $params, $paramTypes));
}
return $stmt;
}
-
- // Bind
- public function bind($param, $value, $type = null) {
- $this->stmt->bindValue($param, $value, $type);
- }
}
diff --git a/system/db/pgsql.php b/system/db/pgsql.php
old mode 100755
new mode 100644
index 10a3e17..87e5c0d
--- a/system/db/pgsql.php
+++ b/system/db/pgsql.php
@@ -24,75 +24,137 @@ namespace Vvveb\System\Db;
use Vvveb\System\Event;
+/**
+ * PostgreSQL database driver using the pgsql extension.
+ *
+ * Provides connection management, query execution with parameterised queries,
+ * result fetching, escaping, and schema introspection for PostgreSQL.
+ */
class Pgsql extends DBDriver {
- private static $link = null;
-
- //public $error;
+ /** @var ?\PgSql\Connection The shared database connection (singleton per process). */
+ private static ?\PgSql\Connection $link = null;
- private $stmt;
+ /** @var mixed The last query result resource. */
+ private mixed $last_res;
- private $last_res;
+ /** @var int Number of rows affected by the last query. */
+ public int $affected_rows = 0;
- public $affected_rows = 0;
+ /** @var int Number of rows returned by the last query. */
+ public int $num_rows = 0;
- public $num_rows = 0;
+ /** @var ?int The OID of the last inserted row, or null if none. */
+ public ?int $insert_id = null;
- public $insert_id = null;
+ /** @var bool Whether to use persistent connections. */
+ private static bool $persistent = false;
- private static $persistent = false;
+ /** @var string Table name prefix. */
+ public string $prefix = ''; //'vv_';
- public $prefix = ''; //'vv_';
+ /** @var string Identifier quote character for PostgreSQL. */
+ public string $quote = '"';
- public $quote = '"';
-
- public static function version() {
+ /**
+ * Get the PostgreSQL client and server version information.
+ *
+ * @return array{client: string, server: string}|null Version info, or null if not connected.
+ */
+ public static function version(): ?array {
if (self :: $link) {
return pg_version(self :: $link);
}
+
+ return null;
}
- public static function info() {
+ /**
+ * Get the PostgreSQL client and server version information.
+ *
+ * @return array{client: string, server: string}|null Version info, or null if not connected.
+ */
+ public static function info(): ?array {
if (self :: $link) {
return pg_version(self :: $link);
}
+
+ return null;
}
- public function error() {
+ /**
+ * Get the error message from the last PostgreSQL operation.
+ *
+ * @return string The error message, or empty string if not connected.
+ */
+ public function error(): string {
if (self :: $link) {
- return pg_last_error(self :: $link) ?? '';
+ return pg_last_error(self :: $link);
}
+
+ return '';
}
- public function errorCode() {
+ /**
+ * Get the error code from the last PostgreSQL operation.
+ *
+ * @return int|string The error code, or 0 if not connected.
+ */
+ public function errorCode(): int|string {
if (self :: $link) {
- return pg_last_error(self :: $link) ?? 0;
+ return pg_last_error(self :: $link);
}
+
+ return 0;
}
- public function get_result($stmt) {
+ /**
+ * Pass through the statement result unchanged (no transformation needed for pgsql).
+ *
+ * @param mixed $stmt The statement result.
+ *
+ * @return mixed The same statement result.
+ */
+ public function get_result(mixed $stmt): mixed {
return $stmt;
}
- public function __construct($host = DB_HOST, $dbname = DB_NAME, $user = DB_USER, $pass = DB_PASS, $port = DB_PORT, $prefix = DB_PREFIX) {
+ public function __construct() {
//return $this->connect($host, $dbname, $user, $pass, $port, $prefix);
}
- public function connect($host = DB_HOST, $dbname = DB_NAME, $user = DB_USER, $pass = DB_PASS, $port = DB_PORT, $prefix = DB_PREFIX) {
- if (! self :: $link) {
+ /**
+ * Connect to the PostgreSQL database.
+ *
+ * Uses a singleton pattern — returns the existing connection if already open.
+ * Supports both regular and persistent connections.
+ *
+ * @param string $host Database host.
+ * @param string $dbname Database name.
+ * @param string $user Database user.
+ * @param string $pass Database password.
+ * @param string $port Database port (5432 direct, 6432 for pgbouncer).
+ * @param string $prefix Table name prefix.
+ *
+ * @return ?\PgSql\Connection The database connection, or null on failure.
+ */
+ public function connect(string $host = DB_HOST, string $dbname = DB_NAME, string $user = DB_USER, string $pass = DB_PASS, string $port = DB_PORT, string $prefix = DB_PREFIX): ?\PgSql\Connection {
+ if (!self :: $link) {
+ $this->prefix = $prefix;
//port 5432 for direct pgsql connection 6432 for pgbouncer
$port = $port ?: 5432;
$connect_string = "host=$host port=$port dbname=$dbname user=$user password=$pass";
if (self :: $persistent) {
- self :: $link = pg_pconnect($connect_string);
+ $link = pg_pconnect($connect_string);
} else {
- self :: $link = pg_connect($connect_string);
+ $link = pg_connect($connect_string);
}
- if (self :: $link) {
- // pg_set_error_verbosity(self :: $link, PGSQL_ERRORS_VERBOSE);
- } else {
+ if (!$link) {
+ throw new \Exception('PostgreSQL connection failed');
}
+
+ self :: $link = $link;
}
//sync database time
@@ -101,10 +163,16 @@ class Pgsql extends DBDriver {
return self :: $link;
}
- /*
- * Get all columns for a table used for sanitizing input
+ /**
+ * Get all columns for a table used for sanitizing input.
+ *
+ * @param string $tableName The table name to introspect.
+ * @param bool $comment Whether to include column comments (unused for pgsql).
+ *
+ * @return array<string, array<string, string|null>>|false
+ * Associative array keyed by column name, or false on failure.
*/
- function getColumnsMeta($tableName, $comment = false) {
+ public function getColumnsMeta(string $tableName, bool $comment = false): array|false {
$sql =
"SELECT data_type as t, column_name as name, column_default as d, is_nullable as n, character_maximum_length as l FROM information_schema.columns WHERE table_name ='$tableName'";
@@ -116,15 +184,21 @@ class Pgsql extends DBDriver {
$columns[$row['name']] = $row;
}
- /* free result set */
+ // free result set
return $columns;
- } else {
}
return false;
}
- function getTableNames($db = DB_NAME) {
+ /**
+ * Get all table names in the database.
+ *
+ * @param string $db The database name (unused — queries pg_catalog instead).
+ *
+ * @return array<int, string>|false List of table names, or false on failure.
+ */
+ public function getTableNames(string $db = DB_NAME): array|false {
$sql =
"SELECT tablename as name FROM pg_catalog.pg_tables WHERE schemaname != 'pg_catalog' AND schemaname != 'information_schema' ORDER BY name";
@@ -137,15 +211,24 @@ class Pgsql extends DBDriver {
$names[] = $row['name'];
}
- /* free result set */
+ // free result set
return $names;
- } else {
}
return false;
}
- public function escape($string) {
+ /**
+ * Escape a value for safe inclusion in a SQL query.
+ *
+ * Strings are escaped with pg_escape_string. Null values become 'null'.
+ * All other types are returned as-is.
+ *
+ * @param mixed $string The value to escape.
+ *
+ * @return mixed The escaped value.
+ */
+ public function escape(mixed $string): mixed {
if (is_string($string)) {
return pg_escape_string(self :: $link, $string);
}
@@ -157,24 +240,29 @@ class Pgsql extends DBDriver {
return $string;
}
- public function escapeLiteral($string) {
- if (is_string($string)) {
- return pg_escape_literal(self :: $link, $string);
- }
-
- if (is_null($string)) {
- return 'null';
- }
-
- return $string;
- }
-
- public function sqlLimit($start, $limit) {
- return "LIMIT $limit OFFSET $start";
+ /**
+ * Escape a string value for use in a SQL literal.
+ *
+ * Returns the escaped value without surrounding quotes, matching the
+ * mysqli/sqlite drivers (callers add their own quotes).
+ *
+ * @param string $string The string to escape.
+ *
+ * @return string The escaped string.
+ */
+ public function escapeLiteral(string $string): string {
+ return pg_escape_string(self :: $link, $string);
}
- public function fetchArray(&$result) {
- if (pg_num_rows($result)) {
+ /**
+ * Fetch a single row from a result resource.
+ *
+ * @param \PgSql\Result|false $result The pgsql result resource.
+ *
+ * @return array<string, mixed> The fetched row, or empty array if no rows.
+ */
+ public function fetchArray(&$result): array {
+ if ($result && pg_num_rows($result)) {
$values = pg_fetch_assoc($result);
return $values;
@@ -183,14 +271,19 @@ class Pgsql extends DBDriver {
return [];
}
- public function fetchAll(&$result) {
- if (pg_num_rows($result)) {
+ /**
+ * Fetch all rows from a result resource and free it.
+ *
+ * @param \PgSql\Result|false $result The pgsql result resource (set to false after freeing).
+ *
+ * @return array<int, array<string, mixed>> All result rows.
+ */
+ public function fetchAll(&$result): array {
+ if ($result && pg_num_rows($result)) {
$values = pg_fetch_all($result);
- if ($result) {
- pg_free_result($result);
- $result = false;
- }
+ pg_free_result($result);
+ $result = false;
return $values;
}
@@ -198,8 +291,21 @@ class Pgsql extends DBDriver {
return [];
}
- public function query($sql, $parameters = []) {
- if (! self :: $link) {
+ /**
+ * Execute a raw SQL query with optional positional parameters.
+ *
+ * Automatically connects if not connected. Uses pg_query_params when
+ * parameters are provided, pg_query otherwise.
+ *
+ * @param string $sql The SQL query with $1, $2... placeholders.
+ * @param array<int, mixed> $parameters Positional parameter values.
+ *
+ * @throws \Exception On query failure.
+ *
+ * @return \PgSql\Result|false The query result, or false on failure.
+ */
+ public function query(string $sql, array $parameters = []): \PgSql\Result|false {
+ if (!self :: $link) {
$this->connect();
}
@@ -208,7 +314,7 @@ class Pgsql extends DBDriver {
try {
if ($parameters) {
if (LOG_SQL_QUERIES) {
- error_log($this->debugSql($sql, $parameters));
+ error_log($this->debugSql($sql, $parameters, [], '$'));
}
$this->last_res = $result = @pg_query_params(self :: $link, $sql, $parameters);
@@ -222,7 +328,7 @@ class Pgsql extends DBDriver {
if ($this->last_res == false) {
$errorMessage = pg_last_error(self :: $link);
- $message = $errorMessage . "\n" . $this->debugSql($sql, $parameters) . "\n - " . $sql . "\n - " . print_r(debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 1), true);
+ $message = $errorMessage . "\n" . $this->debugSql($sql, $parameters, [], '$') . "\n - " . $sql . "\n - " . print_r(debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 1), true);
throw new \Exception($message);
}
@@ -233,25 +339,45 @@ class Pgsql extends DBDriver {
return $this->last_res;
} catch (\Exception $e) {
- $message = $e->getMessage() . "\n" . $this->debugSql($sql, $parameters) . "\n - " . $sql . "\n - " . print_r(debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 1), true);
+ $message = $e->getMessage() . "\n" . $this->debugSql($sql, $parameters, [], '$') . "\n - " . $sql . "\n - " . print_r(debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 1), true);
throw new \Exception($message, $e->getCode());
}
-
- return $result;
}
- public function multi_query($sql) {
+ /**
+ * Execute multiple SQL statements (delegates to query for PostgreSQL).
+ *
+ * @param string $sql The SQL statements to execute.
+ *
+ * @return \PgSql\Result|false The query result, or false on failure.
+ */
+ public function multi_query(string $sql): \PgSql\Result|false {
return $this->query($sql);
}
- public function close() {
+ /**
+ * Close the database connection.
+ *
+ * @return bool|null True on success, null if not connected.
+ */
+ public function close(): ?bool {
if (self :: $link) {
return pg_close(self :: $link);
}
+
+ return null;
}
- public function get_one($query, $parameters = null) {
+ /**
+ * Execute a query and return a single scalar value.
+ *
+ * @param string $query The SQL query.
+ * @param array<int, mixed>|null $parameters Positional parameter values.
+ *
+ * @return string|false The first column of the first row, or false if no results.
+ */
+ public function get_one(string $query, ?array $parameters = null): string|false {
$res = $this->query($query, $parameters);
if (pg_num_rows($res)) {
@@ -261,23 +387,34 @@ class Pgsql extends DBDriver {
}
}
- function get_row($query, $parameters) {
- $res = $this->query($query . ' LIMIT 1', $parameters);
-
- if ($res === null) {
- $res = $this->last_res;
- }
-
+ /**
+ * Execute a query and return a single row.
+ *
+ * @param string $query The SQL query (LIMIT 1 is appended automatically).
+ * @param array<int, mixed> $parameters Positional parameter values.
+ *
+ * @return array<string, mixed>|null The row as an associative array<array-key, mixed>, or null on failure.
+ */
+ public function get_row(string $query, array $parameters): ?array {
+ $res = $this->query($query . ' LIMIT 1', $parameters);
$values = pg_fetch_assoc($res);
if ($res) {
pg_free_result($res);
}
- return $values;
+ return $values ?: null;
}
- public function get_all($query, $parameters = null) {
+ /**
+ * Execute a query and return all rows.
+ *
+ * @param string $query The SQL query.
+ * @param array<int, mixed>|null $parameters Positional parameter values.
+ *
+ * @return array<int, array<string, mixed>>|false All rows, or false if no results.
+ */
+ public function get_all(string $query, ?array $parameters = null): array|false {
$res = $this->query($query, $parameters);
if (pg_num_rows($res)) {
@@ -293,7 +430,14 @@ class Pgsql extends DBDriver {
}
}
- function fetch_row($res = null) {
+ /**
+ * Fetch a single row from a result resource and free it.
+ *
+ * @param resource|null $res The pgsql result resource, or null to use the last result.
+ *
+ * @return array<string, mixed>|null The row as an associative array<array-key, mixed>, or null if no rows.
+ */
+ public function fetch_row($res = null): ?array {
if ($res === null) {
$res = $this->last_res;
}
@@ -304,20 +448,34 @@ class Pgsql extends DBDriver {
pg_free_result($res);
}
- return $values;
+ return $values ?: null;
}
- // Prepare
- public function execute($sql, $params = [], $paramTypes = []) {
- list($sql, $params) = Event::trigger(__CLASS__,__FUNCTION__, $sql, $params);
+ /**
+ * Prepare and execute a parameterised query.
+ *
+ * Fires an Event::trigger hook before execution. Converts named parameters
+ * to positional $1, $2... placeholders for pg_query_params. Updates
+ * affected_rows on success.
+ *
+ * @param string $sql The SQL query with :named parameters.
+ * @param array<string, mixed> $params Named parameter values.
+ * @param array<string, string> $paramTypes Optional explicit type overrides.
+ *
+ * @throws \Exception On query failure.
+ *
+ * @return \PgSql\Result|false The query result, or false on failure.
+ */
+ public function execute(string $sql, array $params = [], array $paramTypes = []): \PgSql\Result|false {
+ [$sql, $params] = Event::trigger(__CLASS__, __FUNCTION__, $sql, $params);
//save orig sql for debugging info
$origSql = $sql;
- if (! self :: $link) {
+ if (!self :: $link) {
$this->connect();
}
- list($parameters, $types) = $this->paramsToQmark($sql, $params, $paramTypes, '$');
+ [$parameters, $types] = $this->paramsToQmark($sql, $params, $paramTypes, '$');
if (LOG_SQL_QUERIES) {
error_log($this->debugSql($origSql, $params, $paramTypes));
@@ -345,9 +503,4 @@ class Pgsql extends DBDriver {
return $this->last_res;
}
-
- // Bind
- public function bind($param, $value, $type = null) {
- $this->stmt->bindValue($param, $value, $type);
- }
}
diff --git a/system/db/sqlite.php b/system/db/sqlite.php
old mode 100755
new mode 100644
index 85192dd..f000b57
--- a/system/db/sqlite.php
+++ b/system/db/sqlite.php
@@ -24,67 +24,126 @@ namespace Vvveb\System\Db;
use Vvveb\System\Event;
+/**
+ * SQLite database driver using the SQLite3 extension.
+ *
+ * Provides connection management, query execution with parameterised statements,
+ * result fetching, escaping, and schema introspection for SQLite databases.
+ */
class Sqlite extends DBDriver {
- private static $link = null;
+ /** @var ?\SQLite3 The shared database connection (singleton per process). */
+ private static ?\SQLite3 $link = null;
- //public $error;
+ /** @var int Number of rows affected by the last query. */
+ public int $affected_rows = 0;
- private $stmt;
+ /** @var int|bool Number of rows returned by the last query, or 0 if not applicable. */
+ public int|bool $num_rows = 0;
- public $affected_rows = 0;
+ /** @var ?int The row ID of the last inserted row, or null if none. */
+ public ?int $insert_id = null;
- public $num_rows = 0;
+ /** @var string Table name prefix. */
+ public string $prefix = ''; //'vv_';
- public $insert_id = null;
+ /** @var string Identifier quote character for SQLite. */
+ public string $quote = '"';
- public $prefix = ''; //'vv_';
-
- public $quote = '`';
-
- public static function version() {
+ /**
+ * Get the SQLite library version number.
+ *
+ * @return int|false The version number (e.g. 3039000), or false if not connected.
+ */
+ public static function version(): int|false {
if (self :: $link) {
- return mysqli_get_server_version(self :: $link);
+ return \SQLite3::version()['versionNumber'] ?? false;
}
+
+ return false;
}
- public static function info() {
+ /**
+ * Get the SQLite library version string.
+ *
+ * @return string|false The version string (e.g. '3.39.0'), or false if not connected.
+ */
+ public static function info(): string|false {
if (self :: $link) {
- return self :: $link->version();
+ return \SQLite3::version()['versionString'] ?? false;
}
+
+ return false;
}
- public function error() {
+ /**
+ * Get the error message from the last SQLite operation.
+ *
+ * @return string The error message, or empty string if not connected.
+ */
+ public function error(): string {
if (self :: $link) {
- return self :: $link->lastErrorMsg() ?? '';
+ return self :: $link->lastErrorMsg();
}
+
+ return '';
}
- public function errorCode() {
+ /**
+ * Get the error code from the last SQLite operation.
+ *
+ * @return int The error code, or 0 if not connected.
+ */
+ public function errorCode(): int {
if (self :: $link) {
- return self :: $link->lastErrorCode() ?? 0;
+ return self :: $link->lastErrorCode();
}
+
+ return 0;
}
- public function get_result($stmt) {
+ /**
+ * Pass through the statement result unchanged.
+ *
+ * @param mixed $stmt The statement result.
+ *
+ * @return mixed The same statement result.
+ */
+ public function get_result(mixed $stmt): mixed {
return $stmt;
- $result = new \SQLite3Stmt($stmt);
-
- return $result;
}
- public function __construct($filename = DB_HOST, $dbname = DB_NAME, $user = DB_USER, $pass = DB_PASS, $port = null, $prefix = DB_PREFIX) {
+ public function __construct() {
//return $this->connect($host, $dbname, $user, $pass, $port, $prefix);
}
- public function connect($filename = DB_HOST, $dbname = DB_NAME, $user = DB_USER, $pass = DB_PASS, $port = null, $prefix = DB_PREFIX) {
+ /**
+ * Connect to the SQLite database.
+ *
+ * Uses a singleton pattern — returns the existing connection if already open.
+ * Enables exceptions for error handling.
+ *
+ * @param string $filename The SQLite database file path.
+ * @param string $dbname Database name (unused for SQLite).
+ * @param string $user Database user (unused for SQLite).
+ * @param string $pass Database password (unused for SQLite).
+ * @param ?string $port Port (unused for SQLite).
+ * @param string $prefix Table name prefix.
+ *
+ * @throws \Exception On connection failure.
+ *
+ * @return \SQLite3 The database connection.
+ */
+ public function connect(string $filename = DB_HOST, string $dbname = DB_NAME, string $user = DB_USER, string $pass = DB_PASS, ?string $port = null, string $prefix = DB_PREFIX): \SQLite3 {
if (self :: $link) {
return self :: $link;
}
+ $this->prefix = $prefix;
+
try {
self :: $link = new \SQLite3($filename); //, SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE);
} catch (\Exception $e) {
- $errorMessage = str_replace($pass,'*****', $e->getMessage());
+ $errorMessage = str_replace($pass, '*****', $e->getMessage());
throw new \Exception($errorMessage, $e->getCode());
}
@@ -94,36 +153,46 @@ class Sqlite extends DBDriver {
return self :: $link;
}
- /*
- * Get all columns for a table used for sanitizing input
+ /**
+ * Get all columns for a table used for sanitizing input.
+ *
+ * @param string $tableName The table name to introspect.
+ * @param bool $comment Whether to include column comments (unused for SQLite).
+ *
+ * @return array<string, array{name: string, d: mixed, n: string, t: string}>|false
+ * Associative array keyed by column name, or false on failure.
*/
- function getColumnsMeta($tableName, $comment = false) {
+ public function getColumnsMeta(string $tableName, bool $comment = false): array|false {
$sql =
"SELECT type as t, name, dflt_value as d, `notnull` as n FROM pragma_table_info('$tableName');";
if ($result = $this->query($sql)) {
- //$columns = $result->fetch_all(MYSQLI_ASSOC);
$columns = [];
while ($row = $result->fetchArray(SQLITE3_ASSOC)) {
$columns[$row['name']] = $row;
}
- /* free result set */
+ // free result set
$result->finalize();
return $columns;
- } else {
}
return false;
}
- function getTableNames($db = DB_NAME) {
+ /**
+ * Get all table names in the database.
+ *
+ * @param string $db The database name (unused for SQLite — reads sqlite_master).
+ *
+ * @return array<int, string>|false List of table names, or false on failure.
+ */
+ public function getTableNames(string $db = DB_NAME): array|false {
$sql = "SELECT name FROM sqlite_master WHERE type ='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '%_search%' ORDER BY name";
if ($result = $this->query($sql)) {
- //$columns = $result->fetch_all(MYSQLI_ASSOC);
$names = [];
while ($row = $result->fetchArray(SQLITE3_ASSOC)) {
@@ -131,17 +200,26 @@ class Sqlite extends DBDriver {
$names[] = $row['name'];
}
- /* free result set */
+ // free result set
$result->finalize();
return $names;
- } else {
}
return false;
}
- public function escape($string) {
+ /**
+ * Escape a value for safe inclusion in a SQL query.
+ *
+ * Strings are escaped with SQLite3::escapeString. Null values become 'null'.
+ * All other types are returned as-is.
+ *
+ * @param mixed $string The value to escape.
+ *
+ * @return mixed The escaped value.
+ */
+ public function escape(mixed $string): mixed {
if (is_string($string)) {
return self :: $link->escapeString($string);
}
@@ -153,48 +231,70 @@ class Sqlite extends DBDriver {
return $string;
}
- public function escapeLiteral($string) {
+ /**
+ * Escape a string value for use in a SQL literal.
+ *
+ * @param string $string The string to escape.
+ *
+ * @return string The escaped string.
+ */
+ public function escapeLiteral(string $string): string {
return $this->escape($string);
}
- public function sqlLimit($start, $limit) {
- return "LIMIT $start, $limit";
- }
-
- public function fetchOne($result) {
- $return = false;
-
- if ($result) {
- $return = $result->fetchArray(SQLITE3_NUM)[0] ?? null;
- }
-
- return $return;
+ /**
+ * Fetch a single scalar value from a result.
+ *
+ * @param \SQLite3Result $result The query result.
+ *
+ * @return mixed The first column value, or null if no row or the value is null.
+ */
+ public function fetchOne(\SQLite3Result $result): mixed {
+ return $result->fetchArray(SQLITE3_NUM)[0] ?? null;
}
- public function fetchArray($result) {
- $return = false;
-
- if ($result) {
- $return = $result->fetchArray(SQLITE3_ASSOC);
- }
-
- return $return;
+ /**
+ * Fetch a single row from a result.
+ *
+ * @param \SQLite3Result $result The query result.
+ *
+ * @return array<string, mixed>|false The row as an associative array<array-key, mixed>, or false if no results.
+ */
+ public function fetchArray(\SQLite3Result $result): array|false {
+ return $result->fetchArray(SQLITE3_ASSOC);
}
- public function fetchAll($result) {
+ /**
+ * Fetch all rows from a result.
+ *
+ * @param \SQLite3Result $result The query result.
+ *
+ * @return array<int, array<string, mixed>> All result rows.
+ */
+ public function fetchAll(\SQLite3Result $result): array {
$return = [];
- if ($result) {
- while ($row = $result->fetchArray(SQLITE3_ASSOC)) {
- $return[] = $row;
- }
+ while ($row = $result->fetchArray(SQLITE3_ASSOC)) {
+ $return[] = $row;
}
return $return;
}
- public function query($sql) {
- if (! self :: $link) {
+ /**
+ * Execute a raw SQL query.
+ *
+ * Automatically connects if not connected. Updates affected_rows, insert_id,
+ * and num_rows on success.
+ *
+ * @param string $sql The SQL query to execute.
+ *
+ * @throws \Exception On query failure.
+ *
+ * @return \SQLite3Result|false The query result, or false on failure.
+ */
+ public function query(string $sql): \SQLite3Result|false {
+ if (!self :: $link) {
$this->connect();
}
@@ -226,7 +326,16 @@ class Sqlite extends DBDriver {
return $result;
}
- public function multi_query($sql) {
+ /**
+ * Execute multiple SQL statements by splitting on semicolons.
+ *
+ * @param string $sql The SQL statements to execute (semicolon-separated).
+ *
+ * @throws \Exception On any statement failure.
+ *
+ * @return array<int, \SQLite3Result> Array of results from each statement.
+ */
+ public function multi_query(string $sql): array {
$results = [];
$queries = preg_split('/;\n/', $sql);
@@ -265,23 +374,45 @@ class Sqlite extends DBDriver {
return $results;
}
- public function close() {
+ /**
+ * Close the database connection.
+ *
+ * @return bool|null True on success, null if not connected.
+ */
+ public function close(): ?bool {
if (self :: $link) {
return self :: $link->close();
}
+
+ return null;
}
- // Prepare
- public function execute($sql, $params = [], $paramTypes = []) {
- list($sql, $params) = Event::trigger(__CLASS__,__FUNCTION__, $sql, $params);
+ /**
+ * Prepare and execute a parameterised query.
+ *
+ * Fires an Event::trigger hook before execution. Converts named parameters
+ * to positional ? placeholders, binds values with appropriate SQLite3 type
+ * constants, and executes the statement. Updates affected_rows, insert_id,
+ * and num_rows on success.
+ *
+ * @param string $sql The SQL query with :named parameters.
+ * @param array<string, mixed> $params Named parameter values.
+ * @param array<string, string> $paramTypes Optional explicit type overrides.
+ *
+ * @throws \Exception On prepare or execute failure.
+ *
+ * @return \SQLite3Result|false|null The query result, false, or null on failure.
+ */
+ public function execute(string $sql, array $params = [], array $paramTypes = []): \SQLite3Result|false|null {
+ [$sql, $params] = Event::trigger(__CLASS__, __FUNCTION__, $sql, $params);
//save orig sql for debugging info
$origSql = $sql;
- if (! self :: $link) {
+ if (!self :: $link) {
$this->connect();
}
- list($parameters, $types) = $this->paramsToQmark($sql, $params, $paramTypes);
+ [$parameters, $types] = $this->paramsToQmark($sql, $params, $paramTypes);
try {
$stmt = self::$link->prepare($sql);
@@ -293,10 +424,14 @@ class Sqlite extends DBDriver {
if ($stmt/* && ! empty($paramTypes)*/) {
foreach ($parameters as $key => $value) {
- $type = $types[$key] ?? 's';
- $type = ($type == 'i') ? SQLITE3_INTEGER : SQLITE3_TEXT;
+ $bindType = match ($types[$key] ?? 's') {
+ 'i' => SQLITE3_INTEGER,
+ 'd' => SQLITE3_FLOAT,
+ 'b' => SQLITE3_BLOB,
+ default => SQLITE3_TEXT,
+ };
$index = (int)$key + 1;
- $stmt->bindValue($index, $value, $type);
+ $stmt->bindValue($index, $value, $bindType);
}
} else {
if (DEBUG) {
@@ -319,24 +454,19 @@ class Sqlite extends DBDriver {
return $result;
} else {
- error_log(print_r($result, 1));
+ error_log(print_r($result, true));
error_log($this->debugSql($sql, $params, $paramTypes));
}
} catch (\Exception $e) {
- $message = $e->getMessage() . "\n" . $origSql . "\n" . $this->debugSql($origSql, $params, $paramTypes) . "\n" . print_r($parameters, 1) . $types . "\n" . print_r(debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 1), true);
+ $message = $e->getMessage() . "\n" . $origSql . "\n" . $this->debugSql($origSql, $params, $paramTypes) . "\n" . print_r($parameters, true) . $types . "\n" . print_r(debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 1), true);
throw new \Exception($message, $e->getCode());
}
} else {
- error_log(print_r($stmt, 1));
+ error_log(print_r($stmt, true));
error_log($this->debugSql($origSql, $params, $paramTypes));
}
return $stmt;
}
-
- // Bind
- public function bind($param, $value, $type = null) {
- $this->stmt->bindValue($param, $value, $type);
- }
}
diff --git a/system/import/sql.php b/system/import/sql.php
index 3e4dbe3..5ee6b97 100755
--- a/system/import/sql.php
+++ b/system/import/sql.php
@@ -26,66 +26,102 @@ use function Vvveb\globBrace;
#[\AllowDynamicProperties]
class Sql {
- private $db;
-
- private $prefix;
-
- function __construct($driver = DB_ENGINE, $host = DB_HOST, $dbname = DB_NAME, $user = DB_USER, $pass = DB_PASS, $port = DB_PASS, $prefix = DB_PREFIX) {
+ /** @var \Vvveb\System\Db\DBDriver */
+ private \Vvveb\System\Db\DBDriver $db;
+
+ /**
+ * @var string
+ */
+ private string $prefix;
+
+ /**
+ * @var string Database driver name (mysqli, pgsql, sqlite).
+ */
+ private string $driver = '';
+
+ /**
+ * @var string
+ */
+ private string $sqlPath = '';
+
+ /**
+ * @param string $driver Database driver.
+ * @param string $dbname Database name.
+ * @param string $prefix Table name prefix.
+ */
+ public function __construct(string $driver = DB_ENGINE, string $dbname = DB_NAME, string $prefix = DB_PREFIX) {
+ $this->driver = $driver;
$this->sqlPath = DIR_ROOT . "install/sql/$driver/";
$engine = '\Vvveb\System\Db\\' . ucfirst($driver);
$this->prefix = $prefix;
try {
- $this->db = new $engine($host, $dbname, $user, $pass, $port, $prefix);
+ $this->db = new $engine();
} catch (\Exception $e) {
//unknown database, try to create
if ($e->getCode() == 1049) {
- $this->db = new $engine($host, '', $user, $pass, $port, $prefix);
+ $this->db = new $engine();
if ($driver !== 'sqlite') {
$this->createDb($dbname);
}
} else {
- throw($e);
+ throw $e;
}
}
}
- private $sqlPath = '';
-
- function setPath($path) {
+ /**
+ * @param string $path
+ *
+ * @return void
+ */
+ public function setPath(string $path): void {
$this->sqlPath = $path;
}
- function createDb($dbname) {
- if (! $this->db->query("CREATE DATABASE IF NOT EXISTS `$dbname`")) {
- throw new \Exception($this->db->error);
+ /**
+ * @param string $dbname
+ *
+ * @return void
+ */
+ public function createDb(string $dbname): void {
+ $q = $this->db->quote;
+
+ if (!$this->db->query("CREATE DATABASE IF NOT EXISTS $q$dbname$q")) {
+ throw new \Exception($this->db->error());
}
- if (! $this->db->select_db($dbname)) {
- throw new \Exception($this->db->error);
+ if (!$this->db->select_db($dbname)) {
+ throw new \Exception($this->db->error());
}
}
- function prefixTable($query, $prefix) {
+ /**
+ * @param string $query
+ * @param string $prefix
+ *
+ * @return string
+ */
+ public function prefixTable(string $query, string $prefix): string {
$tableName = '';
- //$regexs[] = '/(SELECT.+FROM\s+`?)(\w+`? AS \w+|\w+`?)/ims';
- $regexs[] = '/(UPDATE\s+`?)(\w+`? AS \w+\s+SET|\w+`?\s+SET)/ims';
- $regexs[] = '/(INSERT\s+INTO\s+`?)(\w+`? AS \w+|\w+`?)/ims';
- //$regexs[] = '/(DELETE\s+FROM\s+`?)(\w+`? AS \w+|\w+`?)/ims';
- $regexs[] = '/(\s+JOIN\s+`?)(\w+ AS \w+|\w+`?)/ims';
- $regexs[] = '/(CREATE\s+TABLE\s+`?)(\w+ AS \w+|\w+`?)/ims';
- $regexs[] = '/(\s+IF\s+EXISTS\s+`?)(\w+ AS \w+|\w+`?)/ims';
- $regexs[] = '/(\s+FROM\s+`?)(\w+ AS \w+|\w+`?)/ims';
-
- foreach ($regexs as $regex) {
+ $regexes = [
+ //'/(SELECT.+FROM\s+`?)(\w+`? AS \w+|\w+`?)/ims';
+ '/(UPDATE\s+`?)(\w+`? AS \w+\s+SET|\w+`?\s+SET)/ims',
+ '/(INSERT\s+INTO\s+`?)(\w+`? AS \w+|\w+`?)/ims',
+ //'/(DELETE\s+FROM\s+`?)(\w+`? AS \w+|\w+`?)/ims';
+ '/(\s+JOIN\s+`?)(\w+ AS \w+|\w+`?)/ims',
+ '/(CREATE\s+TABLE\s+`?)(\w+ AS \w+|\w+`?)/ims',
+ '/(\s+IF\s+EXISTS\s+`?)(\w+ AS \w+|\w+`?)/ims',
+ '/(\s+FROM\s+`?)(\w+ AS \w+|\w+`?)/ims',
+ ];
+
+ foreach ($regexes as $regex) {
$query = preg_replace_callback(
$regex,
- function ($matches) use ($prefix) {
- return $matches[1] . $prefix . $matches[2];
- },
+ fn ($matches) => $matches[1] . $prefix . $matches[2],
$query
);
}
@@ -93,9 +129,15 @@ class Sql {
return $query;
}
- function multiQuery($sql, $filename = '') {
- if (! $sql) {
- return;
+ /**
+ * @param string $sql
+ * @param string $filename
+ *
+ * @return bool|array<array-key, mixed>|null
+ */
+ public function multiQuery(string $sql, string $filename = ''): bool|array|null {
+ if (!$sql) {
+ return null;
}
if ($this->prefix) {
@@ -103,8 +145,8 @@ class Sql {
}
try {
- if (DB_ENGINE == 'mysqli' || DB_ENGINE == 'pgsql') {
- if (! ($stmt = $this->db->multi_query($sql))) {
+ if ($this->driver == 'mysqli' || $this->driver == 'pgsql') {
+ if (!($stmt = $this->db->multi_query($sql))) {
throw new \Exception($this->db->error() . "\n\n in $filename\n\n" . substr($sql, 0, 256));
}
} else {
@@ -116,14 +158,11 @@ class Sql {
throw new \Exception($e->getMessage() . "\n\n" . substr($sql, 0, 256) . "\n\n in $filename", $e->getCode());
}
- if (DB_ENGINE == 'mysqli') {
+ if ($this->driver == 'mysqli') {
try {
do {
- /* store first result set */
+ // store first result set
if ($result = $this->db->store_result()) {
- /*
- while ($row = $result->fetchRow()) {
- }*/
$result->free();
}
} while ($this->db->more_results() && $this->db->next_result());
@@ -131,7 +170,7 @@ class Sql {
throw new \Exception($e->getMessage() . "\n\n" . substr($sql, 0, 256) . "\n\n in `$filename`", $e->getCode());
}
} else {
- if (DB_ENGINE == 'sqlite') {
+ if ($this->driver == 'sqlite') {
$result = [];
if ($stmt) {
@@ -142,7 +181,6 @@ class Sql {
while ($row = $stmt->fetchArray(SQLITE3_ASSOC)) {
$result[] = $row;
}
- //$stmt->finalize();
}
} catch (\Exception $e) {
throw new \Exception($e->getMessage() . "\n\n" . substr($sql, 0, 256) . "\n\n in `$filename`", $e->getCode());
@@ -151,7 +189,7 @@ class Sql {
$return = $this->db->insert_id ?: $this->db->affected_rows ?: $result;
- if (! $return && ! $this->db->errorCode()) {
+ if (!$return && !$this->db->errorCode()) {
$return = true;
}
@@ -162,11 +200,16 @@ class Sql {
return true;
}
- function createTables($files = []) {
- if (DB_ENGINE == 'sqlite') {
+ /**
+ * @param array<array-key, mixed> $files
+ *
+ * @return void
+ */
+ public function createTables(array $files = []): void {
+ if ($this->driver == 'sqlite') {
//try to speed up install
$query = 'pragma journal_mode = WAL;pragma synchronous = normal;pragma temp_store = memory;pragma mmap_size = 30000000000;PRAGMA writable_schema = 1;';
- $this->db->query($query , 'journal_mode WAL');
+ $this->db->query($query, 'journal_mode WAL');
//check if sql file has minimum version and if current version is supported
//$currentVersion = \SQLite3::version()['versionString'] ?? '3.0.0';
@@ -174,24 +217,21 @@ class Sql {
$fts5Support = true;
$query = 'DROP TABLE IF EXISTS fts5_module_available_test';
- $this->db->query($query , 'fts5 test module');
+ $this->db->query($query, 'fts5 test module');
try {
$query = 'CREATE VIRTUAL TABLE fts5_module_available_test USING fts5(sender, title, body)';
- $this->db->query($query , 'fts5 test module');
- $fts5Support = ! $this->db->errorCode();
+ $this->db->query($query, 'fts5 test module');
+ $fts5Support = !$this->db->errorCode();
} catch (\Exception $e) {
$fts5Support = false;
}
$query = 'DROP TABLE IF EXISTS fts5_module_available_test';
- $this->db->query($query , 'fts5 test module');
+ $this->db->query($query, 'fts5 test module');
}
- $glob = ['', '*/*/', '*/'];
-
- //$files = glob($name, GLOB_BRACE);
- if (! $files) {
+ if (!$files) {
$files = globBrace($this->sqlPath, ['', '**/', '*/*/'], '*.sql');
}
@@ -201,11 +241,10 @@ class Sql {
//remove comments
$sql = preg_replace('/-- .+/', '', $sql);
- if (DB_ENGINE == 'mysqli' || DB_ENGINE == 'pgsql') {
+ if ($this->driver == 'mysqli' || $this->driver == 'pgsql') {
$this->multiQuery($sql, $filename);
} else {
- if (DB_ENGINE == 'sqlite') {
- //$this->multiQuery($sql, $filename);
+ if ($this->driver == 'sqlite') {
//sqlite has problems running multiple queries
//older sqlite bellow 3.9.0 do not have fts5 full text search module use fts4 instead
@@ -237,7 +276,12 @@ class Sql {
}
}
- function insertEscape($sql) {
+ /**
+ * @param string $sql
+ *
+ * @return string
+ */
+ public function insertEscape(string $sql): string {
//replace ` with database escape quote eg: "
$quote = $this->db->quote;
@@ -245,45 +289,44 @@ class Sql {
return $sql;
}
- $sql = preg_replace_callback('/INSERT\s+INTO\s*`.+?`\s*(\(.+?\))?\s*VALUES/i', function ($m) use ($quote) {
- return str_replace('`', $quote, $m[0]);
- }, $sql);
-
- return $sql;
+ return preg_replace_callback('/INSERT\s+INTO\s*`.+?`\s*(\(.+?\))?\s*VALUES/i', fn ($m) => str_replace('`', $quote, $m[0]), $sql);
}
- function insertData($include = [], $exclude = []) {
- $glob = ['', '*/*/', '*/'];
-
- //$files = glob($name, GLOB_BRACE);
- $files = globBrace($this->sqlPath, ['', '**/', '*/*/'], '*.sql');
-
- //expand * and transform to regex
- $includeRegex = '';
+ /**
+ * Expand * wildcards and transform a filter list to a regex.
+ *
+ * @param array<array-key, mixed> $filters
+ *
+ * @return string Empty string when no filters are given.
+ */
+ private function buildFilterRegex(array $filters): string {
+ if (!$filters) {
+ return '';
+ }
- if ($include) {
- foreach ($include as $filter) {
- if ($includeRegex) {
- $includeRegex .= '|';
- }
- $includeRegex .= str_replace('*', '.*', addslashes($filter));
- }
+ $parts = [];
- $includeRegex = '/' . $includeRegex . '/';
+ foreach ($filters as $filter) {
+ $parts[] = str_replace('*', '.*', addslashes($filter));
}
- $excludeRegex = '';
+ return '/' . implode('|', $parts) . '/';
+ }
- if ($exclude) {
- foreach ($exclude as $filter) {
- if ($excludeRegex) {
- $excludeRegex .= '|';
- }
- $excludeRegex .= str_replace('*', '.*', addslashes($filter));
- }
+ /**
+ * @param array<array-key, mixed> $include
+ * @param array<array-key, mixed> $exclude
+ * @param array<array-key, mixed> $template
+ * @param callable|null $callback
+ *
+ * @return void
+ */
+ public function insertData(array $include = [], array $exclude = [], array $template = [], ?callable $callback = null): void {
+ $files = globBrace($this->sqlPath, ['', '**/', '*/*/'], '*.sql');
- $excludeRegex = '/' . $excludeRegex . '/';
- }
+ //expand * and transform to regex
+ $includeRegex = $this->buildFilterRegex($include);
+ $excludeRegex = $this->buildFilterRegex($exclude);
foreach ($files as $filename) {
$name = basename($filename);
@@ -292,13 +335,122 @@ class Sql {
continue;
}
- if ($includeRegex && ! preg_match($includeRegex, $name)) {
+ if ($includeRegex && !preg_match($includeRegex, $name)) {
continue;
}
$sql = file_get_contents($filename);
$sql = $this->insertEscape($sql);
- $this->multiQuery($sql, str_replace($this->sqlPath, '', $filename));
+
+ if ($callback) {
+ $sql = $callback($sql);
+ }
+
+ $this->multiQuery($sql, str_replace($this->sqlPath, '', $filename));
+ }
+ }
+
+ /**
+ * @param string $newSqlPath
+ * @param string $sqlPath
+ *
+ * @return void
+ */
+ public function upgradeDb(string $newSqlPath, string $sqlPath): void {
+ $db = $this->db;
+ $tableNames = $db->getTableNames();
+
+ $files = \Vvveb\globBrace($sqlPath, ['', '*/*/'], '*.sql');
+
+ $q = $this->db->quote;
+
+ //get table names from sql files
+ foreach ($files as $filename) {
+ $tableName = basename($filename, '.sql');
+ $newFilename = str_replace($sqlPath, $newSqlPath, $filename);
+
+ if (file_exists($newFilename)) {
+ $currentSql = file_get_contents($filename);
+ $columns = $this->tableColumns($currentSql);
+
+ if (!$columns) {
+ continue;
+ }
+
+ $newSql = file_get_contents($newFilename);
+ $newColumns = $this->tableColumns($newSql);
+
+ if (!$newColumns) {
+ continue;
+ }
+
+ //newly added columns
+ $tableColumns = $db->getColumnsMeta($tableName);
+ $addedColumns = array_diff_key($newColumns, $tableColumns);
+
+ //changed columns
+ $changedColumns = [];
+ $deletedColumns = [];
+
+ foreach ($columns as $name => $column) {
+ if (isset($newColumns[$name])) {
+ if ($column != $newColumns[$name]) {
+ $changedColumns[$name] = $newColumns[$name];
+ }
+ } else {
+ $deletedColumns[$name] = $column[$name];
+ }
+ }
+
+ //add new columns
+ if ($addedColumns) {
+ //$tableColumns = $db->getColumnsMeta($tableName);
+
+ foreach ($addedColumns as $name => $definition) {
+ if (isset($tableColumns[$name])) {
+ //column already exists skip
+ continue;
+ }
+
+ $query = "ALTER TABLE $q$tableName$q ADD $definition";
+ $result = $db->query($query);
+ }
+ }
+
+ //change columns
+ if ($changedColumns) {
+ if (!$tableColumns) {
+ $tableColumns = $db->getColumnsMeta($tableName);
+ }
+
+ foreach ($changedColumns as $name => $definition) {
+ if (!isset($tableColumns[$name])) {
+ //column does not exist skip
+ continue;
+ }
+
+ $query = "ALTER TABLE $q$tableName$q MODIFY COLUMN $definition";
+ $result = $db->query($query);
+ }
+ }
+
+ //delete columns
+ if ($deletedColumns) {
+ if (!$tableColumns) {
+ $tableColumns = $db->getColumnsMeta($tableName);
+ }
+
+ foreach ($deletedColumns as $name => $definition) {
+ if (!isset($tableColumns[$name])) {
+ //column does not exist skip
+ continue;
+ }
+
+ $query = "ALTER TABLE $q$tableName$q DROP COLUMN $name";
+ $result = $db->query($query);
+ }
+ }
+ }
}
}
}
diff --git a/system/queue/providers/base.php b/system/queue/providers/base.php
new file mode 100755
index 0000000..71532c3
--- /dev/null
+++ b/system/queue/providers/base.php
@@ -0,0 +1,105 @@
+<?php
+
+/**
+ * Vvveb
+ *
+ * Copyright (C) 2022 Ziadin Givan
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace Vvveb\System\Queue\Providers;
+
+/**
+ * Shared helpers for queue providers: retry backoff computation,
+ * job id generation and job record normalization.
+ */
+abstract class Base implements Provider {
+ /** @var array<string, mixed> Provider options from config/queue.php. */
+ protected array $options = [];
+
+ /** @var array{base_delay_seconds: int, max_delay_seconds: int} Retry backoff settings. */
+ protected array $retry = [
+ 'base_delay_seconds' => 30,
+ 'max_delay_seconds' => 3600,
+ ];
+
+ /**
+ * @param array<string, mixed> $options Provider options (retry, ...).
+ */
+ public function __construct(array $options = []) {
+ $this->options = $options;
+ $this->retry = array_merge($this->retry, $options['retry'] ?? []);
+ }
+
+ /**
+ * Exponential backoff delay for attempt N: base * 2^attempts, capped.
+ *
+ * @param int $attempts Number of attempts used so far.
+ *
+ * @return int Delay in seconds.
+ */
+ protected function backoffDelay(int $attempts): int {
+ $base = max(1, (int)$this->retry['base_delay_seconds']);
+ $cap = max($base, (int)$this->retry['max_delay_seconds']);
+ $sec = $base * (2 ** max(0, $attempts));
+
+ return min($cap, $sec);
+ }
+
+ /**
+ * Generate a UUID v4 job id.
+ *
+ * @return string
+ */
+ public static function uuid(): string {
+ $data = random_bytes(16);
+
+ //set version to 0100 and IETF variant to 10
+ $data[6] = chr((ord($data[6]) & 0x0F) | 0x40);
+ $data[8] = chr((ord($data[8]) & 0x3F) | 0x80);
+
+ return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($data), 4));
+ }
+
+ /**
+ * Normalize a raw storage row into the standard job record shape:
+ * integer counters/timestamps and an decoded payload array.
+ *
+ * @param array<string, mixed> $row Raw row; payload may still be encoded JSON.
+ *
+ * @return array<array-key, mixed> Job record.
+ */
+ protected function normalize(array $row): array {
+ $payload = $row['payload'] ?? [];
+
+ if (is_string($payload)) {
+ $payload = json_decode($payload, true);
+ }
+
+ return [
+ 'id' => (string)($row['job_id'] ?? $row['id'] ?? ''),
+ 'queue' => (string)($row['queue'] ?? 'default'),
+ 'job' => (string)($row['job'] ?? ''),
+ 'payload' => is_array($payload) ? $payload : [],
+ 'attempts' => (int)($row['attempts'] ?? 0),
+ 'max_attempts' => (int)($row['max_attempts'] ?? 3),
+ 'available_at' => (int)($row['available_at'] ?? 0),
+ 'reserved_at' => isset($row['reserved_at']) && $row['reserved_at'] !== ''
+ ? (int)$row['reserved_at'] : null,
+ 'created_at' => (int)($row['created_at'] ?? 0),
+ ];
+ }
+}
diff --git a/system/queue/providers/database.php b/system/queue/providers/database.php
new file mode 100755
index 0000000..3354b3f
--- /dev/null
+++ b/system/queue/providers/database.php
@@ -0,0 +1,678 @@
+<?php
+
+/**
+ * Vvveb
+ *
+ * Copyright (C) 2022 Ziadin Givan
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace Vvveb\System\Queue\Providers;
+
+use Vvveb\System\Db;
+
+/**
+ * Database queue provider.
+ *
+ * Stores jobs in `queue_jobs` / `failed_jobs` tables using Vvveb's existing
+ * DB connection — no separate configuration needed. Tables have a numeric
+ * auto-increment `id` plus a public `job_id` UUID; the claim dialect is picked
+ * automatically from the configured engine and server version:
+ *
+ * - PostgreSQL: single-statement atomic claim using `FOR UPDATE SKIP LOCKED`
+ * in the subquery + `RETURNING`, letting multiple workers poll concurrently
+ * without blocking or double-claiming.
+ * - MySQL / MariaDB 8.0+ / 10.6+: transactional
+ * `SELECT ... FOR UPDATE SKIP LOCKED` + `UPDATE` by id — workers skip rows
+ * locked by other workers instead of waiting.
+ * Older servers fall back to an inherently-atomic single-statement claim
+ * using the `LAST_INSERT_ID(id)` trick to read back which row was claimed
+ * (no explicit transaction needed).
+ * - SQLite: no row-level locking (single writer by design) — a plain claim
+ * inside a `BEGIN IMMEDIATE` transaction serializes concurrent workers
+ * cleanly. Best paired with a single worker process / cron mode.
+ */
+class Database extends Base implements FailedJobsAware {
+ /** @var object Db driver instance (shared Vvveb connection). */
+ protected object $db;
+
+ /** @var string Active dialect: pgsql | mysql | sqlite. */
+ protected string $driver = 'mysql';
+
+ /** @var string Jobs table name (with prefix). */
+ protected string $jobsTable = 'queue_jobs';
+
+ /** @var string Failed jobs table name (with prefix). */
+ protected string $failedTable = 'failed_jobs';
+
+ /** @var bool Whether schema has been checked for this process. */
+ protected static bool $schemaChecked = false;
+
+ /** @var bool|null Server supports FOR UPDATE SKIP LOCKED (MySQL 8.0+ / MariaDB 10.6+). */
+ protected static ?bool $skipLocked = null;
+
+ /** @var string Comma-separated columns selected when reading back a job row. */
+ protected const ROW_COLUMNS = 'id, job_id, queue, job, payload, attempts, max_attempts, available_at, reserved_at, created_at';
+
+ /**
+ * @param array<string, mixed> $options Provider options (unused, kept for symmetry;
+ * the DB connection comes from config/db.php).
+ */
+ public function __construct(array $options = []) {
+ parent::__construct($options);
+
+ $this->db = Db::getInstance();
+
+ $engine = defined('DB_ENGINE') ? strtolower((string)DB_ENGINE) : 'mysqli';
+ $this->driver = match ($engine) {
+ 'pgsql' => 'pgsql',
+ 'sqlite' => 'sqlite',
+ default => 'mysql',
+ };
+
+ $prefix = $this->db->prefix ?? DB_PREFIX;
+ $this->jobsTable = $prefix . 'queue_jobs';
+ $this->failedTable = $prefix . 'failed_jobs';
+
+ if ($this->driver === 'sqlite') {
+ //serialize concurrent writers instead of failing with SQLITE_BUSY
+ try {
+ $this->db->query('PRAGMA busy_timeout = 5000');
+ @$this->db->query('PRAGMA journal_mode = WAL');
+ } catch (\Throwable $e) {
+ //ignore, best effort
+ }
+ }
+ }
+
+ /**
+ * Check whether the MySQL/MariaDB server supports FOR UPDATE SKIP LOCKED
+ * (MySQL 8.0+, MariaDB 10.6+). Cached per process.
+ *
+ * @return bool
+ */
+ protected function supportsSkipLocked(): bool {
+ if (static::$skipLocked !== null) {
+ return static::$skipLocked;
+ }
+
+ static::$skipLocked = false;
+
+ try {
+ $stmt = $this->db->execute('SELECT VERSION()');
+ $rows = $this->db->fetchAll($stmt);
+ $ver = (string)($rows[0]['VERSION()'] ?? $rows[0][array_key_first($rows[0])] ?? '');
+
+ if (stripos($ver, 'mariadb') !== false) {
+ //eg. 10.11.14-MariaDB
+ static::$skipLocked = version_compare($ver, '10.6', '>=');
+ } else {
+ //eg. 8.0.36
+ static::$skipLocked = version_compare($ver, '8.0.1', '>=');
+ }
+ } catch (\Throwable $e) {
+ if (function_exists('logError')) {
+ logError('[Queue] Version check failed, using fallback claim: ' . $e->getMessage());
+ }
+ }
+
+ return static::$skipLocked;
+ }
+
+ /**
+ * Create the queue tables if missing (once per process).
+ * Lets existing installations upgrade without re-running the installer.
+ *
+ * @return void
+ */
+ protected function ensureSchema(): void {
+ if (self::$schemaChecked) {
+ return;
+ }
+
+ self::$schemaChecked = true;
+
+ switch ($this->driver) {
+ case 'pgsql':
+ $sql[] = "CREATE TABLE IF NOT EXISTS {$this->jobsTable} (
+ id bigserial PRIMARY KEY,
+ \"job_id\" varchar(36) NOT NULL,
+ \"queue\" varchar(128) NOT NULL DEFAULT 'default',
+ \"job\" varchar(255) NOT NULL,
+ \"payload\" text,
+ attempts integer NOT NULL DEFAULT 0,
+ max_attempts integer NOT NULL DEFAULT 3,
+ available_at bigint NOT NULL DEFAULT 0,
+ reserved_at bigint DEFAULT NULL,
+ created_at bigint NOT NULL DEFAULT 0
+ )";
+ $sql[] = "CREATE TABLE IF NOT EXISTS {$this->failedTable} (
+ \"job_id\" varchar(36) NOT NULL PRIMARY KEY,
+ \"queue\" varchar(128) NOT NULL DEFAULT 'default',
+ \"job\" varchar(255) NOT NULL,
+ \"payload\" text,
+ error text,
+ attempts integer NOT NULL DEFAULT 0,
+ max_attempts integer NOT NULL DEFAULT 3,
+ failed_at bigint NOT NULL DEFAULT 0
+ )";
+ $sql[] = 'CREATE UNIQUE INDEX IF NOT EXISTS u_queue_jobs_job_id ON ' . $this->jobsTable . ' ("job_id")';
+ $sql[] = 'CREATE INDEX IF NOT EXISTS idx_queue_jobs_queue_available ON ' . $this->jobsTable . ' ("queue", "available_at")';
+ $sql[] = 'CREATE INDEX IF NOT EXISTS idx_queue_jobs_reserved ON ' . $this->jobsTable . ' ("reserved_at")';
+ break;
+
+ case 'sqlite':
+ $sql[] = "CREATE TABLE IF NOT EXISTS `{$this->jobsTable}` (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ job_id TEXT NOT NULL UNIQUE,
+ queue TEXT NOT NULL DEFAULT 'default',
+ job TEXT NOT NULL,
+ payload TEXT,
+ attempts INTEGER NOT NULL DEFAULT 0,
+ max_attempts INTEGER NOT NULL DEFAULT 3,
+ available_at INTEGER NOT NULL DEFAULT 0,
+ reserved_at INTEGER DEFAULT NULL,
+ created_at INTEGER NOT NULL DEFAULT 0
+ )";
+ $sql[] = "CREATE TABLE IF NOT EXISTS `{$this->failedTable}` (
+ job_id TEXT NOT NULL PRIMARY KEY,
+ queue TEXT NOT NULL DEFAULT 'default',
+ job TEXT NOT NULL,
+ payload TEXT,
+ error TEXT,
+ attempts INTEGER NOT NULL DEFAULT 0,
+ max_attempts INTEGER NOT NULL DEFAULT 3,
+ failed_at INTEGER NOT NULL DEFAULT 0
+ )";
+ $sql[] = "CREATE INDEX IF NOT EXISTS idx_queue_jobs_queue_available ON `{$this->jobsTable}` (`queue`, `available_at`)";
+ $sql[] = "CREATE INDEX IF NOT EXISTS idx_queue_jobs_reserved ON `{$this->jobsTable}` (`reserved_at`)";
+ break;
+
+ default: //mysql / mariadb
+ $sql[] = "CREATE TABLE IF NOT EXISTS `{$this->jobsTable}` (
+ `id` bigint unsigned NOT NULL AUTO_INCREMENT,
+ `job_id` varchar(36) NOT NULL,
+ `queue` varchar(128) NOT NULL DEFAULT 'default',
+ `job` varchar(255) NOT NULL,
+ `payload` json DEFAULT NULL,
+ `attempts` int NOT NULL DEFAULT 0,
+ `max_attempts` int NOT NULL DEFAULT 3,
+ `available_at` bigint NOT NULL DEFAULT 0,
+ `reserved_at` bigint DEFAULT NULL,
+ `created_at` bigint NOT NULL DEFAULT 0,
+ PRIMARY KEY (`id`),
+ UNIQUE KEY `u_job_id` (`job_id`),
+ KEY `idx_queue_available` (`queue`, `available_at`),
+ KEY `idx_reserved_at` (`reserved_at`)
+ ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4";
+ $sql[] = "CREATE TABLE IF NOT EXISTS `{$this->failedTable}` (
+ `job_id` varchar(36) NOT NULL,
+ `queue` varchar(128) NOT NULL DEFAULT 'default',
+ `job` varchar(255) NOT NULL,
+ `payload` json DEFAULT NULL,
+ `error` text,
+ `attempts` int NOT NULL DEFAULT 0,
+ `max_attempts` int NOT NULL DEFAULT 3,
+ `failed_at` bigint NOT NULL DEFAULT 0,
+ PRIMARY KEY (`job_id`),
+ KEY `idx_failed_queue` (`queue`, `failed_at`)
+ ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4";
+ break;
+ }
+
+ foreach ($sql as $stmt) {
+ try {
+ $this->db->execute($stmt);
+ } catch (\Throwable $e) {
+ //duplicate index etc — ignore, tables exist from installer schema
+ }
+ }
+ }
+
+ /**
+ * @param string $queue Queue name.
+ * @param array<array-key, mixed> $job Job record.
+ *
+ * @return string Job id.
+ */
+ public function push(string $queue, array $job): string {
+ $this->ensureSchema();
+
+ $this->db->execute(
+ "INSERT INTO {$this->jobsTable} (job_id, queue, job, payload, attempts, max_attempts, available_at, reserved_at, created_at)
+ VALUES (:id, :queue, :job, :payload, :attempts, :max_attempts, :available_at, :reserved_at, :created_at)",
+ [
+ 'id' => $job['id'],
+ 'queue' => $queue,
+ 'job' => $job['job'],
+ 'payload' => json_encode($job['payload'] ?? []),
+ 'attempts' => (int)($job['attempts'] ?? 0),
+ 'max_attempts' => (int)($job['max_attempts'] ?? 3),
+ 'available_at' => (int)($job['available_at'] ?? time()),
+ 'reserved_at' => null,
+ 'created_at' => (int)($job['created_at'] ?? time()),
+ ]
+ );
+
+ return (string)$job['id'];
+ }
+
+ /**
+ * Fetch a full job row by numeric id.
+ *
+ * @param int $numericId Numeric row id.
+ *
+ * @return array<array-key, mixed>|null
+ */
+ protected function fetchRowById(int $numericId): ?array {
+ $stmt = $this->db->execute(
+ 'SELECT ' . self::ROW_COLUMNS . " FROM {$this->jobsTable} WHERE id = :nid",
+ ['nid' => $numericId]
+ );
+ $rows = $this->db->fetchAll($stmt);
+
+ return $rows ? $this->normalize($rows[0]) : null;
+ }
+
+ /**
+ * Atomically claim and return the next available job.
+ *
+ * @param string $queue Queue name.
+ *
+ * @return array<array-key, mixed>|null
+ */
+ public function pop(string $queue): ?array {
+ $this->ensureSchema();
+ $now = time();
+
+ switch ($this->driver) {
+ case 'pgsql':
+ //FOR UPDATE SKIP LOCKED lets multiple workers poll concurrently
+ $stmt = $this->db->execute(
+ "UPDATE {$this->jobsTable} SET reserved_at = :now, attempts = attempts + 1
+ WHERE id = (
+ SELECT id FROM {$this->jobsTable}
+ WHERE queue = :queue AND available_at <= :now AND reserved_at IS NULL
+ ORDER BY available_at ASC
+ FOR UPDATE SKIP LOCKED
+ LIMIT 1
+ )
+ RETURNING " . self::ROW_COLUMNS,
+ ['now' => $now, 'queue' => $queue]
+ );
+ $rows = $this->db->fetchAll($stmt);
+
+ return $rows ? $this->normalize($rows[0]) : null;
+
+ case 'mysql':
+ if ($this->supportsSkipLocked()) {
+ //transactional SELECT ... FOR UPDATE SKIP LOCKED skips jobs locked by other workers
+ $this->db->query('START TRANSACTION');
+
+ try {
+ $stmt = $this->db->execute(
+ "SELECT id FROM {$this->jobsTable}
+ WHERE queue = :queue AND available_at <= :now AND reserved_at IS NULL
+ ORDER BY available_at ASC
+ LIMIT 1 FOR UPDATE SKIP LOCKED",
+ ['now' => $now, 'queue' => $queue]
+ );
+ $rows = $this->db->fetchAll($stmt);
+
+ if (!$rows) {
+ $this->db->query('COMMIT');
+
+ return null;
+ }
+
+ $numericId = (int)$rows[0]['id'];
+
+ $this->db->execute(
+ "UPDATE {$this->jobsTable} SET reserved_at = :now, attempts = attempts + 1 WHERE id = :nid",
+ ['now' => $now, 'nid' => $numericId]
+ );
+
+ $this->db->query('COMMIT');
+
+ return $this->fetchRowById($numericId);
+ } catch (\Throwable $e) {
+ try {
+ $this->db->query('ROLLBACK');
+ } catch (\Throwable $ignored) {
+ }
+
+ throw $e;
+ }
+ }
+
+ //older servers: single-statement atomic claim, LAST_INSERT_ID(id) reads back the claimed row
+ $this->db->execute(
+ "UPDATE {$this->jobsTable} SET reserved_at = :now, attempts = attempts + 1, id = LAST_INSERT_ID(id)
+ WHERE queue = :queue AND available_at <= :now AND reserved_at IS NULL
+ ORDER BY available_at ASC
+ LIMIT 1",
+ ['now' => $now, 'queue' => $queue]
+ );
+
+ if (!$this->db->affected_rows || !$this->db->insert_id) {
+ return null;
+ }
+
+ return $this->fetchRowById((int)$this->db->insert_id);
+
+ case 'sqlite':
+ default:
+ //no row locks — serialize workers with an IMMEDIATE transaction
+ $this->db->query('BEGIN IMMEDIATE');
+
+ try {
+ $stmt = $this->db->execute(
+ "SELECT id FROM {$this->jobsTable}
+ WHERE queue = :queue AND available_at <= :now AND reserved_at IS NULL
+ ORDER BY available_at ASC
+ LIMIT 1",
+ ['now' => $now, 'queue' => $queue]
+ );
+ $rows = $this->db->fetchAll($stmt);
+
+ if (!$rows) {
+ $this->db->query('COMMIT');
+
+ return null;
+ }
+
+ $numericId = (int)$rows[0]['id'];
+
+ $this->db->execute(
+ "UPDATE {$this->jobsTable} SET reserved_at = :now, attempts = attempts + 1 WHERE id = :nid",
+ ['now' => $now, 'nid' => $numericId]
+ );
+
+ $stmt = $this->db->execute(
+ 'SELECT ' . self::ROW_COLUMNS . " FROM {$this->jobsTable} WHERE id = :nid",
+ ['nid' => $numericId]
+ );
+ $rows = $this->db->fetchAll($stmt);
+
+ $this->db->query('COMMIT');
+
+ return $rows ? $this->normalize($rows[0]) : null;
+ } catch (\Throwable $e) {
+ try {
+ $this->db->query('ROLLBACK');
+ } catch (\Throwable $ignored) {
+ }
+
+ throw $e;
+ }
+ }
+ }
+
+ /**
+ * Remove a completed job.
+ *
+ * @param string $jobId Job id.
+ *
+ * @return void
+ */
+ public function complete(string $jobId): void {
+ $this->db->execute(
+ "DELETE FROM {$this->jobsTable} WHERE job_id = :id",
+ ['id' => $jobId]
+ );
+ }
+
+ /**
+ * Return a job to the queue after an optional delay.
+ *
+ * @param string $jobId Job id.
+ * @param int $delaySeconds Delay before job becomes available again.
+ *
+ * @return void
+ */
+ public function release(string $jobId, int $delaySeconds = 0): void {
+ $this->db->execute(
+ "UPDATE {$this->jobsTable} SET reserved_at = NULL, available_at = :available_at WHERE job_id = :id",
+ ['available_at' => time() + max(0, $delaySeconds), 'id' => $jobId]
+ );
+ }
+
+ /**
+ * Handle failure: release with exponential backoff while retries remain,
+ * otherwise move to the failed store.
+ *
+ * @param string $jobId Job id.
+ * @param string $error Error message.
+ *
+ * @return bool True when moved to failed store, false when released for retry.
+ */
+ public function fail(string $jobId, string $error): bool {
+ $stmt = $this->db->execute(
+ "SELECT job_id, queue, job, payload, attempts, max_attempts FROM {$this->jobsTable} WHERE job_id = :id",
+ ['id' => $jobId]
+ );
+ $rows = $this->db->fetchAll($stmt);
+
+ if (!$rows) {
+ return false; //already gone
+ }
+
+ $row = $this->normalize($rows[0]);
+
+ if ($row['attempts'] < $row['max_attempts']) {
+ $this->release($jobId, $this->backoffDelay($row['attempts']));
+
+ return false;
+ }
+
+ //exhausted — move to failed store
+ $this->db->execute(
+ "INSERT INTO {$this->failedTable} (job_id, queue, job, payload, error, attempts, max_attempts, failed_at)
+ VALUES (:id, :queue, :job, :payload, :error, :attempts, :max_attempts, :failed_at)",
+ [
+ 'id' => $row['id'],
+ 'queue' => $row['queue'],
+ 'job' => $row['job'],
+ 'payload' => json_encode($row['payload']),
+ 'error' => mb_substr($error, 0, 65535),
+ 'attempts' => $row['attempts'],
+ 'max_attempts' => $row['max_attempts'],
+ 'failed_at' => time(),
+ ]
+ );
+
+ $this->complete($jobId);
+
+ return true;
+ }
+
+ /**
+ * Pending (ready + delayed + reserved) job count on a queue.
+ *
+ * @param string $queue Queue name.
+ *
+ * @return int
+ */
+ public function size(string $queue): int {
+ $this->ensureSchema();
+
+ $stmt = $this->db->execute(
+ "SELECT COUNT(*) AS cnt FROM {$this->jobsTable} WHERE queue = :queue",
+ ['queue' => $queue]
+ );
+ $rows = $this->db->fetchAll($stmt);
+
+ return (int)($rows[0]['cnt'] ?? 0);
+ }
+
+ /**
+ * Per-queue counters for monitoring.
+ *
+ * @param string $queue Queue name.
+ *
+ * @return array{ready: int, delayed: int, reserved: int}
+ */
+ public function stats(string $queue): array {
+ $this->ensureSchema();
+ $now = time();
+
+ $stmt = $this->db->execute(
+ "SELECT
+ SUM(CASE WHEN reserved_at IS NULL AND available_at <= :now THEN 1 ELSE 0 END) AS ready_cnt,
+ SUM(CASE WHEN reserved_at IS NULL AND available_at > :now THEN 1 ELSE 0 END) AS delayed_cnt,
+ SUM(CASE WHEN reserved_at IS NOT NULL THEN 1 ELSE 0 END) AS reserved_cnt
+ FROM {$this->jobsTable} WHERE queue = :queue",
+ ['now' => $now, 'queue' => $queue]
+ );
+ $rows = $this->db->fetchAll($stmt);
+ $row = $rows[0] ?? [];
+
+ return [
+ 'ready' => (int)($row['ready_cnt'] ?? 0),
+ 'delayed' => (int)($row['delayed_cnt'] ?? 0),
+ 'reserved' => (int)($row['reserved_cnt'] ?? 0),
+ ];
+ }
+
+ /**
+ * Requeue jobs claimed by crashed workers.
+ *
+ * @param int $reservedTimeoutSeconds Age threshold in seconds.
+ *
+ * @return int Number of requeued jobs.
+ */
+ public function requeueStalled(int $reservedTimeoutSeconds): int {
+ $this->db->execute(
+ "UPDATE {$this->jobsTable} SET reserved_at = NULL WHERE reserved_at IS NOT NULL AND reserved_at <= :cutoff",
+ ['cutoff' => time() - max(1, $reservedTimeoutSeconds)]
+ );
+
+ return (int)$this->db->affected_rows;
+ }
+
+ // ── Failed jobs ────────────────────────────────────────────────────
+
+ /**
+ * List failed jobs, newest first.
+ *
+ * @param string|null $queue Filter by queue.
+ * @param int $limit Max rows.
+ *
+ * @return list<array<array-key, mixed>>
+ */
+ public function getFailed(?string $queue = null, int $limit = 100): array {
+ $this->ensureSchema();
+
+ $params = ['limit' => $limit];
+ $where = '';
+
+ if ($queue) {
+ $where = 'WHERE queue = :queue';
+ $params['queue'] = $queue;
+ }
+
+ $stmt = $this->db->execute(
+ "SELECT job_id, queue, job, payload, error, attempts, max_attempts, failed_at
+ FROM {$this->failedTable} $where ORDER BY failed_at DESC LIMIT :limit",
+ $params
+ );
+ $rows = $this->db->fetchAll($stmt);
+
+ foreach ($rows as &$row) {
+ $row['id'] = $row['job_id'];
+ $row['payload'] = json_decode($row['payload'] ?? '[]', true);
+ $row['attempts'] = (int)$row['attempts'];
+ $row['failed_at'] = (int)$row['failed_at'];
+ }
+
+ return $rows;
+ }
+
+ /**
+ * Move a failed job back into the queue with attempts reset.
+ *
+ * @param string $jobId Job id.
+ *
+ * @return bool
+ */
+ public function retryFailed(string $jobId): bool {
+ $this->ensureSchema();
+
+ $stmt = $this->db->execute(
+ "SELECT job_id, queue, job, payload, attempts, max_attempts, failed_at FROM {$this->failedTable} WHERE job_id = :id",
+ ['id' => $jobId]
+ );
+ $rows = $this->db->fetchAll($stmt);
+
+ if (!$rows) {
+ return false;
+ }
+
+ $row = $rows[0];
+
+ $this->push(
+ $row['queue'],
+ [
+ 'id' => $row['job_id'],
+ 'queue' => $row['queue'],
+ 'job' => $row['job'],
+ 'payload' => json_decode($row['payload'] ?? '[]', true),
+ 'attempts' => 0,
+ 'max_attempts' => (int)$row['max_attempts'],
+ 'available_at' => time(),
+ 'created_at' => (int)$row['failed_at'],
+ ]
+ );
+
+ return $this->deleteFailed($jobId);
+ }
+
+ /**
+ * Delete a single failed job.
+ *
+ * @param string $jobId Job id.
+ *
+ * @return bool
+ */
+ public function deleteFailed(string $jobId): bool {
+ $this->db->execute(
+ "DELETE FROM {$this->failedTable} WHERE job_id = :id",
+ ['id' => $jobId]
+ );
+
+ return (int)$this->db->affected_rows > 0;
+ }
+
+ /**
+ * Delete all failed jobs, optionally filtered by queue.
+ *
+ * @param string|null $queue Filter by queue.
+ *
+ * @return int Deleted count.
+ */
+ public function clearFailed(?string $queue = null): int {
+ if ($queue) {
+ $this->db->execute(
+ "DELETE FROM {$this->failedTable} WHERE queue = :queue",
+ ['queue' => $queue]
+ );
+ } else {
+ $this->db->execute("DELETE FROM {$this->failedTable}");
+ }
+
+ return (int)$this->db->affected_rows;
+ }
+}
diff --git a/system/queue/providers/provider.php b/system/queue/providers/provider.php
new file mode 100755
index 0000000..cfd82e4
--- /dev/null
+++ b/system/queue/providers/provider.php
@@ -0,0 +1,162 @@
+<?php
+
+/**
+ * Vvveb
+ *
+ * Copyright (C) 2022 Ziadin Givan
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace Vvveb\System\Queue\Providers;
+
+/**
+ * Interface that all queue providers must implement.
+ *
+ * A provider is a storage backend holding jobs for one or more named queues:
+ * Redis (lists + sorted sets) or SQL database (PostgreSQL / MySQL / MariaDB / SQLite).
+ * Plugins can register additional backends (Beanstalkd, SQS ...) via the
+ * 'Vvveb\System\Queue\Providers', 'register' event, same as payment/notification providers.
+ */
+interface Provider {
+ /**
+ * Push a job record onto a queue.
+ *
+ * The job record contains at least: id, queue, job, payload, attempts,
+ * max_attempts, available_at, reserved_at (null), created_at.
+ *
+ * @param string $queue Queue name.
+ * @param array<array-key, mixed> $job Job record.
+ *
+ * @return string Job id.
+ */
+ public function push(string $queue, array $job): string;
+
+ /**
+ * Atomically claim and return the next available job on a queue.
+ *
+ * The claim marks the job as reserved so concurrent workers never grab
+ * the same job. Attempts counter is incremented on claim.
+ *
+ * @param string $queue Queue name.
+ *
+ * @return array<array-key, mixed>|null Job record or null when the queue is empty.
+ */
+ public function pop(string $queue): ?array;
+
+ /**
+ * Remove/acknowledge a completed job.
+ *
+ * @param string $jobId Job id.
+ *
+ * @return void
+ */
+ public function complete(string $jobId): void;
+
+ /**
+ * Return a job to the queue after an optional delay in seconds
+ * (used for retries and stalled-job requeue).
+ *
+ * @param string $jobId Job id.
+ * @param int $delaySeconds Delay before the job becomes available again.
+ *
+ * @return void
+ */
+ public function release(string $jobId, int $delaySeconds = 0): void;
+
+ /**
+ * Handle a failed attempt: re-queue with exponential backoff if retries
+ * remain, otherwise move the job to the failed store.
+ *
+ * @param string $jobId Job id.
+ * @param string $error Error message.
+ *
+ * @return bool True when the job was moved to the failed store (no retries left),
+ * false when it was released back to the queue for another retry.
+ */
+ public function fail(string $jobId, string $error): bool;
+
+ /**
+ * Number of pending jobs (ready + delayed) on a queue, for admin/monitoring.
+ *
+ * @param string $queue Queue name.
+ *
+ * @return int
+ */
+ public function size(string $queue): int;
+}
+
+/**
+ * Extended admin/monitoring API.
+ *
+ * Built-in providers implement this; plugins registering custom backends are
+ * encouraged to implement it too so the admin monitoring page works fully.
+ */
+interface FailedJobsAware {
+ /**
+ * List failed jobs, newest first.
+ *
+ * @param string|null $queue Filter by queue name.
+ * @param int $limit Max rows.
+ *
+ * @return list<array<array-key, mixed>> Failed job records (+ error, failed_at).
+ */
+ public function getFailed(?string $queue = null, int $limit = 100): array;
+
+ /**
+ * Retry a failed job: move it back to the queue with attempts reset.
+ *
+ * @param string $jobId Job id.
+ *
+ * @return bool True on success.
+ */
+ public function retryFailed(string $jobId): bool;
+
+ /**
+ * Delete a single failed job.
+ *
+ * @param string $jobId Job id.
+ *
+ * @return bool True on success.
+ */
+ public function deleteFailed(string $jobId): bool;
+
+ /**
+ * Delete all failed jobs, optionally filtered by queue.
+ *
+ * @param string|null $queue Filter by queue name.
+ *
+ * @return int Number of deleted jobs.
+ */
+ public function clearFailed(?string $queue = null): int;
+
+ /**
+ * Requeue jobs claimed by crashed workers (reserved longer than timeout).
+ *
+ * @param int $reservedTimeoutSeconds Age threshold in seconds.
+ *
+ * @return int Number of requeued jobs.
+ */
+ public function requeueStalled(int $reservedTimeoutSeconds): int;
+
+ /**
+ * Per-queue counters for the monitoring page.
+ *
+ * @param string $queue Queue name.
+ *
+ * @return array{ready: int, delayed: int, reserved: int}
+ */
+ public function stats(string $queue): array;
+}
diff --git a/system/queue/providers/redis.php b/system/queue/providers/redis.php
new file mode 100755
index 0000000..a80f2b8
--- /dev/null
+++ b/system/queue/providers/redis.php
@@ -0,0 +1,548 @@
+<?php
+
+/**
+ * Vvveb
+ *
+ * Copyright (C) 2022 Ziadin Givan
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace Vvveb\System\Queue\Providers;
+
+use function Vvveb\config;
+
+/**
+ * Redis queue provider — reliable-queue pattern.
+ *
+ * Keys per queue (all prefixed):
+ * {prefix}queue:{name} list — ready jobs (JSON records)
+ * {prefix}queue:{name}:delayed zset — scheduled jobs scored by available_at
+ * {prefix}queue:{name}:reserved list — jobs claimed by workers (in flight)
+ * {prefix}queue:{name}:failed hash — permanently failed jobs keyed by job id
+ *
+ * pop() first migrates due delayed jobs into the ready list (atomic Lua script),
+ * then atomically moves a job from ready to reserved with RPOPLPUSH so a crashed
+ * worker never loses its claimed job — stalled reservations are requeued by
+ * requeueStalled() based on the record's reserved_at age.
+ */
+class Redis extends Base implements FailedJobsAware {
+ public const DUE_LIMIT = 100;
+
+ /** @var \Redis Connection instance. */
+ protected \Redis $redis;
+
+ /** @var string Key prefix. */
+ protected string $prefix = 'vvveb.queue:';
+
+ /** @var array<string, string> Claimed raw payloads by job id (for LREM on complete/fail). */
+ protected array $reservedMap = [];
+
+ /**
+ * @param array<string, mixed> $options host, port, password, database, prefix, retry.
+ */
+ public function __construct(array $options = []) {
+ if (!class_exists('\Redis')) {
+ throw new \Exception('The phpredis extension is required for the Redis queue provider!');
+ }
+
+ //share connection settings with the cache driver when not explicitly configured
+ if (empty($options['host'])) {
+ $cacheConfig = config('app.cache', []);
+ $isRedis = ($cacheConfig['driver'] ?? '') === 'redis';
+ $options['host'] = $isRedis ? ($cacheConfig['host'] ?? '127.0.0.1') : '127.0.0.1';
+ $options['port'] = (int)($options['port'] ?? ($isRedis ? ($cacheConfig['port'] ?? 6379) : 6379));
+ $options['password'] = $options['password'] ?? ($isRedis ? ($cacheConfig['password'] ?? null) : null);
+ }
+
+ parent::__construct($options);
+
+ $this->prefix = $this->options['prefix'] ?? $this->prefix;
+
+ $this->redis = new \Redis();
+ $this->redis->pconnect((string)$this->options['host'], (int)($this->options['port'] ?? 6379));
+
+ if (!empty($this->options['password'])) {
+ $this->redis->auth($this->options['password']);
+ }
+
+ if (isset($this->options['database'])) {
+ $this->redis->select((int)$this->options['database']);
+ }
+ }
+
+ /**
+ * Build a key for a queue: {prefix}{name}[:{suffix}].
+ *
+ * @param string $queue Queue name.
+ * @param string $suffix Optional suffix ('delayed', 'reserved', 'failed').
+ *
+ * @return string
+ */
+ protected function key(string $queue, string $suffix = ''): string {
+ return $this->prefix . $queue . ($suffix ? ":$suffix" : '');
+ }
+
+ /**
+ * Move due delayed jobs into the ready list (atomic Lua script).
+ * Called at the start of every pop() — lightweight scheduler step.
+ *
+ * @param string $queue Queue name.
+ *
+ * @return int Number of migrated jobs.
+ */
+ protected function migrateDue(string $queue): int {
+ $script = <<<'LUA'
+ local jobs = redis.call('ZRANGEBYSCORE', KEYS[1], '-inf', ARGV[1], 'LIMIT', 0, ARGV[2])
+ local n = 0
+ for _, job in ipairs(jobs) do
+ redis.call('ZREM', KEYS[1], job)
+ redis.call('LPUSH', KEYS[2], job)
+ n = n + 1
+ end
+ return n
+ LUA;
+
+ try {
+ return (int)$this->redis->eval($script, [$this->key($queue, 'delayed'), $this->key($queue), (string)time(), self::DUE_LIMIT], 2);
+ } catch (\Throwable $e) {
+ //fallback without Lua (non-atomic but safe enough for low concurrency)
+ $jobs = $this->redis->zRangeByScore($this->key($queue, 'delayed'), '-inf', (string)time(), ['limit' => [0, self::DUE_LIMIT]]);
+ $n = 0;
+
+ foreach ($jobs as $job) {
+ if ($this->redis->zRem($this->key($queue, 'delayed'), $job) && $this->redis->lPush($this->key($queue), $job)) {
+ $n++;
+ }
+ }
+
+ return $n;
+ }
+ }
+
+ /**
+ * Push a raw JSON record to ready/delayed depending on availability.
+ *
+ * @param string $queue Queue name.
+ * @param array<array-key, mixed> $job Job record.
+ *
+ * @return void
+ */
+ protected function pushRaw(string $queue, array $job): void {
+ $json = json_encode($job);
+ $availableAt = (int)($job['available_at'] ?? time());
+
+ if ($availableAt <= time()) {
+ $this->redis->lPush($this->key($queue), $json);
+ } else {
+ $this->redis->zAdd($this->key($queue, 'delayed'), $availableAt, $json);
+ }
+ }
+
+ /**
+ * Find the raw payload stored in the reserved list for a claimed job id.
+ *
+ * @param string $jobId Job id.
+ * @param string|null $queue Queue name hint (scans all queues when null).
+ *
+ * @return string|null Raw JSON payload.
+ */
+ protected function findReservedRaw(string $jobId, ?string $queue = null): ?string {
+ if (isset($this->reservedMap[$jobId])) {
+ return $this->reservedMap[$jobId];
+ }
+
+ if ($queue) {
+ $key = $this->key($queue, 'reserved');
+ $len = $this->redis->lLen($key);
+
+ for ($i = 0; $i < min(1000, $len); $i++) {
+ $raw = $this->redis->lIndex($key, $i);
+
+ if (!$raw) {
+ continue;
+ }
+
+ $job = json_decode($raw, true);
+
+ if (($job['id'] ?? null) === $jobId) {
+ return $raw;
+ }
+ }
+ }
+
+ return null;
+ }
+
+ /**
+ * Remove a raw payload from a queue's reserved list.
+ *
+ * @param string $queue Queue name.
+ * @param string $raw Raw JSON payload.
+ *
+ * @return void
+ */
+ protected function removeReservedRaw(string $queue, string $raw): void {
+ $this->redis->lRem($this->key($queue, 'reserved'), $raw, 1);
+ }
+
+ /**
+ * @param string $queue Queue name.
+ * @param array<array-key, mixed> $job Job record.
+ *
+ * @return string Job id.
+ */
+ public function push(string $queue, array $job): string {
+ $this->pushRaw($queue, $job);
+
+ return (string)$job['id'];
+ }
+
+ /**
+ * Atomically claim and return the next available job.
+ *
+ * @param string $queue Queue name.
+ *
+ * @return array<array-key, mixed>|null
+ */
+ public function pop(string $queue): ?array {
+ $this->migrateDue($queue);
+
+ $readyKey = $this->key($queue);
+ $reservedKey = $this->key($queue, 'reserved');
+
+ $raw = $this->redis->rPopLPush($readyKey, $reservedKey);
+
+ if (!$raw) {
+ return null;
+ }
+
+ $job = json_decode($raw, true);
+
+ if (!is_array($job)) {
+ //corrupt record — drop it from reserved so it doesn't loop forever
+ $this->removeReservedRaw($queue, $raw);
+
+ return null;
+ }
+
+ //mark claim: bump attempts + stamp reserved_at, replace record in reserved list
+ $job['attempts'] = (int)($job['attempts'] ?? 0) + 1;
+ $job['reserved_at'] = time();
+ $newRaw = json_encode($job);
+
+ $this->removeReservedRaw($queue, $raw);
+ $this->redis->lPush($reservedKey, $newRaw);
+
+ $this->reservedMap[(string)$job['id']] = $newRaw;
+
+ return $this->normalize($job);
+ }
+
+ /**
+ * Acknowledge a completed job.
+ *
+ * @param string $jobId Job id.
+ *
+ * @return void
+ */
+ public function complete(string $jobId): void {
+ $raw = $this->findReservedRaw($jobId);
+
+ if ($raw !== null) {
+ $job = json_decode($raw, true);
+ $this->removeReservedRaw($job['queue'] ?? 'default', $raw);
+ unset($this->reservedMap[$jobId]);
+ }
+ }
+
+ /**
+ * Return a job to the queue after an optional delay.
+ *
+ * @param string $jobId Job id.
+ * @param int $delaySeconds Delay before job becomes available again.
+ *
+ * @return void
+ */
+ public function release(string $jobId, int $delaySeconds = 0): void {
+ $raw = $this->findReservedRaw($jobId);
+
+ if ($raw === null) {
+ return;
+ }
+
+ $job = json_decode($raw, true);
+ $queue = $job['queue'] ?? 'default';
+ $job['reserved_at'] = null;
+ $job['available_at'] = time() + max(0, $delaySeconds);
+
+ $this->removeReservedRaw($queue, $raw);
+ unset($this->reservedMap[$jobId]);
+
+ $this->pushRaw($queue, $job);
+ }
+
+ /**
+ * Handle failure: release with exponential backoff while retries remain,
+ * otherwise move to the failed hash.
+ *
+ * @param string $jobId Job id.
+ * @param string $error Error message.
+ *
+ * @return bool True when moved to failed store, false when released for retry.
+ */
+ public function fail(string $jobId, string $error): bool {
+ $raw = $this->findReservedRaw($jobId);
+
+ if ($raw === null) {
+ return false;
+ }
+
+ $job = json_decode($raw, true);
+ $queue = $job['queue'] ?? 'default';
+
+ $this->removeReservedRaw($queue, $raw);
+ unset($this->reservedMap[$jobId]);
+
+ if ((int)($job['attempts'] ?? 0) < (int)($job['max_attempts'] ?? 3)) {
+ $job['available_at'] = time() + $this->backoffDelay((int)$job['attempts']);
+ $this->pushRaw($queue, $job);
+
+ return false;
+ }
+
+ $job['error'] = mb_substr($error, 0, 65535);
+ $job['failed_at'] = time();
+
+ $this->redis->hSet($this->key($queue, 'failed'), $jobId, json_encode($job));
+
+ return true;
+ }
+
+ /**
+ * Pending (ready + delayed) job count on a queue.
+ *
+ * @param string $queue Queue name.
+ *
+ * @return int
+ */
+ public function size(string $queue): int {
+ return (int)$this->redis->lLen($this->key($queue)) + (int)$this->redis->zCard($this->key($queue, 'delayed'));
+ }
+
+ /**
+ * Per-queue counters for monitoring.
+ *
+ * @param string $queue Queue name.
+ *
+ * @return array{ready: int, delayed: int, reserved: int}
+ */
+ public function stats(string $queue): array {
+ return [
+ 'ready' => (int)$this->redis->lLen($this->key($queue)),
+ 'delayed' => (int)$this->redis->zCard($this->key($queue, 'delayed')),
+ 'reserved' => (int)$this->redis->lLen($this->key($queue, 'reserved')),
+ ];
+ }
+
+ /**
+ * Requeue jobs claimed by crashed workers (reserved_at older than timeout).
+ *
+ * @param int $reservedTimeoutSeconds Age threshold in seconds.
+ *
+ * @return int Number of requeued jobs.
+ */
+ public function requeueStalled(int $reservedTimeoutSeconds): int {
+ $cutoff = time() - max(1, $reservedTimeoutSeconds);
+ $count = 0;
+
+ //scan every known queue's reserved list
+ $iterator = null;
+ $pattern = $this->prefix . '*:reserved';
+
+ while ($keys = $this->redis->scan($iterator, $pattern)) {
+ foreach ($keys as $key) {
+ $len = (int)$this->redis->lLen($key);
+
+ for ($i = 0; $i < min(1000, $len); $i++) {
+ $raw = $this->redis->lIndex($key, $i);
+
+ if (!$raw) {
+ continue;
+ }
+
+ $job = json_decode($raw, true);
+
+ if (!is_array($job) || empty($job['reserved_at']) || $job['reserved_at'] > $cutoff) {
+ continue;
+ }
+
+ $queue = $job['queue'] ?? 'default';
+ $job['reserved_at'] = null;
+ $job['available_at'] = time();
+
+ $this->redis->lRem($key, $raw, 1);
+ $this->pushRaw($queue, $job);
+ $count++;
+ }
+ }
+ }
+
+ return $count;
+ }
+
+ // ── Failed jobs ────────────────────────────────────────────────────
+
+ /**
+ * List failed jobs, newest first.
+ *
+ * @param string|null $queue Filter by queue.
+ * @param int $limit Max rows.
+ *
+ * @return list<array<array-key, mixed>>
+ */
+ public function getFailed(?string $queue = null, int $limit = 100): array {
+ $result = [];
+
+ if ($queue) {
+ $keys = [$queue => $this->key($queue, 'failed')];
+ } else {
+ $keys = [];
+
+ $iterator = null;
+ $pattern = $this->prefix . '*:failed';
+
+ while ($found = $this->redis->scan($iterator, $pattern)) {
+ foreach ($found as $key) {
+ $name = str_replace([$this->prefix, ':failed'], '', $key);
+ $keys[$name] = $key;
+ }
+ }
+ }
+
+ foreach ($keys as $name => $key) {
+ $jobs = $this->redis->hGetAll($key) ?: [];
+
+ foreach ($jobs as $raw) {
+ $job = json_decode($raw, true);
+
+ if (is_array($job)) {
+ $job['queue'] = $name;
+ $result[] = $job;
+ }
+ }
+ }
+
+ usort($result, fn ($a, $b) => (int)($b['failed_at'] ?? 0) <=> (int)($a['failed_at'] ?? 0));
+
+ return array_slice($result, 0, $limit);
+ }
+
+ /**
+ * Move a failed job back into the queue with attempts reset.
+ *
+ * @param string $jobId Job id.
+ *
+ * @return bool
+ */
+ public function retryFailed(string $jobId): bool {
+ $raw = null;
+ $queueName = null;
+
+ $iterator = null;
+ $pattern = $this->prefix . '*:failed';
+
+ while ($found = $this->redis->scan($iterator, $pattern)) {
+ foreach ($found as $key) {
+ $raw = $this->redis->hGet($key, $jobId);
+
+ if ($raw) {
+ $queueName = str_replace([$this->prefix, ':failed'], '', $key);
+
+ break 2;
+ }
+ }
+ }
+
+ if (!$raw || !$queueName) {
+ return false;
+ }
+
+ $job = json_decode($raw, true);
+
+ $this->redis->hDel($this->key($queueName, 'failed'), $jobId);
+
+ $job['attempts'] = 0;
+ $job['available_at'] = time();
+ unset($job['error'], $job['failed_at']);
+
+ $this->pushRaw($queueName, $job);
+
+ return true;
+ }
+
+ /**
+ * Delete a single failed job.
+ *
+ * @param string $jobId Job id.
+ *
+ * @return bool
+ */
+ public function deleteFailed(string $jobId): bool {
+ $deleted = 0;
+
+ $iterator = null;
+ $pattern = $this->prefix . '*:failed';
+
+ while ($found = $this->redis->scan($iterator, $pattern)) {
+ foreach ($found as $key) {
+ $deleted += (int)$this->redis->hDel($key, $jobId);
+ }
+ }
+
+ return $deleted > 0;
+ }
+
+ /**
+ * Delete all failed jobs, optionally filtered by queue.
+ *
+ * @param string|null $queue Filter by queue.
+ *
+ * @return int Deleted count.
+ */
+ public function clearFailed(?string $queue = null): int {
+ if ($queue) {
+ $key = $this->key($queue, 'failed');
+ $cnt = (int)$this->redis->hLen($key);
+ $this->redis->del($key);
+
+ return $cnt;
+ }
+
+ $total = 0;
+
+ $iterator = null;
+ $pattern = $this->prefix . '*:failed';
+
+ while ($found = $this->redis->scan($iterator, $pattern)) {
+ foreach ($found as $key) {
+ $total += (int)$this->redis->hLen($key);
+ $this->redis->del($key);
+ }
+ }
+
+ return $total;
+ }
+}