Άμεση SQL
Μπορείτε να εργαστείτε με τη βάση δεδομένων Nette με δύο τρόπους: γράφοντας απευθείας ερωτήματα SQL (Άμεση πρόσβαση) ή αφήνοντας την SQL να δημιουργηθεί αυτόματα(Εξερευνητική πρόσβαση). Η Άμεση πρόσβαση σας επιτρέπει να δημιουργείτε με ασφάλεια ερωτήματα διατηρώντας τον πλήρη έλεγχο της δομής τους.
Για πληροφορίες σχετικά με τη δημιουργία μιας σύνδεσης και τη διαμόρφωσή της, ανατρέξτε στην ξεχωριστή σελίδα.
Βασικές ερωτήσεις
Η μέθοδος query()
εκτελεί ερωτήματα στη βάση δεδομένων και
επιστρέφει ένα αντικείμενο ResultSet που αντιπροσωπεύει το
αποτέλεσμα. Εάν το ερώτημα αποτύχει, η μέθοδος πετάει μια
εξαίρεση. Μπορείτε να κάνετε βρόχο στο αποτέλεσμα του ερωτήματος
χρησιμοποιώντας έναν βρόχο foreach
ή να χρησιμοποιήσετε μια από
τις βοηθητικές συναρτήσεις.
$result = $database->query('SELECT * FROM users');
foreach ($result as $row) {
echo $row->id;
echo $row->name;
}
Για την ασφαλή εισαγωγή τιμών σε ερωτήματα SQL, χρησιμοποιήστε παραμετροποιημένα ερωτήματα. Η Nette Database το κάνει αυτό πολύ απλό: απλά προσθέστε ένα κόμμα και την τιμή στο ερώτημα SQL.
$database->query('SELECT * FROM users WHERE name = ?', $name);
Για πολλαπλές παραμέτρους, μπορείτε είτε να παρεμβάλλετε το ερώτημα SQL με παραμέτρους:
$database->query('SELECT * FROM users WHERE name = ?', $name, 'AND age > ?', $age);
Ή να γράψετε πρώτα ολόκληρο το ερώτημα SQL και στη συνέχεια να επισυνάψετε όλες τις παραμέτρους:
$database->query('SELECT * FROM users WHERE name = ? AND age > ?', $name, $age);
Προστασία κατά της εισβολής SQL
Γιατί είναι σημαντικό να χρησιμοποιείτε παραμετροποιημένα ερωτήματα; Επειδή σας προστατεύουν από επιθέσεις έγχυσης SQL, όπου οι επιτιθέμενοι μπορούν να εισάγουν κακόβουλες εντολές SQL για να χειριστούν ή να αποκτήσουν πρόσβαση σε δεδομένα βάσης δεδομένων.
Ποτέ μην εισάγετε μεταβλητές απευθείας σε ένα ερώτημα SQL! Χρησιμοποιείτε πάντα παραμετροποιημένα ερωτήματα για να προστατεύεστε από SQL injection.
// ❌ UNSAFE CODE - ευάλωτος σε έγχυση SQL
$database->query("SELECT * FROM users WHERE name = '$name'");
// ✅ Ασφαλές παραμετροποιημένο ερώτημα
$database->query('SELECT * FROM users WHERE name = ?', $name);
Φροντίστε να εξοικειωθείτε με τους πιθανούς κινδύνους ασφαλείας.
Τεχνικές αναζήτησης
WHERE Συνθήκες
Μπορείτε να γράψετε τις συνθήκες WHERE
ως συσχετιστικό πίνακα,
όπου τα κλειδιά είναι τα ονόματα των στηλών και οι τιμές είναι τα
δεδομένα προς σύγκριση. Η Nette Database επιλέγει αυτόματα τον καταλληλότερο
τελεστή SQL με βάση τον τύπο της τιμής.
$database->query('SELECT * FROM users WHERE', [
'name' => 'John',
'active' => true,
]);
// WHERE `name` = 'John' AND `active` = 1
Μπορείτε επίσης να καθορίσετε ρητά τον τελεστή στο κλειδί:
$database->query('SELECT * FROM users WHERE', [
'age >' => 25, // χρησιμοποιεί τον τελεστή >
'name LIKE' => '%John%', // χρησιμοποιεί τον τελεστή LIKE
'email NOT LIKE' => '%example.com%', // χρησιμοποιεί τον τελεστή NOT LIKE
]);
// WHERE "age" > 25 AND "name" LIKE "%John%" AND "email" NOT LIKE "%example.com%
Ειδικές περιπτώσεις όπως οι τιμές null
ή οι πίνακες
αντιμετωπίζονται αυτόματα:
$database->query('SELECT * FROM products WHERE', [
'name' => 'Laptop', // χρησιμοποιεί τον τελεστή =
'category_id' => [1, 2, 3], // χρησιμοποιεί IN
'description' => null, // χρησιμοποιεί IS NULL
]);
// WHERE `name` = 'Laptop' AND `category_id` IN (1, 2, 3) AND `description` IS NULL
Για αρνητικές συνθήκες, χρησιμοποιήστε τον τελεστή NOT
:
$database->query('SELECT * FROM products WHERE', [
'name NOT' => 'Laptop', // χρησιμοποιεί τον τελεστή <>
'category_id NOT' => [1, 2, 3], // χρησιμοποιεί NOT IN
'description NOT' => null, // χρησιμοποιεί IS NOT NULL
'id' => [], // skipped
]);
// WHERE `name` <> 'Laptop' AND `category_id` NOT IN (1, 2, 3) AND `description` IS NOT NULL
Από προεπιλογή, οι όροι συνδυάζονται με τον τελεστή AND
.
Μπορείτε να αλλάξετε αυτή τη συμπεριφορά χρησιμοποιώντας τον τελεστή ?or.
ORDER BY Κανόνες
Η ρήτρα ORDER BY
μπορεί να οριστεί ως πίνακας, όπου τα κλειδιά
αντιπροσωπεύουν στήλες και οι τιμές είναι booleans που υποδεικνύουν
αύξουσα σειρά:
$database->query('SELECT id FROM author ORDER BY', [
'id' => true, // αύξουσα
'name' => false, // φθίνουσα
]);
// SELECT id FROM author ORDER BY `id`, `name` DESC
Εισαγωγή δεδομένων (INSERT)
Για να εισαγάγετε εγγραφές, χρησιμοποιήστε τη δήλωση SQL INSERT
.
$values = [
'name' => 'John Doe',
'email' => 'john@example.com',
];
$database->query('INSERT INTO users ?', $values);
$userId = $database->getInsertId();
Η μέθοδος getInsertId()
επιστρέφει το αναγνωριστικό της τελευταίας
εισαχθείσας γραμμής. Για ορισμένες βάσεις δεδομένων (π.χ. PostgreSQL), πρέπει
να καθορίσετε το όνομα της ακολουθίας χρησιμοποιώντας την εντολή
$database->getInsertId($sequenceId)
.
Μπορείτε επίσης να περάσετε ειδικές τιμές, όπως αρχεία, αντικείμενα DateTime ή τύπους enum, ως παραμέτρους.
Εισαγωγή πολλών εγγραφών ταυτόχρονα:
$database->query('INSERT INTO users ?', [
['name' => 'User 1', 'email' => 'user1@mail.com'],
['name' => 'User 2', 'email' => 'user2@mail.com'],
]);
Η εκτέλεση μιας INSERT δέσμης είναι πολύ πιο γρήγορη, επειδή εκτελείται μόνο ένα ερώτημα στη βάση δεδομένων αντί για πολλαπλά μεμονωμένα ερωτήματα.
Σημείωση ασφαλείας: Ποτέ μην χρησιμοποιείτε μη επικυρωμένα
δεδομένα ως $values
. Εξοικειωθείτε με τους πιθανούς κινδύνους.
Ενημέρωση δεδομένων (UPDATE)
Για να ενημερώσετε τις εγγραφές, χρησιμοποιήστε την εντολή SQL
UPDATE
.
// Ενημέρωση μίας εγγραφής
$values = [
'name' => 'John Smith',
];
$result = $database->query('UPDATE users SET ? WHERE id = ?', $values, 1);
Μπορείτε να ελέγξετε τον αριθμό των επηρεαζόμενων γραμμών
χρησιμοποιώντας την εντολή $result->getRowCount()
.
Μπορείτε να χρησιμοποιήσετε τους τελεστές +=
και -=
στο
UPDATE
:
$database->query('UPDATE users SET ? WHERE id = ?', [
'login_count+=' => 1, // αύξηση login_count
], 1);
Για να εισαγάγετε ή να ενημερώσετε μια εγγραφή εάν υπάρχει ήδη,
χρησιμοποιήστε την τεχνική ON DUPLICATE KEY UPDATE
:
$values = [
'name' => $name,
'year' => $year,
];
$database->query('INSERT INTO users ? ON DUPLICATE KEY UPDATE ?',
$values + ['id' => $id],
$values,
);
// INSERT INTO users (`id`, `name`, `year`) VALUES (123, 'Jim', 1978)
// ON DUPLICATE KEY UPDATE `name` = 'Jim', `year` = 1978
Σημειώστε ότι η Nette Database αναγνωρίζει το πλαίσιο της εντολής SQL στο
οποίο χρησιμοποιείται μια παράμετρος με πίνακα και παράγει τον κώδικα
SQL αναλόγως. Για παράδειγμα, κατασκεύασε το
(id, name, year) VALUES (123, 'Jim', 1978)
από τον πρώτο πίνακα, ενώ μετέτρεψε τον
δεύτερο σε name = 'Jim', year = 1978
. Αυτό καλύπτεται λεπτομερέστερα στην
ενότητα Υποδείξεις για την κατασκευή της SQL.
Διαγραφή δεδομένων (DELETE)
Για να διαγράψετε εγγραφές, χρησιμοποιήστε την εντολή SQL DELETE
.
Παράδειγμα με τον αριθμό των διαγραμμένων γραμμών:
$count = $database->query('DELETE FROM users WHERE id = ?', 1)
->getRowCount();
Υποδείξεις κατασκευής SQL
Τα SQL placeholders σας επιτρέπουν να ελέγχετε τον τρόπο με τον οποίο οι τιμές των παραμέτρων ενσωματώνονται στις εκφράσεις SQL:
Υπόδειξη | Περιγραφή | Αυτόματη χρήση για |
---|---|---|
?name |
Χρησιμοποιείται για ονόματα πινάκων ή στηλών | – |
?values |
Δημιουργεί (key, ...) VALUES (value, ...) |
INSERT ... ? , REPLACE ... ? |
?set |
Δημιουργεί αναθέσεις key = value, ... |
SET ? , KEY UPDATE ? |
?and |
Ενώνει όρους σε έναν πίνακα με AND |
WHERE ? , HAVING ? |
?or |
Συνδέει όρους σε πίνακα με OR |
– |
?order |
Δημιουργεί τη ρήτρα ORDER BY |
ORDER BY ? , GROUP BY ? |
Για τη δυναμική εισαγωγή ονομάτων πινάκων ή στηλών, χρησιμοποιήστε
το ?name
. Η Nette Database διασφαλίζει τη σωστή αποφυγή σύμφωνα με τις
συμβάσεις της βάσης δεδομένων (π.χ., περικλείοντας σε backticks για τη MySQL).
$table = 'users';
$column = 'name';
$database->query('SELECT ?name FROM ?name WHERE id = 1', $column, $table);
// SELECT `name` FROM `users` WHERE id = 1 (στη MySQL)
Προειδοποίηση: Χρησιμοποιείτε τον πλαστό φορέα ?name
μόνο
για επικυρωμένα ονόματα πινάκων και στηλών. Διαφορετικά,
διακινδυνεύετε ευπάθειες ασφαλείας.
Άλλες υποδείξεις δεν είναι συνήθως απαραίτητο να καθοριστούν, καθώς
η Nette χρησιμοποιεί έξυπνη αυτόματη ανίχνευση κατά την κατασκευή
ερωτημάτων SQL (βλ. τρίτη στήλη του πίνακα). Ωστόσο, μπορείτε να τις
χρησιμοποιήσετε σε περιπτώσεις όπου θέλετε να συνδυάσετε συνθήκες
χρησιμοποιώντας OR
αντί για AND
:
$database->query('SELECT * FROM users WHERE ?or', [
'name' => 'John',
'email' => 'john@example.com',
]);
// SELECT * FROM users WHERE `name` = 'John' OR `email` = 'john@example.com'
Ειδικές αξίες
Εκτός από τους τυπικούς κλιμακωτούς τύπους (π.χ. string
, int
,
bool
), μπορείτε επίσης να περάσετε ειδικές τιμές ως παραμέτρους:
- Αρχεία: Χρησιμοποιήστε το
fopen('file.png', 'r')
για να εισαγάγετε το δυαδικό περιεχόμενο ενός αρχείου. - Ημερομηνία και ώρα: Τα αντικείμενα
DateTime
μετατρέπονται αυτόματα στη μορφή ημερομηνίας της βάσης δεδομένων. - Τιμές Enum: Οι περιπτώσεις του
enum
μετατρέπονται στις αντίστοιχες τιμές τους. - SQL Literals: Δημιουργούνται με τη χρήση του
Connection::literal('NOW()')
, εισάγονται απευθείας στο ερώτημα.
$database->query('INSERT INTO articles ?', [
'title' => 'My Article',
'published_at' => new DateTime,
'content' => fopen('image.png', 'r'),
'state' => Status::Draft,
]);
Για βάσεις δεδομένων που δεν υποστηρίζουν εγγενώς τον τύπο
datetime
(π.χ. SQLite και Oracle), οι τιμές DateTime
μετατρέπονται
σύμφωνα με την επιλογή ρύθμισης formatDateTime
(προεπιλογή: U
για Unix timestamp).
Κυριολεκτικές λέξεις SQL
Σε ορισμένες περιπτώσεις, μπορεί να χρειαστεί να εισαγάγετε
ακατέργαστο κώδικα SQL ως τιμή χωρίς να τον αντιμετωπίσετε ως
συμβολοσειρά ή να τον διαφυλάξετε. Για το σκοπό αυτό, χρησιμοποιήστε
αντικείμενα της κλάσης Nette\Database\SqlLiteral
, τα οποία μπορείτε να
δημιουργήσετε χρησιμοποιώντας τη μέθοδο Connection::literal()
.
$result = $database->query('SELECT * FROM users WHERE', [
'name' => $name,
'year >' => $database::literal('YEAR()'),
]);
// SELECT * FROM users WHERE (`name` = 'Jim') AND (`year` > YEAR())
Εναλλακτικά:
$result = $database->query('SELECT * FROM users WHERE', [
'name' => $name,
$database::literal('year > YEAR()'),
]);
// SELECT * FROM users WHERE (`name` = 'Jim') AND (year > YEAR())
SQL literals μπορούν επίσης να περιέχουν παραμέτρους:
$result = $database->query('SELECT * FROM users WHERE', [
'name' => $name,
$database::literal('year > ? AND year < ?', $min, $max),
]);
// SELECT * FROM users WHERE `name` = 'Jim' AND (έτος > 1978 AND έτος < 2017)
Αυτό επιτρέπει ευέλικτους συνδυασμούς:
$result = $database->query('SELECT * FROM users WHERE', [
'name' => $name,
$database::literal('?or', [
'active' => true,
'role' => $role,
]),
]);
// SELECT * FROM users WHERE `name` = 'Jim' AND (`active` = 1 OR `role` = 'admin')
Λήψη δεδομένων
Συντομεύσεις για ερωτήματα SELECT
Για την απλούστευση της ανάκτησης δεδομένων, η κλάση Connection
παρέχει διάφορες συντομεύσεις που συνδυάζουν μια κλήση query()
με
μια επακόλουθη κλήση fetch*()
. Αυτές οι μέθοδοι δέχονται τις ίδιες
παραμέτρους με την query()
, δηλαδή ένα ερώτημα SQL και προαιρετικές
παραμέτρους. Μια λεπτομερής περιγραφή των μεθόδων fetch*()
μπορεί
να βρεθεί παρακάτω.
fetch($sql, ...$params): ?Row |
Εκτελεί το ερώτημα και ανακτά την πρώτη γραμμή ως αντικείμενο
Row . |
fetchAll($sql, ...$params): array |
Εκτελεί το ερώτημα και ανακτά όλες τις γραμμές ως πίνακα
αντικειμένων Row . |
fetchPairs($sql, ...$params): array |
Εκτελεί το ερώτημα και ανακτά έναν συσχετιστικό πίνακα όπου η πρώτη στήλη είναι το κλειδί και η δεύτερη η τιμή. |
fetchField($sql, ...$params): mixed |
Εκτελεί το ερώτημα και ανακτά την τιμή του πρώτου κελιού της πρώτης γραμμής. |
fetchList($sql, ...$params): ?array |
Εκτελεί το ερώτημα και ανακτά την πρώτη γραμμή ως δεικτοδοτούμενο πίνακα. |
Παράδειγμα:
// fetchField() - επιστρέφει την τιμή του πρώτου κελιού
$count = $database->query('SELECT COUNT(*) FROM articles')
->fetchField();
foreach
– Γραμμές
Μετά την εκτέλεση ενός ερωτήματος, επιστρέφεται ένα αντικείμενο ResultSet, το οποίο σας επιτρέπει
να επαναλαμβάνετε τα αποτελέσματα με διάφορους τρόπους. Ο απλούστερος
και πιο αποδοτικός στη μνήμη τρόπος ανάκτησης γραμμών είναι η
επανάληψη σε έναν βρόχο foreach
. Αυτή η μέθοδος επεξεργάζεται τις
γραμμές μία προς μία και αποφεύγει την αποθήκευση όλων των δεδομένων
στη μνήμη ταυτόχρονα.
$result = $database->query('SELECT * FROM users');
foreach ($result as $row) {
echo $row->id;
echo $row->name;
//...
}
Το ResultSet
μπορεί να επαναληφθεί μόνο μία φορά. Εάν πρέπει
να την επαναλάβετε πολλές φορές, πρέπει πρώτα να φορτώσετε τα δεδομένα
σε έναν πίνακα, για παράδειγμα, χρησιμοποιώντας τη μέθοδο
fetchAll()
.
fetch(): ?Row
Εκτελεί το ερώτημα και ανακτά μια μόνο γραμμή ως αντικείμενο
Row
. Εάν δεν υπάρχουν άλλες διαθέσιμες γραμμές, επιστρέφει το
null
. Αυτή η μέθοδος προωθεί τον εσωτερικό δείκτη στην επόμενη
γραμμή.
$result = $database->query('SELECT * FROM users');
$row = $result->fetch(); // φέρνει την πρώτη σειρά
if ($row) {
echo $row->name;
}
fetchAll(): array
Λαμβάνει όλες τις υπόλοιπες γραμμές από το ResultSet
ως πίνακα
αντικειμένων Row
.
$result = $database->query('SELECT * FROM users');
$rows = $result->fetchAll(); // φέρνει όλες τις γραμμές
foreach ($rows as $row) {
echo $row->name;
}
fetchPairs(string|int|null $key = null, string|int|null $value = null): array
Αντλεί τα αποτελέσματα ως συσχετιστικό πίνακα. Το πρώτο όρισμα καθορίζει τη στήλη που θα χρησιμοποιηθεί ως κλειδί και το δεύτερο όρισμα καθορίζει τη στήλη που θα χρησιμοποιηθεί ως τιμή:
$result = $database->query('SELECT id, name FROM users');
$names = $result->fetchPairs('id', 'name');
// [1 => 'John Doe', 2 => 'Jane Doe', ...]
Εάν παρέχεται μόνο η πρώτη παράμετρος, η τιμή θα είναι ολόκληρη η
γραμμή (ως αντικείμενο Row
):
$rows = $result->fetchPairs('id');
// [1 => Row(id: 1, name: 'John'), 2 => Row(id: 2, name: 'Jane'), ...]
Εάν το null
δίνεται ως κλειδί, ο πίνακας θα έχει αριθμητική
ευρετηρίαση ξεκινώντας από το μηδέν:
$names = $result->fetchPairs(null, 'name');
// [0 => 'John Doe', 1 => 'Jane Doe', ...]
fetchPairs(Closure $callback): array
Εναλλακτικά, μπορείτε να παρέχετε μια επανάκληση που καθορίζει τα ζεύγη κλειδιών-τιμών ή τις τιμές για κάθε γραμμή.
$result = $database->query('SELECT * FROM users');
$items = $result->fetchPairs(fn($row) => "$row->id - $row->name");
// ['1 - John', '2 - Jane', ...]
// Η επανάκληση μπορεί επίσης να επιστρέψει έναν πίνακα με ένα ζεύγος κλειδιών και τιμών:
$names = $result->fetchPairs(fn($row) => [$row->name, $row->age]);
// ['John' => 46, 'Jane' => 21, ...]
fetchField(): mixed
Λαμβάνει την τιμή του πρώτου κελιού της τρέχουσας γραμμής. Αν δεν
υπάρχουν άλλες διαθέσιμες γραμμές, επιστρέφει null
. Αυτή η
μέθοδος προωθεί τον εσωτερικό δείκτη στην επόμενη γραμμή.
$result = $database->query('SELECT name FROM users');
$name = $result->fetchField(); // ανακτά το όνομα από την πρώτη σειρά
fetchList(): ?array
Λαμβάνει τη γραμμή ως δεικτοδοτούμενο πίνακα. Αν δεν υπάρχουν άλλες
διαθέσιμες γραμμές, επιστρέφει null
. Αυτή η μέθοδος προωθεί τον
εσωτερικό δείκτη στην επόμενη γραμμή.
$result = $database->query('SELECT name, email FROM users');
$row = $result->fetchList(); // ['John', 'john@example.com']
getRowCount(): ?int
Επιστρέφει τον αριθμό των γραμμών που επηρεάστηκαν από το τελευταίο
ερώτημα UPDATE
ή DELETE
. Για τα ερωτήματα SELECT
,
επιστρέφει τον αριθμό των γραμμών που ανακτήθηκαν, αλλά αυτό μπορεί να
μην είναι πάντα γνωστό – σε τέτοιες περιπτώσεις, επιστρέφει
null
.
getColumnCount(): ?int
Επιστρέφει τον αριθμό των στηλών στο ResultSet
.
Πληροφορίες ερωτήματος
Για να ανακτήσετε λεπτομέρειες σχετικά με το πιο πρόσφατα εκτελεσμένο ερώτημα, χρησιμοποιήστε:
echo $database->getLastQueryString(); // εξάγει το ερώτημα SQL
$result = $database->query('SELECT * FROM articles');
echo $result->getQueryString(); // εξάγει το ερώτημα SQL
echo $result->getTime(); // εξάγει το χρόνο εκτέλεσης σε δευτερόλεπτα
Για να εμφανίσετε το αποτέλεσμα ως πίνακα HTML, χρησιμοποιήστε:
$result = $database->query('SELECT * FROM articles');
$result->dump();
Μπορείτε επίσης να ανακτήσετε πληροφορίες σχετικά με τους τύπους των
στηλών από τη διεύθυνση ResultSet
:
$result = $database->query('SELECT * FROM articles');
$types = $result->getColumnTypes();
foreach ($types as $column => $type) {
echo "$column is of type $type->type"; // π.χ., 'id is of type int'
}
Καταγραφή ερωτημάτων
Μπορείτε να υλοποιήσετε προσαρμοσμένη καταγραφή ερωτημάτων. Το
συμβάν onQuery
είναι ένας πίνακας από callbacks που καλούνται μετά από
κάθε εκτέλεση ερωτήματος:
$database->onQuery[] = function ($database, $result) use ($logger) {
$logger->info('Query: ' . $result->getQueryString());
$logger->info('Time: ' . $result->getTime());
if ($result->getRowCount() > 1000) {
$logger->warning('Large result set: ' . $result->getRowCount() . ' rows');
}
};