setcookie
(PHP 4, PHP 5, PHP 7, PHP 8)
setcookie — Bir çerez gönderir
Açıklama
Çerezler bir kere atandı mı, artık $_COOKIE dizisi ile
sonraki sayfa yüklemesinde erişilebilir olacaktır. Çerez
değerleri ayrıca, $_REQUEST içinde de mevcut olabilir.
Bağımsız Değişkenler
setcookie() bağımsız değişkenlerinin her birinin nasıl
çalıştığını hakkında bilgi edinmek için bkz:
» RFC 6265
isim
-
Çerezin ismi.
değer
-
Çerezin değeri. Bu değer istemcinin bilgisayarında saklanır. Bu
bakımdan çerezlerde güvenlik ihlaline konu bilgiler saklanmamalıdır.
isim
bağımsız değişkeninde
'çerezim'
isminin kullanıldığı varsayımıyla, bu
çerezin değeri $_COOKIE['çerezim'] değişkeni ile
alınabilir.
süreler_veya_seçenekler
-
Çerezin zaman aşımına uğrama süresi. Değer bir Unix zaman damgasıdır.
Bu değeri elde etmenin tek yolu, time() işlevinden
dönen değere çerezin zaman aşımına uğrayacağı süreyi saniye cinsinden
eklemektir. Örneğin, time()+60*60*24*30
ile çerez 30 gün sonra zaman aşımına uğrar. Ayrıca,
mktime() işlevi de kullanılabilir. Burada 0
atanır veya birşey belirtilmezse, çerez oturumun sonunda (tarayıcı
kapandığında) zaman aşımına uğrar.
Bilginize:
süreler_veya_seçenekler
bağımsız değişkeni
değer olarak bir Unix zaman damgası alır. Bu,
başlıkta belirtilen Wdy, DD-Mon-YYYY HH:MM:SS GMT
tarih biçeminin zıddı olup bu dönüşümü PHP dahili olarak yapar.
yol
-
Çerezin üzerinde etkin olacağı sunucudaki yol. '/'
belirtilirse çerez alan
'ın tamamında
kullanılabilir olacaktır. Eğer '/foo/'
belirtilirse, çerez sadece /foo/
dizininde ve
/foo/bar/
gibi alt dizinlerde kullanılabilir
olacaktır. Öntanımlı değer çerezin atandığı içinde bulunulan dizindir.
alan
-
Çerezin kullanılabileceği (alt)alan. Çerezi
('www.example.com'
gibi) bir alt alan adında
kullanılabilir yapmak onu tüm diğer alt alan adlarında da
(w2.www.example.com gibi) kullanılabilir kılacaktır. Çerezi tüm alt alan
adlarında kullanılabilir yapmak için buraya alan adı (örneğimiz için
('example.com'
) yazılmalıdır.
Eski tarayıcılar hala kullanımdan kalkmış olan ve alt alan adıyla
eşleşme sağlamak için . ile başlatmayı gerektiren » RFC 2109'u gerçeklemektedir.
güvenli
-
Çerezin istemciye güvenli bir HTTPS bağlantısı üzerinden mi
aktarılması gerektiğini belirtmek için kullanılır. true
belirtildiği
takdirde, çerez sadece güvenli bağlantı mevcutsa gönderilecektir.
Sunucu tarafında, bu çeşit çerezin sadece
($_SERVER["HTTPS"] ile ilgili) güvenli bağlantı
üzerinden gönderilmesi kararı yazılımcıya aittir.
sadece_http
-
true
olduğu takdirde çerez sadece HTTP protokolü üzerinden
erişilebilir olacaktır. Yani çerez, JavaScript gibi betik dilleri
tarafından erişilebilir olmayacaktır. Bu ayarlama, XSS saldırılarıyla
kimlik hırsızlığı riskini etkin şekilde azaltmaya (tüm tarayıcılar
tarafından desteklenmese de) yardımcı olabilir, fakat bu sava çoğunlukla
itiraz edilir. Değer olarak true
veya false
belirtilebilir.
seçenekler
-
zaman_aşımı
, yol
,
alan
, güvenli
,
sadece_http
ve samesite
bağımsız değişkenlerinden herhangi birine sahip olabilen ilişkisel bir
dizi. Bunlar dışında bir anahtar varsa, E_WARNING
seviyesinde bir hata üretilir. Değerler, aynı ada sahip bağımsız
değişkenler için açıklananla aynı anlama sahiptir.
samesite
öğesinin değeri None
,
Lax
veya Strict
olmalıdır. İzin
verilen seçeneklerden herhangi biri belirtilmezse, bunların öntanımlı
değerleri, açık bağımsız değişkenlerin öntanımlı değerleri ile aynıdır.
samesite
öğesi atlanırsa, SameSite çerez özelliği
ayarlanmaz.
Bilginize:
Listelenen anahtarlar arasında olmayan öznitelikleri içeren bir çerez
belirtmek için header() işlevi kullanılır.
Dönen Değerler
Bu işlev çağrılmadan önce yapılmış çıktı varsa
setcookie() başarısız olup false
döndürür.
setcookie() başarılı olduğu takdirde true
döndürür.
Dönüş değeri, kullanıcının çerezi kabul ettiği ya da etmediği anlamına
gelmez.
Örnekler
Çerez gönderimi ile ilgili bazı örnekler:
Örnek 1 - setcookie() gönderim örneği
<?php
$value = 'bir şeyler bir yerlere';
setcookie("TestCookie", $value);
setcookie("TestCookie", $value, time()+3600); /* 1 saatliğine geçerli */
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", true);
?>
Çerez gönderilirken çerez değerinin otomatik olarak URL kodlamasından
geçirileceğine, alınırken ise bu kodlamanın yine otomatik olarak
çözüleceğine ve yine aynı çerez ismine atanacağına dikkat ediimalidir. Bu
istenmiyorsa, Bu işlevin yerine
setrawcookie() işlevi kullanılabilir. Deneme
çerezimizin bir betik içindeki değerini görmek için aşağıdaki örneklerden
biri kullanılabilir:
Örnek 2 - setcookie() silme örneği
Bir çerezi silerken, tarayıcının yürürlükten kaldırma mekanizmasını
tetikleyebilmek için, süre bitiminin geçmişte kalmasını sağlamanız
gerekir. Önceki örnekte gönderilen çerezin silinmesi:
<?php
// süre bitimini 1 saat önceye ayarla
setcookie ("TestCookie", "", time() - 3600);
setcookie ("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);
?>
Örnek 3 - setcookie() ve diziler
Çerez ismini belirtirken dizi gösterimini kullanmak suretiyle çerez
dizileri tanımlanabilir. Bu sayede dizi elemanı sayısı kadar çerez
tanımlanabilir, fakat çerezler betikle alındığında değerlerin
hepsi çerez isminde bir diziye yerleştirilir:
<?php
// çerezleri tanımla
setcookie("cookie[three]", "cookiethree");
setcookie("cookie[two]", "cookietwo");
setcookie("cookie[one]", "cookieone");
// sayfayı yeniden yükledikten sonra çerezler bas
if (isset($_COOKIE['cookie'])) {
foreach ($_COOKIE['cookie'] as $name => $value) {
$name = htmlspecialchars($name);
$value = htmlspecialchars($value);
echo "$name : $value <br />\n";
}
}
?>
Yukarıdaki örneğin çıktısı:
three : cookiethree
two : cookietwo
one : cookieone
Bilginize:
Çerez isminin paraçası olarak [
ve ]
gibi ayırıcı karakterlerin kullanımı RFC 6265, bölüm 4 ile uyumlu değildir,
fakat RFC 6265, bölüm 5'e göre kullanıcı istemcileri tarafından
desteklendikleri varsayılmıştır.
Notlar
Bilginize:
Bu işlevi çağırmadan önce, tarayıcıya gönderilene
kadar sunucuda bekletilmek üzere çıktı bir tampona yazılabilir. Bu
işlem, betikten ob_start() ve
ob_end_flush() işlevlerini çağırarak veya
output_buffering
yapılandırma
yönergesi php.ini veya sunucu yapılandırma dosyalarında belirtilerek
yapılabilir.
Bilinen Güçlükler:
-
Çerezler sonraki sayfada görünür olmak üzere atanırlar, dolayısıyla
sonraki sayfa yüklenene kadar görünür olmazlar. Bir çerezin başarıyla
tanımlanıp tanımlanmadığını anlayabilmek için çerez zaman aşımına
uğramadan sonraki sayfa üzerinde çerez denenmelidir. Zaman aşımı
süresi
zaman_aşımı
bağımsız değişkeni ile
belirtilebilir. Bir çerezin varlığını sınamanın en kolay yolu
print_r($_COOKIE);
çağrısı yapmaktır.
-
Çerezler atandıkları sırada kullanılan bağımsız değişkenler kullanılarak
silinmelidir.
değer
bağımsız değişkeninde bir boş
dizge belirtilir ve tüm diğer bağımsız değişkenlerin çerezi atarken
kullanılan bağımsız değişkenlerle aynı olması sağlanırsa, ismi
belirtilen çerez uzak istemciden silinir. Bu işlem dahili olarak
çereze 'deleted'
değeri atanarak ve zaman aşımı
tarihi bir yıl önceye çekilerek gerçekleştirilir.
-
Bir çereze silmek amacıyla
false
değeri atanırken mantıksal değerler
kullanılmamalıdır. false
için 0, true
için
1 kullanılmalıdır.
-
Çerez isimleri dizi isimleri olabilir. Böylece PHP betiğinde bu
çerezler için dizi kullanılırken, kullanıcının sisteminde bunlar ayrı
ayrı çerezler olarak saklanırlar. Tek bir çereze çok sayıda isim ve
değer atamak için explode() işlevi
kullanılabilir. Güvenlik zafiyeti oluşturması nedeniyle bu işlem
için serialize() işlevinin kullanılması
önerilmemektedir.
Peşpeşe pek çok setcookie() çağrısı yapılabilir.