Salta ai contenuti
XOOPS 2.7 Docs

Query Builder XOOPS

Il Query Builder XOOPS fornisce un’interfaccia fluente e moderna per costruire query SQL. Aiuta a prevenire SQL injection, migliora la leggibilità e fornisce astrazione database per sistemi database multipli.

Architettura Query Builder

Sezione intitolata “Architettura Query Builder”
graph TD
    A[QueryBuilder] -->|builds| B[SELECT Queries]
    A -->|builds| C[INSERT Queries]
    A -->|builds| D[UPDATE Queries]
    A -->|builds| E[DELETE Queries]


    F[Table] -->|chains| G[select]
    F -->|chains| H[where]
    F -->|chains| I[orderBy]
    F -->|chains| J[limit]


    G -->|chains| K[join]
    G -->|chains| H
    H -->|chains| I
    I -->|chains| J


    L[Execute Methods] -->|returns| M[Results]
    L -->|returns| N[Count]
    L -->|returns| O[First/Last]

Classe QueryBuilder

Sezione intitolata “Classe QueryBuilder”

Classe principale query builder con interfaccia fluente.

Panoramica Classe

Sezione intitolata “Panoramica Classe”
namespace Xoops\Database;


class QueryBuilder
{
    protected string $table = '';
    protected string $type = 'SELECT';
    protected array $selects = [];
    protected array $joins = [];
    protected array $wheres = [];
    protected array $orders = [];
    protected int $limit = 0;
    protected int $offset = 0;
    protected array $bindings = [];
}

Metodi Statici

Sezione intitolata “Metodi Statici”

table

Sezione intitolata “table”

Crea un nuovo query builder per una tabella.

public static function table(string $table): QueryBuilder

Parametri:

ParametroTipoDescrizione
$tablestringNome tabella (con o senza prefisso)

Restituisce: QueryBuilder - Istanza query builder

Esempio:

$query = QueryBuilder::table('users');
$query = QueryBuilder::table('xoops_users'); // Con prefisso

Query SELECT

Sezione intitolata “Query SELECT”

select

Sezione intitolata “select”

Specifica le colonne da selezionare.

public function select(...$columns): self

Parametri:

ParametroTipoDescrizione
...$columnsarrayNomi colonne o espressioni

Restituisce: self - Per method chaining

Esempio:

// Select semplice
QueryBuilder::table('users')
    ->select('id', 'username', 'email')
    ->get();


// Select con alias
QueryBuilder::table('users')
    ->select('id as user_id', 'username as name')
    ->get();


// Select tutte colonne
QueryBuilder::table('users')
    ->select('*')
    ->get();


// Select con espressioni
QueryBuilder::table('orders')
    ->select('id', 'COUNT(*) as total_items')
    ->groupBy('id')
    ->get();

where

Sezione intitolata “where”

Aggiunge una condizione WHERE.

public function where(string $column, string $operator = '=', mixed $value = null): self

Parametri:

ParametroTipoDescrizione
$columnstringNome colonna
$operatorstringOperatore di confronto
$valuemixedValore per il confronto

Restituisce: self - Per method chaining

Operatori:

OperatoreDescrizioneEsempio
=Uguale->where('status', '=', 'active')
!= o <>Non uguale->where('status', '!=', 'deleted')
>Maggiore di->where('price', '>', 100)
<Minore di->where('price', '<', 100)
>=Maggiore o uguale->where('age', '>=', 18)
<=Minore o uguale->where('age', '<=', 65)
LIKEPattern match->where('name', 'LIKE', '%john%')
INIn lista->where('status', 'IN', ['active', 'pending'])
NOT INNon in lista->where('id', 'NOT IN', [1, 2, 3])
BETWEENRange->where('age', 'BETWEEN', [18, 65])
IS NULLÈ null->where('deleted_at', 'IS NULL')
IS NOT NULLNon null->where('deleted_at', 'IS NOT NULL')

Esempio:

// Singola condizione
QueryBuilder::table('users')
    ->select('*')
    ->where('status', '=', 'active')
    ->get();


// Condizioni multiple (AND)
QueryBuilder::table('users')
    ->select('*')
    ->where('status', '=', 'active')
    ->where('age', '>=', 18)
    ->get();


// Operatore IN
QueryBuilder::table('products')
    ->select('*')
    ->where('category_id', 'IN', [1, 2, 3])
    ->get();


// Operatore LIKE
QueryBuilder::table('users')
    ->select('*')
    ->where('email', 'LIKE', '%@example.com')
    ->get();


// Controllo NULL
QueryBuilder::table('users')
    ->select('*')
    ->where('deleted_at', 'IS NULL')
    ->get();

orWhere

Sezione intitolata “orWhere”

Aggiunge una condizione OR.

public function orWhere(string $column, string $operator = '=', mixed $value = null): self

Esempio:

QueryBuilder::table('users')
    ->select('*')
    ->where('status', '=', 'active')
    ->orWhere('premium', '=', 1)
    ->get();
    // SELECT * FROM users WHERE status = 'active' OR premium = 1

whereIn / whereNotIn

Sezione intitolata “whereIn / whereNotIn”

Metodi di convenienza per IN/NOT IN.

public function whereIn(string $column, array $values): self
public function whereNotIn(string $column, array $values): self

Esempio:

QueryBuilder::table('posts')
    ->select('*')
    ->whereIn('status', ['published', 'scheduled'])
    ->get();


QueryBuilder::table('comments')
    ->select('*')
    ->whereNotIn('spam_score', [8, 9, 10])
    ->get();

whereNull / whereNotNull

Sezione intitolata “whereNull / whereNotNull”

Metodi di convenienza per controlli NULL.

public function whereNull(string $column): self
public function whereNotNull(string $column): self

Esempio:

QueryBuilder::table('users')
    ->select('*')
    ->whereNotNull('verified_at')
    ->get();

whereBetween

Sezione intitolata “whereBetween”

Verifica se il valore è tra due valori.

public function whereBetween(string $column, array $values): self

Esempio:

QueryBuilder::table('products')
    ->select('*')
    ->whereBetween('price', [10, 100])
    ->get();


QueryBuilder::table('orders')
    ->select('*')
    ->whereBetween('created_at', ['2024-01-01', '2024-12-31'])
    ->get();

join

Sezione intitolata “join”

Aggiunge un INNER JOIN.

public function join(
    string $table,
    string $first,
    string $operator = '=',
    string $second = null
): self

Esempio:

QueryBuilder::table('posts')
    ->select('posts.*', 'users.username', 'categories.name')
    ->join('users', 'posts.user_id', '=', 'users.id')
    ->join('categories', 'posts.category_id', '=', 'categories.id')
    ->where('posts.published', '=', 1)
    ->get();

leftJoin / rightJoin

Sezione intitolata “leftJoin / rightJoin”

Tipi di join alternativi.

public function leftJoin(
    string $table,
    string $first,
    string $operator = '=',
    string $second = null
): self


public function rightJoin(
    string $table,
    string $first,
    string $operator = '=',
    string $second = null
): self

Esempio:

QueryBuilder::table('users')
    ->select('users.*', 'COUNT(posts.id) as post_count')
    ->leftJoin('posts', 'users.id', '=', 'posts.user_id')
    ->groupBy('users.id')
    ->get();

groupBy

Sezione intitolata “groupBy”

Raggruppa risultati per colonna(e).

public function groupBy(...$columns): self

Esempio:

QueryBuilder::table('orders')
    ->select('user_id', 'COUNT(*) as order_count', 'SUM(total) as total_spent')
    ->groupBy('user_id')
    ->get();


QueryBuilder::table('sales')
    ->select('department', 'region', 'SUM(amount) as total')
    ->groupBy('department', 'region')
    ->get();

having

Sezione intitolata “having”

Aggiunge una condizione HAVING.

public function having(string $column, string $operator = '=', mixed $value = null): self

Esempio:

QueryBuilder::table('orders')
    ->select('user_id', 'COUNT(*) as order_count')
    ->groupBy('user_id')
    ->having('order_count', '>', 5)
    ->get();

orderBy

Sezione intitolata “orderBy”

Ordina i risultati.

public function orderBy(string $column, string $direction = 'ASC'): self

Parametri:

ParametroTipoDescrizione
$columnstringColonna da ordinare
$directionstringASC o DESC

Esempio:

// Ordine singolo
QueryBuilder::table('users')
    ->select('*')
    ->orderBy('created_at', 'DESC')
    ->get();


// Ordini multipli
QueryBuilder::table('posts')
    ->select('*')
    ->orderBy('category_id', 'ASC')
    ->orderBy('created_at', 'DESC')
    ->get();


// Ordine casuale
QueryBuilder::table('quotes')
    ->select('*')
    ->orderBy('RAND()')
    ->get();

limit / offset

Sezione intitolata “limit / offset”

Limita e fa l’offset sui risultati.

public function limit(int $limit): self
public function offset(int $offset): self

Esempio:

// Limit semplice
QueryBuilder::table('posts')
    ->select('*')
    ->limit(10)
    ->get();


// Paginazione
$page = 2;
$perPage = 20;
$offset = ($page - 1) * $perPage;


QueryBuilder::table('posts')
    ->select('*')
    ->limit($perPage)
    ->offset($offset)
    ->get();

Metodi di Esecuzione

Sezione intitolata “Metodi di Esecuzione”

get

Sezione intitolata “get”

Esegue query e restituisce tutti i risultati.

public function get(): array

Restituisce: array - Array di righe di risultato

Esempio:

$users = QueryBuilder::table('users')
    ->select('id', 'username', 'email')
    ->where('status', '=', 'active')
    ->orderBy('username')
    ->get();


foreach ($users as $user) {
    echo $user['username'] . ' (' . $user['email'] . ')' . "\n";
}

first

Sezione intitolata “first”

Ottiene il primo risultato.

public function first(): ?array

Restituisce: ?array - Prima riga o null

Esempio:

$user = QueryBuilder::table('users')
    ->select('*')
    ->where('id', '=', 123)
    ->first();


if ($user) {
    echo 'Trovato: ' . $user['username'];
}

last

Sezione intitolata “last”

Ottiene l’ultimo risultato.

public function last(): ?array

Esempio:

$latestPost = QueryBuilder::table('posts')
    ->select('*')
    ->orderBy('created_at', 'DESC')
    ->last();

count

Sezione intitolata “count”

Ottiene il conteggio dei risultati.

public function count(): int

Restituisce: int - Numero di righe

Esempio:

$activeUsers = QueryBuilder::table('users')
    ->where('status', '=', 'active')
    ->count();


echo "Utenti attivi: $activeUsers";

exists

Sezione intitolata “exists”

Verifica se la query restituisce risultati.

public function exists(): bool

Restituisce: bool - True se esistono risultati

Esempio:

if (QueryBuilder::table('users')->where('email', '=', 'test@example.com')->exists()) {
    echo 'L\'utente esiste già';
}

aggregate

Sezione intitolata “aggregate”

Ottiene valori aggregati.

public function aggregate(string $function, string $column): mixed

Esempio:

$maxPrice = QueryBuilder::table('products')
    ->aggregate('MAX', 'price');


$avgAge = QueryBuilder::table('users')
    ->aggregate('AVG', 'age');


$totalSales = QueryBuilder::table('orders')
    ->aggregate('SUM', 'total');

Query INSERT

Sezione intitolata “Query INSERT”

insert

Sezione intitolata “insert”

Inserisce una riga.

public function insert(array $values): bool

Esempio:

QueryBuilder::table('users')->insert([
    'username' => 'john',
    'email' => 'john@example.com',
    'password' => password_hash('secret', PASSWORD_BCRYPT),
    'created_at' => date('Y-m-d H:i:s')
]);

insertMany

Sezione intitolata “insertMany”

Inserisce righe multiple.

public function insertMany(array $rows): bool

Esempio:

QueryBuilder::table('log_entries')->insertMany([
    ['action' => 'login', 'user_id' => 1, 'timestamp' => time()],
    ['action' => 'logout', 'user_id' => 2, 'timestamp' => time()],
    ['action' => 'update', 'user_id' => 3, 'timestamp' => time()]
]);

Query UPDATE

Sezione intitolata “Query UPDATE”

update

Sezione intitolata “update”

Aggiorna righe.

public function update(array $values): int

Restituisce: int - Numero di righe interessate

Esempio:

// Aggiorna singolo utente
QueryBuilder::table('users')
    ->where('id', '=', 123)
    ->update([
        'email' => 'newemail@example.com',
        'updated_at' => date('Y-m-d H:i:s')
    ]);


// Aggiorna righe multiple
QueryBuilder::table('posts')
    ->where('status', '=', 'draft')
    ->where('created_at', '<', date('Y-m-d', strtotime('-30 days')))
    ->update([
        'status' => 'archived'
    ]);

increment / decrement

Sezione intitolata “increment / decrement”

Incrementa o decrementa una colonna.

public function increment(string $column, int $amount = 1): int
public function decrement(string $column, int $amount = 1): int

Esempio:

// Incrementa conteggio visualizzazioni
QueryBuilder::table('posts')
    ->where('id', '=', 123)
    ->increment('views');


// Decrementa stock
QueryBuilder::table('products')
    ->where('id', '=', 456)
    ->decrement('stock', 5);

Query DELETE

Sezione intitolata “Query DELETE”

delete

Sezione intitolata “delete”

Elimina righe.

public function delete(): int

Restituisce: int - Numero di righe eliminate

Esempio:

// Elimina singolo record
QueryBuilder::table('comments')
    ->where('id', '=', 789)
    ->delete();


// Elimina record multipli
QueryBuilder::table('log_entries')
    ->where('created_at', '<', date('Y-m-d', strtotime('-30 days')))
    ->delete();

truncate

Sezione intitolata “truncate”

Elimina tutte le righe dalla tabella.

public function truncate(): bool

Esempio:

// Cancella tutte le sessioni
QueryBuilder::table('sessions')->truncate();

Caratteristiche Avanzate

Sezione intitolata “Caratteristiche Avanzate”

Espressioni Raw

Sezione intitolata “Espressioni Raw”
QueryBuilder::table('products')
    ->select('id', 'name', QueryBuilder::raw('price * quantity as total'))
    ->get();

Subquery

Sezione intitolata “Subquery”
$recentPostIds = QueryBuilder::table('posts')
    ->select('id')
    ->where('created_at', '>', date('Y-m-d', strtotime('-7 days')))
    ->toSql();


$comments = QueryBuilder::table('comments')
    ->select('*')
    ->whereIn('post_id', $recentPostIds)
    ->get();

Ottieni l’SQL

Sezione intitolata “Ottieni l’SQL”
public function toSql(): string

Esempio:

$sql = QueryBuilder::table('users')
    ->select('id', 'username')
    ->where('status', '=', 'active')
    ->toSql();


echo $sql;
// SELECT id, username FROM xoops_users WHERE status = ?

Migliori Pratiche

Sezione intitolata “Migliori Pratiche”
  1. Usa Query Parametrizzate - QueryBuilder gestisce il binding dei parametri automaticamente
  2. Concatena Metodi - Sfrutta l’interfaccia fluente per codice leggibile
  3. Testa Output SQL - Usa toSql() per verificare le query generate
  4. Usa Indici - Assicurati che le colonne frequentemente query siano indicizzate
  5. Limita Risultati - Usa sempre limit() per dataset grandi
  6. Usa Aggregati - Lascia che il database faccia il conteggio/somma invece di PHP
  7. Escapi Output - Sempre escapa i dati visualizzati con htmlspecialchars()
  8. Monitora Performance - Monitora query lente e ottimizza di conseguenza

Documentazione Correlata

Sezione intitolata “Documentazione Correlata”
  • XoopsDatabase - Livello database e connessioni
  • Criteria - Sistema Criteria legacy per query
  • ../Core/XoopsObject - Persistenza oggetto dati
  • ../Module/Module-System - Operazioni database modulo

Vedi anche: API Database XOOPS