Αίτημα HTTP

Το Nette ενσωματώνει το αίτημα HTTP σε αντικείμενα με ένα κατανοητό API και ταυτόχρονα παρέχει ένα φίλτρο εξυγίανσης.

Το αίτημα HTTP αντιπροσωπεύεται από το αντικείμενο Nette\Http\Request. Εάν εργάζεστε με το Nette, αυτό το αντικείμενο δημιουργείται αυτόματα από το framework και μπορείτε να το λάβετε μέσω έγχυσης εξάρτησης. Στους presenters, απλά καλέστε τη μέθοδο $this->getHttpRequest(). Εάν εργάζεστε εκτός του Nette Framework, μπορείτε να δημιουργήσετε το αντικείμενο χρησιμοποιώντας το RequestFactory.

Ένα μεγάλο πλεονέκτημα του Nette είναι ότι κατά τη δημιουργία του αντικειμένου, καθαρίζει αυτόματα όλες τις παραμέτρους εισόδου GET, POST, COOKIE, καθώς και το URL από χαρακτήρες ελέγχου και μη έγκυρες ακολουθίες UTF-8. Στη συνέχεια, μπορείτε να εργαστείτε με ασφάλεια με αυτά τα δεδομένα. Τα καθαρισμένα δεδομένα χρησιμοποιούνται στη συνέχεια σε presenters και φόρμες.

Εγκατάσταση και απαιτήσεις

Nette\Http\Request

Αυτό το αντικείμενο είναι αμετάβλητο (immutable). Δεν έχει setters, έχει μόνο έναν λεγόμενο wither withUrl(), ο οποίος δεν αλλάζει το αντικείμενο, αλλά επιστρέφει μια νέα παρουσία με την αλλαγμένη τιμή.

withUrl (Nette\Http\UrlScript $url): Nette\Http\Request

Επιστρέφει έναν κλώνο με διαφορετικό URL.

getUrl(): Nette\Http\UrlScript

Επιστρέφει το URL του αιτήματος ως αντικείμενο UrlScript.

$url = $httpRequest->getUrl();
echo $url; // https://doc.nette.org/cs/?action=edit
echo $url->getHost(); // nette.org

Προειδοποίηση: οι περιηγητές δεν στέλνουν το fragment στον διακομιστή, οπότε το $url->getFragment() θα επιστρέψει μια κενή συμβολοσειρά.

getQuery (?string $key=null): string|array|null

Επιστρέφει τις παραμέτρους GET του αιτήματος.

$all = $httpRequest->getQuery(); // επιστρέφει έναν πίνακα όλων των παραμέτρων από το URL
$id = $httpRequest->getQuery('id'); // επιστρέφει την παράμετρο GET 'id' (ή null)

getPost (?string $key=null): string|array|null

Επιστρέφει τις παραμέτρους POST του αιτήματος.

$all = $httpRequest->getPost(); // επιστρέφει έναν πίνακα όλων των παραμέτρων από το POST
$id = $httpRequest->getPost('id'); // επιστρέφει την παράμετρο POST 'id' (ή null)

getFile (string|string[] $key): Nette\Http\FileUpload|array|null

Επιστρέφει το ανέβασμα ως αντικείμενο Nette\Http\FileUpload:

$file = $httpRequest->getFile('avatar');
if ($file?->hasFile()) { // ανέβηκε κάποιο αρχείο;
	$file->getUntrustedName(); // όνομα αρχείου που στάλθηκε από τον χρήστη
	$file->getSanitizedName(); // όνομα χωρίς επικίνδυνους χαρακτήρες
}

Για πρόσβαση σε μια ένθετη δομή, καθορίστε έναν πίνακα κλειδιών.

//<input type="file" name="my-form[details][avatar]" multiple>
$file = $request->getFile(['my-form', 'details', 'avatar']);

Επειδή δεν μπορείτε να εμπιστευτείτε δεδομένα από έξω και επομένως ούτε να βασιστείτε στη μορφή της δομής των αρχείων, αυτή η μέθοδος είναι ασφαλέστερη από, για παράδειγμα, $request->getFiles()['my-form']['details']['avatar'], η οποία μπορεί να αποτύχει.

getFiles(): array

Επιστρέφει ένα δέντρο όλων των ανεβασμάτων σε μια κανονικοποιημένη δομή, της οποίας τα φύλλα είναι αντικείμενα Nette\Http\FileUpload:

$files = $httpRequest->getFiles();

getCookie (string $key): string|array|null

Επιστρέφει ένα cookie ή null εάν δεν υπάρχει.

$sessId = $httpRequest->getCookie('sess_id');

getCookies(): array

Επιστρέφει όλα τα cookies.

$cookies = $httpRequest->getCookies();

getMethod(): string

Επιστρέφει τη μέθοδο HTTP με την οποία έγινε το αίτημα.

$httpRequest->getMethod(); // GET, POST, HEAD, PUT

isMethod (string $method)bool

Ελέγχει τη μέθοδο HTTP με την οποία έγινε το αίτημα. Η παράμετρος δεν κάνει διάκριση πεζών-κεφαλαίων.

if ($httpRequest->isMethod('GET')) // ...

getHeader (string $header): ?string

Επιστρέφει μια κεφαλίδα HTTP ή null εάν δεν υπάρχει. Η παράμετρος δεν κάνει διάκριση πεζών-κεφαλαίων.

$userAgent = $httpRequest->getHeader('User-Agent');

getHeaders(): array

Επιστρέφει όλες τις κεφαλίδες HTTP ως συσχετιστικό πίνακα.

$headers = $httpRequest->getHeaders();
echo $headers['Content-Type'];

isSecured(): bool

Είναι η σύνδεση κρυπτογραφημένη (HTTPS); Μπορεί να χρειαστεί να ρυθμίσετε έναν proxy για σωστή λειτουργία.

isSameSite(): bool

Προέρχεται το αίτημα από το ίδιο (υπο)domain και ξεκίνησε κάνοντας κλικ σε έναν σύνδεσμο; Το Nette χρησιμοποιεί το cookie _nss (παλαιότερα nette-samesite) για ανίχνευση.

isAjax(): bool

Είναι αυτό ένα αίτημα AJAX;

getRemoteAddress(): ?string

Επιστρέφει τη διεύθυνση IP του χρήστη. Μπορεί να χρειαστεί να ρυθμίσετε έναν proxy για σωστή λειτουργία.

getRemoteHost(): ?string

Επιστρέφει τη μετάφραση DNS της διεύθυνσης IP του χρήστη. Μπορεί να χρειαστεί να ρυθμίσετε έναν proxy για σωστή λειτουργία.

getBasicCredentials(): ?array

Επιστρέφει τα διαπιστευτήρια ελέγχου ταυτότητας για Basic HTTP authentication.

[$user, $password] = $httpRequest->getBasicCredentials();

getRawBody(): ?string

Επιστρέφει το σώμα του αιτήματος HTTP.

$body = $httpRequest->getRawBody();

detectLanguage (array $langs): ?string

Ανιχνεύει τη γλώσσα. Ως παράμετρο $lang, περνάμε έναν πίνακα με τις γλώσσες που υποστηρίζει η εφαρμογή, και επιστρέφει αυτή που θα προτιμούσε να δει ο περιηγητής του επισκέπτη. Δεν είναι μαγεία, απλά χρησιμοποιεί την κεφαλίδα Accept-Language. Εάν δεν βρεθεί αντιστοιχία, επιστρέφει null.

// ο περιηγητής στέλνει π.χ. Accept-Language: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3

$langs = ['hu', 'pl', 'en']; // γλώσσες που υποστηρίζονται από την εφαρμογή
echo $httpRequest->detectLanguage($langs); // en

RequestFactory

Η κλάση Nette\Http\RequestFactory χρησιμοποιείται για τη δημιουργία μιας παρουσίας του Nette\Http\Request, η οποία αντιπροσωπεύει το τρέχον αίτημα HTTP. (Εάν εργάζεστε με το Nette, το αντικείμενο αιτήματος HTTP δημιουργείται αυτόματα από το framework.)

$factory = new Nette\Http\RequestFactory;
$httpRequest = $factory->fromGlobals();

Η μέθοδος fromGlobals() δημιουργεί το αντικείμενο αιτήματος με βάση τις τρέχουσες καθολικές μεταβλητές της PHP ($_GET, $_POST, $_COOKIE, $_FILES και $_SERVER). Κατά τη δημιουργία του αντικειμένου, καθαρίζει αυτόματα όλες τις παραμέτρους εισόδου GET, POST, COOKIE, καθώς και το URL από χαρακτήρες ελέγχου και μη έγκυρες ακολουθίες UTF-8, γεγονός που διασφαλίζει την ασφάλεια κατά την περαιτέρω εργασία με αυτά τα δεδομένα.

Το RequestFactory μπορεί να διαμορφωθεί πριν από την κλήση του fromGlobals():

  • με τη μέθοδο $factory->setBinary(), απενεργοποιείτε τον αυτόματο καθαρισμό των παραμέτρων εισόδου από χαρακτήρες ελέγχου και μη έγκυρες ακολουθίες UTF-8.
  • με τη μέθοδο $factory->setProxy(...), καθορίζετε τη διεύθυνση IP του proxy server, η οποία είναι απαραίτητη για τη σωστή ανίχνευση της διεύθυνσης IP του χρήστη.

Το RequestFactory επιτρέπει τον ορισμό φίλτρων που μετασχηματίζουν αυτόματα τμήματα του URL του αιτήματος. Αυτά τα φίλτρα αφαιρούν ανεπιθύμητους χαρακτήρες από το URL, οι οποίοι μπορεί να έχουν εισαχθεί εκεί, για παράδειγμα, από λανθασμένη υλοποίηση συστημάτων σχολιασμού σε διάφορους ιστότοπους:

// αφαίρεση κενών από τη διαδρομή
$requestFactory->urlFilters['path']['%20'] = '';

// αφαίρεση τελείας, κόμματος ή δεξιάς παρένθεσης από το τέλος του URI
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// καθαρισμός της διαδρομής από διπλές καθέτους (προεπιλεγμένο φίλτρο)
$requestFactory->urlFilters['path']['/{2,}'] = '/';

Το πρώτο κλειδί 'path' ή 'url' καθορίζει σε ποιο τμήμα του URL θα εφαρμοστεί το φίλτρο. Το δεύτερο κλειδί είναι η κανονική έκφραση που πρέπει να βρεθεί, και η τιμή είναι η αντικατάσταση που θα χρησιμοποιηθεί αντί για το κείμενο που βρέθηκε.

Ανεβασμένα Αρχεία

Η μέθοδος Nette\Http\Request::getFiles() επιστρέφει έναν πίνακα όλων των ανεβασμάτων σε μια κανονικοποιημένη δομή, της οποίας τα φύλλα είναι αντικείμενα Nette\Http\FileUpload. Αυτά ενσωματώνουν τα δεδομένα που αποστέλλονται από το στοιχείο φόρμας <input type=file>.

Η δομή αντικατοπτρίζει την ονομασία των στοιχείων στο HTML. Στην απλούστερη περίπτωση, μπορεί να είναι ένα μόνο ονομασμένο στοιχείο φόρμας που αποστέλλεται ως:

<input type="file" name="avatar">

Σε αυτή την περίπτωση, το $request->getFiles() επιστρέφει έναν πίνακα:

[
	'avatar' => /* Παράδειγμα FileUpload */
]

Το αντικείμενο FileUpload δημιουργείται ακόμη και αν ο χρήστης δεν ανέβασε κανένα αρχείο ή το ανέβασμα απέτυχε. Η μέθοδος hasFile() επιστρέφει εάν ένα αρχείο ανέβηκε:

$request->getFile('avatar')?->hasFile();

Στην περίπτωση ενός ονόματος στοιχείου που χρησιμοποιεί σημειογραφία πίνακα:

<input type="file" name="my-form[details][avatar]">

το επιστρεφόμενο δέντρο μοιάζει με αυτό:

[
	'my-form' => [
		'details' => [
			'avatar' => /* Παράδειγμα FileUpload */
		],
	],
]

Μπορείτε επίσης να δημιουργήσετε έναν πίνακα αρχείων:

<input type="file" name="my-form[details][avatars][]" multiple>

Σε αυτή την περίπτωση, η δομή μοιάζει με αυτό:

[
	'my-form' => [
		'details' => [
			'avatars' => [
				0 => /* Παράδειγμα FileUpload */,
				1 => /* Παράδειγμα FileUpload */,
				2 => /* Παράδειγμα FileUpload */,
			],
		],
	],
]

Η πρόσβαση στο ευρετήριο 1 του ένθετου πίνακα γίνεται καλύτερα ως εξής:

$file = $request->getFile(['my-form', 'details', 'avatars', 1]);
if ($file instanceof FileUpload) {
	// ...
}

Επειδή δεν μπορείτε να εμπιστευτείτε δεδομένα από έξω και επομένως ούτε να βασιστείτε στη μορφή της δομής των αρχείων, αυτή η μέθοδος είναι ασφαλέστερη από, για παράδειγμα, $request->getFiles()['my-form']['details']['avatars'][1], η οποία μπορεί να αποτύχει.

Επισκόπηση των μεθόδων FileUpload

hasFile(): bool

Επιστρέφει true εάν ο χρήστης ανέβασε κάποιο αρχείο.

isOk(): bool

Επιστρέφει true εάν το αρχείο ανέβηκε με επιτυχία.

getError(): int

Επιστρέφει τον κωδικό σφάλματος κατά το ανέβασμα του αρχείου. Είναι μία από τις σταθερές UPLOAD_ERR_XXX. Εάν το ανέβασμα ήταν επιτυχές, επιστρέφει UPLOAD_ERR_OK.

move (string $dest)

Μετακινεί το ανεβασμένο αρχείο σε νέα τοποθεσία. Εάν το αρχείο προορισμού υπάρχει ήδη, θα αντικατασταθεί.

$file->move('/path/to/files/name.ext');

getContents(): ?string

Επιστρέφει τα περιεχόμενα του ανεβασμένου αρχείου. Εάν το ανέβασμα δεν ήταν επιτυχές, επιστρέφει null.

getContentType(): ?string

Ανιχνεύει τον τύπο περιεχομένου MIME του ανεβασμένου αρχείου με βάση την υπογραφή του. Εάν το ανέβασμα δεν ήταν επιτυχές ή η ανίχνευση απέτυχε, επιστρέφει null.

Απαιτεί την επέκταση PHP fileinfo.

getUntrustedName(): string

Επιστρέφει το αρχικό όνομα του αρχείου, όπως στάλθηκε από τον περιηγητή.

Μην εμπιστεύεστε την τιμή που επιστρέφεται από αυτή τη μέθοδο. Ο πελάτης θα μπορούσε να έχει στείλει ένα κακόβουλο όνομα αρχείου με σκοπό να βλάψει ή να παραβιάσει την εφαρμογή σας.

getSanitizedName(): string

Επιστρέφει το εξυγιασμένο όνομα αρχείου. Περιέχει μόνο χαρακτήρες ASCII [a-zA-Z0-9.-]. Εάν το όνομα δεν περιέχει τέτοιους χαρακτήρες, επιστρέφει 'unknown'. Εάν το αρχείο είναι εικόνα σε μορφή JPEG, PNG, GIF, WebP ή AVIF, επιστρέφει επίσης τη σωστή επέκταση.

Απαιτεί την επέκταση PHP fileinfo.

getSuggestedExtension(): ?string

Επιστρέφει την κατάλληλη επέκταση αρχείου (χωρίς την τελεία) που αντιστοιχεί στον ανιχνευμένο τύπο MIME.

Απαιτεί την επέκταση PHP fileinfo.

getUntrustedFullPath(): string

Επιστρέφει την αρχική διαδρομή του αρχείου, όπως στάλθηκε από τον περιηγητή κατά το ανέβασμα ενός φακέλου. Η πλήρης διαδρομή είναι διαθέσιμη μόνο σε PHP 8.1 και νεότερες εκδόσεις. Σε προηγούμενες εκδόσεις, αυτή η μέθοδος επιστρέφει το αρχικό όνομα αρχείου.

Μην εμπιστεύεστε την τιμή που επιστρέφεται από αυτή τη μέθοδο. Ο πελάτης θα μπορούσε να έχει στείλει ένα κακόβουλο όνομα αρχείου με σκοπό να βλάψει ή να παραβιάσει την εφαρμογή σας.

getSize(): int

Επιστρέφει το μέγεθος του ανεβασμένου αρχείου. Εάν το ανέβασμα δεν ήταν επιτυχές, επιστρέφει 0.

getTemporaryFile(): string

Επιστρέφει τη διαδρομή προς την προσωρινή τοποθεσία του ανεβασμένου αρχείου. Εάν το ανέβασμα δεν ήταν επιτυχές, επιστρέφει ''.

isImage(): bool

Επιστρέφει true εάν το ανεβασμένο αρχείο είναι εικόνα σε μορφή JPEG, PNG, GIF, WebP ή AVIF. Η ανίχνευση βασίζεται στην υπογραφή του και δεν επαληθεύει την ακεραιότητα ολόκληρου του αρχείου. Το αν μια εικόνα είναι κατεστραμμένη μπορεί να προσδιοριστεί, για παράδειγμα, προσπαθώντας να την φορτώσετε.

Απαιτεί την επέκταση PHP fileinfo.

getImageSize(): ?array

Επιστρέφει ένα ζεύγος [πλάτος, ύψος] με τις διαστάσεις της ανεβασμένης εικόνας. Εάν το ανέβασμα δεν ήταν επιτυχές ή δεν είναι έγκυρη εικόνα, επιστρέφει null.

toImage(): Nette\Utils\Image

Φορτώνει την εικόνα ως αντικείμενο Image. Εάν το ανέβασμα δεν ήταν επιτυχές ή δεν είναι έγκυρη εικόνα, δημιουργεί μια εξαίρεση Nette\Utils\ImageException.

έκδοση: 4.0