FacturaScripts

DbQuery
in package

Application

FinalYes

Query builder fluido para construir y ejecutar consultas SQL contra la base de datos.

Ofrece una API encadenable al estilo de Laravel/Eloquent: se parte de DbQuery::table('tabla') y se van añadiendo cláusulas (select, where*, orderBy, groupBy, limit, ...) hasta ejecutar la consulta con un método terminal (get, first, count, sum, delete, insert, update, etc.). Internamente comparte una conexión perezosa singleton (self::db()).

Los nombres de columnas y tablas se escapan con escapeColumn() y los valores con var2str(), así que las APIs estándar son seguras frente a inyección. La excepción es selectRaw() y la cláusula having(), que aceptan SQL en bruto: el llamador es responsable de no concatenar ahí datos no confiables.

También expone helpers dinámicos where{Campo}($valor) (vía __call) que se traducen a whereEq con el nombre de campo en minúsculas.

Properties

$fields : mixed: Lista de campos del SELECT (ya escapados o en bruto si vinieron de selectRaw).
$groupBy : mixed: Cláusula GROUP BY ya construida (campos escapados separados por coma).
$having : mixed: Cláusula HAVING en bruto.
$limit : mixed: Límite de filas. 0 significa sin límite.
$offset : mixed: Desplazamiento de filas para paginación.
$orderBy : mixed: Lista de fragmentos `campo ASC|DESC` ya construidos para el ORDER BY.
$db : mixed: Conexión compartida perezosa para todas las instancias del builder.
$table : mixed: Nombre de la tabla destino, sin escapar.
$where : mixed: Cláusulas WHERE acumuladas, combinadas con AND al construir el SQL.

Methods

__call() : mixed: Soporta llamadas dinámicas del tipo `whereCampo($valor)` traduciéndolas a `whereEq('campo', $valor)`.
__construct() : mixed: Inicia una consulta sobre la tabla indicada; usar preferentemente el factory `DbQuery::table()`.
array() : array<string|int, mixed>: Ejecuta la consulta y devuelve un array asociativo donde cada fila aporta una pareja `$key => $value`.
avg() : float: Devuelve la media de `$field`, opcionalmente redondeada a `$decimals` decimales.
avgArray() : array<string|int, mixed>: Devuelve la media de `$field` agrupada por `$groupByKey`, en formato `clave => media`.
count() : int: Cuenta filas según el modo elegido.
countArray() : array<string|int, mixed>: Devuelve el conteo de `$field` agrupado por `$groupByKey`, en formato `clave => count`.
delete() : bool: Ejecuta un DELETE sobre la tabla aplicando los `where*` acumulados.
first() : array<string|int, mixed>: Devuelve la primera fila resultante, o un array vacío si no hay coincidencias.
get() : array<string|int, mixed>: Ejecuta la consulta SELECT y devuelve todas las filas como arrays asociativos.
groupBy() : self: Define el GROUP BY a partir de una lista de campos separados por comas; cada campo se escapa por separado.
having() : self: Define la cláusula HAVING en bruto.
insert() : bool: Inserta una fila o un lote de filas en la tabla.
insertGetId() : int|null: Inserta y devuelve el último ID autoincremental generado, o null si la inserción falla.
limit() : self: Establece el LIMIT de la consulta; 0 significa sin límite.
max() : float: Devuelve el valor MAX de `$field` como float, opcionalmente redondeado a `$decimals` decimales.
maxArray() : array<string|int, mixed>: Devuelve el MAX de `$field` agrupado por `$groupByKey`, en formato `clave => max`.
maxString() : string: Devuelve el valor MAX de `$field` como string, útil para columnas no numéricas (fechas, textos).
min() : float: Devuelve el valor MIN de `$field` como float, opcionalmente redondeado a `$decimals` decimales.
minArray() : array<string|int, mixed>: Devuelve el MIN de `$field` agrupado por `$groupByKey`, en formato `clave => min`.
minString() : string: Devuelve el valor MIN de `$field` como string, útil para columnas no numéricas.
offset() : self: Establece el OFFSET (número de filas a saltar) para paginación.
orderBy() : self: Añade una cláusula ORDER BY validando estrictamente la entrada para evitar inyección SQL.
orderByRandom() : self: Añade un ORDER BY aleatorio usando la función específica del motor de base de datos.
orderMulti() : self: Añade varias cláusulas ORDER BY a partir de un array `campo => orden`.
reorder() : self: Limpia el ORDER BY acumulado para empezar a definirlo de nuevo.
select() : self: Define la lista de campos del SELECT a partir de una cadena separada por comas; cada campo se escapa por separado.
selectRaw() : self: Define la lista de campos del SELECT en bruto, sin escapar.
sql() : string: Construye y devuelve la sentencia SELECT resultante (sin LIMIT/OFFSET, que se aplican al ejecutar).
sum() : float: Devuelve la suma de `$field`, opcionalmente redondeada a `$decimals` decimales.
sumArray() : array<string|int, mixed>: Devuelve la suma de `$field` agrupada por `$groupByKey`, en formato `clave => suma`.
table() : self: Factory recomendado: crea una nueva consulta sobre la tabla indicada.
update() : bool: Ejecuta un UPDATE sobre la tabla aplicando los `where*` acumulados.
where() : $this: Añade un conjunto de cláusulas WHERE preconstruidas.
whereBetween() : self: Añade una condición `field BETWEEN value1 AND value2`.
whereEq() : self: Añade una condición `field = value`. Equivalente al helper dinámico `where{Campo}($valor)`.
whereGt() : self: Añade una condición `field > value`.
whereGte() : self: Añade una condición `field >= value`.
whereIn() : self: Añade una condición `field IN (values...)`.
whereLike() : self: Añade una condición `field LIKE value`. El llamador es quien añade los comodines `%` cuando los necesite.
whereLt() : self: Añade una condición `field < value`.
whereLte() : self: Añade una condición `field <= value`.
whereNotEq() : self: Añade una condición `field <> value`.
whereNotIn() : self: Añade una condición `field NOT IN (values...)`.
whereNotNull() : self: Añade una condición `field IS NOT NULL`.
whereNull() : self: Añade una condición `field IS NULL`.
db() : DataBase: Devuelve la conexión, abriéndola la primera vez (singleton perezoso compartido por todas las consultas).

$fields

Lista de campos del SELECT (ya escapados o en bruto si vinieron de selectRaw).


        public
            mixed
    $fields
     = '*'

@var string

$groupBy

Cláusula GROUP BY ya construida (campos escapados separados por coma).


        public
            mixed
    $groupBy

@var string

$having

Cláusula HAVING en bruto.


        public
            mixed
    $having

@var string

$limit

Límite de filas. 0 significa sin límite.


        public
            mixed
    $limit
     = 0

@var int

$offset

Desplazamiento de filas para paginación.


        public
            mixed
    $offset
     = 0

@var int

$orderBy

Lista de fragmentos `campo ASC|DESC` ya construidos para el ORDER BY.


        public
            mixed
    $orderBy
     = []

@var array

$db

Conexión compartida perezosa para todas las instancias del builder.


        private
        static    mixed
    $db

@var DataBase

$table

Nombre de la tabla destino, sin escapar.


        private
            mixed
    $table

@var string

$where

Cláusulas WHERE acumuladas, combinadas con AND al construir el SQL.


        private
            mixed
    $where
     = []

@var Where[]

__call()

Soporta llamadas dinámicas del tipo `whereCampo($valor)` traduciéndolas a `whereEq('campo', $valor)`.


    public
                    __call(mixed $method, mixed $parameters) : mixed

Cualquier otra llamada se delega al método correspondiente si existe; en caso contrario, se lanza una excepción para evitar fallos silenciosos.

Parameters

$method : mixed
$parameters : mixed

__construct()

Inicia una consulta sobre la tabla indicada; usar preferentemente el factory `DbQuery::table()`.


    public
                    __construct(string $table) : mixed

Parameters

$table : string

array()

Ejecuta la consulta y devuelve un array asociativo donde cada fila aporta una pareja `$key => $value`.


    public
                    array(string $key, string $value) : array<string|int, mixed>

Si dos filas comparten la misma $key, la última sobrescribe a las anteriores.

Parameters

$key : string
$value : string

Return values

array<string|int, mixed>

avg()

Devuelve la media de `$field`, opcionalmente redondeada a `$decimals` decimales.


    public
                    avg(string $field[, int|null $decimals = null ]) : float

Sustituye la cláusula SELECT por AVG(field), así que invalida cualquier select() previo.

Parameters

$field : string
$decimals : int|null = null

Return values

float

avgArray()

Devuelve la media de `$field` agrupada por `$groupByKey`, en formato `clave => media`.


    public
                    avgArray(string $field, string $groupByKey) : array<string|int, mixed>

Parameters

$field : string
$groupByKey : string

Return values

array<string|int, mixed>

count()

Cuenta filas según el modo elegido.


    public
                    count([string $field = '' ]) : int

Sin argumento y sin select() previo: COUNT(*).
Con $field: COUNT(DISTINCT field), útil para contar valores únicos de una columna.
Con select() previo: envuelve el SELECT existente en un COUNT(...).

Parameters

$field : string = ''

Return values

int

countArray()

Devuelve el conteo de `$field` agrupado por `$groupByKey`, en formato `clave => count`.


    public
                    countArray(string $field, string $groupByKey) : array<string|int, mixed>

Parameters

$field : string
$groupByKey : string

Return values

array<string|int, mixed>

delete()

Ejecuta un DELETE sobre la tabla aplicando los `where*` acumulados.


    public
                    delete() : bool

Importante: si no se han añadido cláusulas WHERE, se borra la tabla entera. La clase no impone una verificación adicional, así que el llamador debe asegurarse de añadir las condiciones que correspondan.

Return values

bool

first()

Devuelve la primera fila resultante, o un array vacío si no hay coincidencias.


    public
                    first() : array<string|int, mixed>

Internamente fuerza limit=1 y offset=0, sobrescribiendo cualquier valor previo.

Return values

array<string|int, mixed>

get()

Ejecuta la consulta SELECT y devuelve todas las filas como arrays asociativos.


    public
                    get() : array<string|int, mixed>

Return values

array<string|int, mixed>

groupBy()

Define el GROUP BY a partir de una lista de campos separados por comas; cada campo se escapa por separado.


    public
                    groupBy(string $fields) : self

Parameters

$fields : string

Return values

self

having()

Define la cláusula HAVING en bruto.


    public
                    having(string $having) : self

No se escapa: el llamador es responsable de no concatenar datos no confiables aquí.

Parameters

$having : string

Return values

self

insert()

Inserta una fila o un lote de filas en la tabla.


    public
                    insert(array<string|int, mixed> $data) : bool

Detecta automáticamente el modo: si el primer elemento de $data es a su vez un array, trata $data como una lista de filas y emite un INSERT múltiple usando los campos del primer registro como referencia (todas las filas deben tener las mismas claves). En caso contrario, hace un INSERT simple con el array recibido. Devuelve false si $data viene vacío.

Parameters

$data : array<string|int, mixed>

Return values

bool

insertGetId()

Inserta y devuelve el último ID autoincremental generado, o null si la inserción falla.


    public
                    insertGetId(array<string|int, mixed> $data) : int|null

Parameters

$data : array<string|int, mixed>

Return values

int|null

limit()

Establece el LIMIT de la consulta; 0 significa sin límite.


    public
                    limit(int $limit) : self

Parameters

$limit : int

Return values

self

max()

Devuelve el valor MAX de `$field` como float, opcionalmente redondeado a `$decimals` decimales.


    public
                    max(string $field[, int|null $decimals = null ]) : float

Parameters

$field : string
$decimals : int|null = null

Return values

float

maxArray()

Devuelve el MAX de `$field` agrupado por `$groupByKey`, en formato `clave => max`.


    public
                    maxArray(string $field, string $groupByKey) : array<string|int, mixed>

Parameters

$field : string
$groupByKey : string

Return values

array<string|int, mixed>

maxString()

Devuelve el valor MAX de `$field` como string, útil para columnas no numéricas (fechas, textos).


    public
                    maxString(string $field) : string

Parameters

$field : string

Return values

string

min()

Devuelve el valor MIN de `$field` como float, opcionalmente redondeado a `$decimals` decimales.


    public
                    min(string $field[, int|null $decimals = null ]) : float

Parameters

$field : string
$decimals : int|null = null

Return values

float

minArray()

Devuelve el MIN de `$field` agrupado por `$groupByKey`, en formato `clave => min`.


    public
                    minArray(string $field, string $groupByKey) : array<string|int, mixed>

Parameters

$field : string
$groupByKey : string

Return values

array<string|int, mixed>

minString()

Devuelve el valor MIN de `$field` como string, útil para columnas no numéricas.


    public
                    minString(string $field) : string

Parameters

$field : string

Return values

string

offset()

Establece el OFFSET (número de filas a saltar) para paginación.


    public
                    offset(int $offset) : self

Parameters

$offset : int

Return values

self

orderBy()

Añade una cláusula ORDER BY validando estrictamente la entrada para evitar inyección SQL.


    public
                    orderBy(string $field[, string $order = 'ASC' ]) : self

Aceptación de $order: cualquier valor distinto de 'DESC' (case-insensitive) cae en 'ASC'.

Aceptación de $field:

Expresión RAND() o RANDOM(): se sustituye por el operador aleatorio del motor.
Funciones LOWER(col), UPPER(col), CAST(col AS tipo) o COALESCE(col, valor) con patrones validados por regex; se aceptan tal cual.
Cualquier otro paréntesis se considera no permitido y se cae a la rama de escape simple.
Prefijos especiales integer:, lower: y upper: aplican el cast/función correspondiente.
Resto: se escapa con escapeColumn().

Parameters

$field : string
$order : string = 'ASC'

Return values

self

orderByRandom()

Añade un ORDER BY aleatorio usando la función específica del motor de base de datos.


    public
                    orderByRandom() : self

Return values

self

orderMulti()

Añade varias cláusulas ORDER BY a partir de un array `campo => orden`.


    public
                    orderMulti(array<string|int, mixed> $fields) : self

Parameters

$fields : array<string|int, mixed>

Return values

self

reorder()

Limpia el ORDER BY acumulado para empezar a definirlo de nuevo.


    public
                    reorder() : self

Return values

self

select()

Define la lista de campos del SELECT a partir de una cadena separada por comas; cada campo se escapa por separado.


    public
                    select(string $fields) : self

Parameters

$fields : string

Return values

self

selectRaw()

Define la lista de campos del SELECT en bruto, sin escapar.


    public
                    selectRaw(string $fields) : self

Pensado para expresiones complejas (subconsultas, funciones, alias). El llamador es responsable de no concatenar aquí entrada del usuario sin sanear.

Parameters

$fields : string

Return values

self

sql()

Construye y devuelve la sentencia SELECT resultante (sin LIMIT/OFFSET, que se aplican al ejecutar).


    public
                    sql() : string

Útil para inspeccionar la consulta, depurar o ejecutarla manualmente.

Return values

string

sum()

Devuelve la suma de `$field`, opcionalmente redondeada a `$decimals` decimales.


    public
                    sum(string $field[, int|null $decimals = null ]) : float

Parameters

$field : string
$decimals : int|null = null

Return values

float

sumArray()

Devuelve la suma de `$field` agrupada por `$groupByKey`, en formato `clave => suma`.


    public
                    sumArray(string $field, string $groupByKey) : array<string|int, mixed>

Parameters

$field : string
$groupByKey : string

Return values

array<string|int, mixed>

table()

Factory recomendado: crea una nueva consulta sobre la tabla indicada.


    public
            static        table(string $table) : self

Parameters

$table : string

Return values

self

update()

Ejecuta un UPDATE sobre la tabla aplicando los `where*` acumulados.


    public
                    update(array<string|int, mixed> $data) : bool

Devuelve false si $data viene vacío. Igual que delete(), si no hay cláusulas WHERE, el UPDATE afecta a todas las filas; el llamador es responsable de filtrar.

Parameters

$data : array<string|int, mixed>

Return values

bool

where()

Añade un conjunto de cláusulas WHERE preconstruidas.


    public
                    where(array<string|int, Where>|array<string|int, DataBaseWhere> $where) : $this

Acepta tanto instancias de Where (nuevo estilo) como de DataBaseWhere (legacy), para facilitar la migración progresiva. Cualquier otro valor lanza excepción.

Parameters

$where : array<string|int, Where>|array<string|int, DataBaseWhere>

Return values

$this

whereBetween()

Añade una condición `field BETWEEN value1 AND value2`.


    public
                    whereBetween(string $field, mixed $value1, mixed $value2) : self

Parameters

$field : string
$value1 : mixed
$value2 : mixed

Return values

self

whereEq()

Añade una condición `field = value`. Equivalente al helper dinámico `where{Campo}($valor)`.


    public
                    whereEq(string $field, mixed $value) : self

Parameters

$field : string
$value : mixed

Return values

self

whereGt()

Añade una condición `field > value`.


    public
                    whereGt(string $field, mixed $value) : self

Parameters

$field : string
$value : mixed

Return values

self

whereGte()

Añade una condición `field >= value`.


    public
                    whereGte(string $field, mixed $value) : self

Parameters

$field : string
$value : mixed

Return values

self

whereIn()

Añade una condición `field IN (values...)`.


    public
                    whereIn(string $field, array<string|int, mixed> $values) : self

Parameters

$field : string
$values : array<string|int, mixed>

Return values

self

whereLike()

Añade una condición `field LIKE value`. El llamador es quien añade los comodines `%` cuando los necesite.


    public
                    whereLike(string $field, string $value) : self

Parameters

$field : string
$value : string

Return values

self

whereLt()

Añade una condición `field < value`.


    public
                    whereLt(string $field, mixed $value) : self

Parameters

$field : string
$value : mixed

Return values

self

whereLte()

Añade una condición `field <= value`.


    public
                    whereLte(string $field, mixed $value) : self

Parameters

$field : string
$value : mixed

Return values

self

whereNotEq()

Añade una condición `field <> value`.


    public
                    whereNotEq(string $field, mixed $value) : self

Parameters

$field : string
$value : mixed

Return values

self

whereNotIn()

Añade una condición `field NOT IN (values...)`.


    public
                    whereNotIn(string $field, array<string|int, mixed> $values) : self

Parameters

$field : string
$values : array<string|int, mixed>

Return values

self

whereNotNull()

Añade una condición `field IS NOT NULL`.


    public
                    whereNotNull(string $field) : self

Parameters

$field : string

Return values

self

whereNull()

Añade una condición `field IS NULL`.


    public
                    whereNull(string $field) : self

Parameters

$field : string

Return values

self

db()

Devuelve la conexión, abriéndola la primera vez (singleton perezoso compartido por todas las consultas).


    private
            static        db() : DataBase

Return values

DataBase

DbQuery in package Application

Table of Contents

Properties

Methods

Properties

$fields

$groupBy

$having

$limit

$offset

$orderBy

$db

$table

$where

Methods

__call()

Parameters

__construct()

Parameters

array()

Parameters

Return values

avg()

Parameters

Return values

avgArray()

Parameters

Return values

count()

Parameters

Return values

countArray()

Parameters

Return values

delete()

Return values

first()

Return values

get()

Return values

groupBy()

Parameters

Return values

having()

Parameters

Return values

insert()

Parameters

Return values

insertGetId()

Parameters

Return values

limit()

Parameters

Return values

max()

Parameters

Return values

maxArray()

Parameters

Return values

maxString()

Parameters

Return values

min()

Parameters

Return values

minArray()

Parameters

Return values

minString()

Parameters

Return values

offset()

Parameters

Return values

orderBy()

Parameters

Return values

orderByRandom()

DbQuery
in package

Application