Αίτημα HTTP

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

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

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

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

Nette\Http\Request

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

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

Επιστρέφει έναν κλώνο με διαφορετική διεύθυνση URL.

getUrl(): Nette\Http\UrlScript

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

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

Προειδοποίηση: Οι φυλλομετρητές δεν στέλνουν ένα τμήμα στον διακομιστή, οπότε το $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

Επιστρέφει το upload ως αντικείμενο 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 με την οποία έγινε η αίτηση.

echo $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); Ενδέχεται να χρειαστεί να ρυθμίσετε έναν διακομιστή μεσολάβησης για τη σωστή λειτουργία.

isSameSite(): bool

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

isAjax(): bool

Πρόκειται για αίτηση AJAX;

getRemoteAddress(): ?string

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

getRemoteHost(): ?string

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

getBasicCredentials(): ?string

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

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

getRawBody(): ?string

Επιστρέφει το σώμα της αίτησης HTTP:

$body = $httpRequest->getRawBody();

detectLanguage (array $langs): ?string

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

// Κεφαλίδα που αποστέλλεται από το πρόγραμμα περιήγησης: el-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 δημιουργείται αυτόματα από το πλαίσιο).

$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 του διακομιστή μεσολάβησης, η οποία είναι απαραίτητη για τη σωστή ανίχνευση της διεύθυνσης IP του χρήστη.

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

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

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

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

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

Uploaded Files

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

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

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

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

[
	'avatar' => /* FileUpload instance */
]

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

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

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

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

Το επιστρεφόμενο δέντρο καταλήγει να μοιάζει ως εξής:

[
	'my-form' => [
		'details' => [
			'avatar' => /* FileUpload instance */
		],
	],
]

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

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

Σε μια τέτοια περίπτωση η δομή μοιάζει με:

[
	'my-form' => [
		'details' => [
			'avatars' => [
				0 => /* FileUpload instance */,
				1 => /* FileUpload instance */,
				2 => /* FileUpload instance */,
			],
		],
	],
]

Ο καλύτερος τρόπος πρόσβασης στο δείκτη 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, επιστρέφει τη σωστή επέκταση αρχείου.

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

getSuggestedExtension(): ?string

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

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

getUntrustedFullPath(): string

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

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

getSize(): int

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

getTemporaryFile(): string

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

isImage(): bool

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

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

getImageSize(): ?array

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

toImage(): Nette\Utils\Image

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

έκδοση: 4.0