Η setcookie() ορίζει να σταλεί ένα cookie μαζί με τους υπόλοιπους HTTP headers. Όπως και οι άλλοι headers, τα cookies πρέπει να στέλνονται πριν από οποιοδήποτε αποτέλεσμα (output) του script σας (αυτό είναι ένας περιορισμός του πρωτοκόλου). Αυτό προϋποθέτει ότι εσείς τοποθετείτε τις κλήσεις αυτής της συνάρτησης πριν από κάθε output, συμπεριλαμβανομένων των <html> και <head> tags όπως επίσης και οπιονδήποτε κενών. Αν το output υπάρχει πριν από την κλήση αυτής της συνάρτησης, η setcookie() θα αποτύχει και θα επιστρέψει FALSE. Αν η setcookie() εκτελεστεί επιτυχώς, θα επιστρέψει TRUE. Αυτό όμως δεν δείχνει αν ο χρήστης έχει δεχθεί το cookie.
Óçìåßùóç: Στην PHP 4, μπορείτε να χρησιμοποιήσετε buffering στο output για να στείλετε το output πριν από την κλήση αυτής της συνάρτησης, κάνοντας buffer στον server το overhead ολόκληρου του output στον browser μέχρι αυτό να σταλεί. Μπορείτε να το κάνετε αυτό καλώντας την ob_start() και την ob_end_flush() στο script σας, ή θέτοντας την output_buffering configuration ντιρεκτίβα στο php.ini ή στα αρχεία configuration του server.
Όλες οι παράμετροι εκτός από την παράμετρο name είναι προαιρετικές. Μπορείτε επίσης να αντικαταστήσετε μια παράμετρο με ένα κενό string ("") προκειμένου να παρακάμψετε αυτή την παράμετρο. Επειδή οι παράμετροι expire και secure είναι ακέραιοι, δεν μπορούν να παρακαμφθούν με ένα κενό string, αλλά πρέπει να χρησιμοποιήσετε το μηδέν (0). Ο παρακάτω πίνακας εξηγεί κάθε παράμετρο της συνάρτησης setcookie(), και διαβάστε το τμήμα Ορισμό cookie για Netscape για οδηγίες σχετικά με το πώς κάθε παράμετρος setcookie() δουλεύει και το RFC 2965 για επιπρόσθετες πληροφορίες σχετικά με το πώς η HTTP cookies δουλεύει.
Ðßíáêáò 1. setcookie() εξήγηση παραμέτρων
Παράμετρος | Περιγραφή | Παραδείγματα |
---|---|---|
name | Το όνομα του cookie. | η 'cookiename' καλείται ως $_COOKIE['cookiename'] |
value | Η τιμή του cookie. Η τιμή αυτή αποθηκεύεται στον υπολογιστών των clients, γι'αυτό μην αποθηκεύετε ευαίσθητες πληροφορίες. | Υποθέτοντας ότι η name είναι η 'cookiename', αυτή η τιμή παίρνεται με την $_COOKIE['cookiename'] |
expire | Η ώρα λήξης του cookie. Αυτό είναι ένα unix timestamp έτσι είναι σε αριθμό δευτερολέπτων από την εποχή (epoch). Με άλλα λόγια, είναι πιθανό ότι θα θέσετε αυτό με τη συνάρτηση time() συν τον αριθμό των δευτερολέπτων πριν από τη στιγμή που θέλετε να λήξει. Ή μπορείτε να χρησιμοποιήσετε την mktime(). | Η time()+60*60*24*30 θα ορίσει το cookie να λήξει σε 30 μέρες. Αν δεν τεθεί, το cookie θα λήξει στο τέλος του session (όταν κλείσει ο browser). |
path | Το path στον server στο οποίο θα είναι διαθέσιμο το cookie. | Αν τεθεί στο '/', το cookie θα είναι διαθέσιμο μέσα σε ολόκληρο το domain. Αν τεθεί στο '/foo/', το cookie θα είναι διαθέσιμο μόνο μέσα στον κατάλογο /foo/ και σε όλους τους υπο-καταλόγους όπως οι /foo/bar/ του domain. Η προκαθορισμένη τιμή είναι το τρέχον directory στο οποίο θέτεται το cookie. |
domain | Το domain στο οποίο το cookie είναι διαθέσιμο. | Για να είναι το cookie διαθέσιμο σε όλα τα subdomains του example.com θα πρέπει να το θέσετε στο '.example.com'. Η . δεν απαιτείται αλλά το κάνει συμβατό με περισσότερους browsers. Θέτοντας το στο www.example.com θα κάνει το cookie διαθέσιμο μόνο στο www subdomain. Αναφερθείτε στο tail matching στο spec για λεπτομέρειες. |
secure | Δείχνει ότι το cookie μπορεί μόνο να μεταδωθεί με secure HTTPS σύνδεση. Όταν τίθεται στο 1, το cookie θα δημιουργηθεί μόνο αν υπάρχει μια ασφαλής σύνδεση. Το προκαθορισμένο είναι το 0. | 0 ή 1 |
Αφού έχουν σταλεί τα cookies, μπορούν να προσπελαστούν κατά τη φόρτωση της επόμενης σελίδας με τον πίνακα (array) $_COOKIE ή $HTTP_COOKIE_VARS. Σημειώστε ότι οι autoglobals όπως οι $_COOKIE είναι διαθέσιμες από την PHP 4.1.0. Η $HTTP_COOKIE_VARS υπάρχει από την PHP 3. Οι τιμές των cookies υπάρχουν επίσης και στην $_REQUEST.
Óçìåßùóç: Αν η ντιρεκτίβα της PHP register_globals τεθεί στο on τότε οι τιμές των cookies θα γίνουν επίσης μεταβλητές. Στα παραδείγματα μας παρακάτω, η $TextCookie θα υπάρξει. Συνιστούμε να χρησιμοποιείτε την $_COOKIE.
Συχνά λάθη:
Τα cookies δε θα είναι ορατά μέχρι το επόμενο φόρτωμα της σελίδας για την οποία το cookie θα πρέπει να είναι ορατό. Για να ελένξετε αν ένα cookie έχει οριστεί με επιτυχία, ελένξτε το cookie στο επόμενο φόρτωμα της σελίδα πριν όμως το cookie λήξει. Η ώρα λήξης ορίζεται διαμέσου της παραμέτρου expire. Ένας ωραίος τρόπος για να κάνετε debug στην ύπαρξη των cookies είναι καλώντας απλά την print_r($_COOKIE);.
Τα cookies πρέπει να διαγράφονται με τις ίδιες παραμέτρους με τις οποίες θέτονται. Αν η τιμή της παραμέτρου είναι ένα κενό string (""), και όλες οι άλλες παράμετροι ταιριάζουν σε κάποια προηγούμενη κλήση της setcookie, τότε το cookie με το καθορισμένο όνομα θα διαγραφεί από τον απομακρυσμένο client.
Τα ονόματα των cookies μπορούν να τεθούν ως ονόματα πινάκων και θα είναι διαθέσιμα στα PHP scripts σας ως πίνακες αλλά ξεχωριστά cookies αποθηκεύονται στο σύστημα των χρηστών. Θεωρείστε την explode() ή την serialize() για να θέσετε ένα cookie με πολλαπλά ονόματα και τιμές.
Στην PHP 3, οι πολλαπλές κλήσεις της setcookie() στο ίδιο script θα εκτελεστούν με αντίθετη σειρά. Αν προσπαθήσετε να διαγράψετε ένα cookie πριν προσθέσετε άλλο θα πρέπει να τοποθετήσετε την εισαγωγή προν την διαγραφή. Στην PHP 4, οι πολλαπλές κλήσεις στην setcookie() εκτελούνται με τη σειρά που καλούνται.
Ακολουθούν μερικά παραδείγματα σχετικά με το πώς να στέλνετε cookies:
Σημειώστε ότι το τμήμα που περιέχει την τιμή του cookie θα γίνει αυτόματα urlencoded όταν στείλετε το cookie, και όταν αυτό παραληφθεί, αποκωδικοποιείται αυτόματα και αντίθεται σε μια μεταβλητή με το ίδιο όνομα με το όνομα του cookie. Για να δείτε τα περιεχόμενα από το δοκιμαστικό cookie μας σε ένα script, απλά χρησιμοποιήστε ένα από τα παρακάτω παραδείγματα:
<?php |
Όταν διαγράφετε ένα cookie πρέπει να ελέγχετε ότι η ημερομηνία λήξης ανήκει στο παρελθόν, και τότε να ενεργοποιείται το μηχανισμό διαγραφής στον browser σας. Ακολουθούν παραδείγματα σχετικά με τον πώς να διαφράψετε τα cookies που στάλθηκαν στον προηγούμενο παράδειγμα:
Μπορείτε επίσης να ορίσετε array cookies χρησιμοποιώντας μια σημείωση πίνακα (array notation) στο όνομα του cookie. Αυτό έχει ως αποτέλεσμα να μπορούμε να ορίσουμε όσα cookies θέλουμε αρκεί να έχουμε στοιχεία στον πίνακα, αλλά όταν το cookie λαμβάνεται από το script, οι τιμές τοποθετούνται όλες σε έναν array με το όνομα του cookie:
Óçìåßùóç: Για περισσότερες πληροφορίες στα cookies, δείτε το cookie specification της Netscape's στο http://wp.netscape.com/newsref/std/cookie_spec.html και το RFC 2965.
Ίσως παρατηρήσετε ότι η παράμετρος expire παίρνει ένα unix timestamp, σε αντίθεση με το date format Wdy, DD-Mon-YYYY HH:MM:SS GMT, αυτό συμβαίνει επειδή η PHP εκτελεί αυτή τη μετατροπή εσωτερικά.
Óçìåßùóç: Ο Microsoft Internet Explorer 4 με το Service Pack 1 δεν χειρίζεται σωστά τα cookies στα οποία έχει οριστεί η παράμετρος path.
Οι Netscape Communicator 4.05 και Microsoft Internet Explorer 3.x χειρίζονται τα cookies με μη ορθό τρόπο όταν το path και η ώρα δεν έχουν οριστεί.