esc_url în WordPress

esc_url( string $url, string[] $protocols = null, string $_context = 'display' ): string

Ce face esc_url

esc_url() (din WordPress 2.8.0) verifică protocolul adresei față de lista permisă (implicit cea din wp_allowed_protocols(): http, https, ftp, ftps, mailto, news, irc, gopher, nntp, feed, telnet și altele). Dacă protocolul nu e permis, de exemplu javascript:, întoarce un șir gol. În contextul de afișare, & și apostroful devin & și '.

Dacă adresa nu are protocol și nu începe cu /, # sau ?, funcția adaugă http:// în față. Din WordPress 6.9 adaugă https:// dacă primul element din $protocols este 'https'. Adresele relative și ancorele rămân neschimbate.

Pentru salvare în baza de date sau pentru redirecționări nu folosi esc_url(), ci sanitize_url() sau aliasul ei esc_url_raw() (din 6.1.0 esc_url_raw() doar apelează sanitize_url()): acestea nu transformă & în entitate.

Parametri

Parametru	Descriere
$url	Adresa de curățat.
$protocols	Lista protocoalelor permise, de exemplu array( 'https' ). Implicit lista din wp_allowed_protocols().
$_context	Parametru privat, implicit 'display'; nu îl folosi. Pentru baza de date există sanitize_url().

Ce returnează

Adresa curățată sau un șir gol dacă protocolul nu este permis ori adresa e goală.

Exemple

Exemplul 1: Link cu parametri în query string

Caracterul & dintre parametri devine & în HTML, iar browserul îl citește corect.

<?php
$link = 'https://exemplu.ro/cauta?produs=cafea&oras=Iasi';
echo '<a href="' . esc_url( $link ) . '">Cafea în Iași</a>';

Ce afișează pagina

<a href="https://exemplu.ro/cauta?produs=cafea&#038;oras=Iasi">Cafea în Iași</a>

Exemplul 2: Un link javascript: este eliminat

Adresa site-ului din profilul unui utilizator conține javascript:; esc_url() întoarce șir gol, deci linkul nu mai face nimic.

<?php
$site = 'javascript:alert(document.cookie)';
echo '<a href="' . esc_url( $site ) . '">Site-ul lui Mihai</a>';

Ce afișează pagina

<a href="">Site-ul lui Mihai</a>

Exemplul 3: Salvarea unei adrese cu sanitize_url()

La salvare folosim sanitize_url(), care păstrează & ca atare; esc_url() îl folosim doar la afișare.

<?php
if ( isset( $_POST['dex_site'] ) ) {
    $site = sanitize_url( wp_unslash( $_POST['dex_site'] ) );
    update_option( 'dex_site_partener', $site );
}

Greșeli frecvente

• esc_url() înainte de wp_redirect() sau de salvare: & ajunge în adresă și o strică. Folosește sanitize_url() / esc_url_raw().
• esc_html() sau esc_attr() pe un href: nu verifică protocolul, deci javascript: trece.
• Să construiești adrese prin concatenare cu valori nevalidate: pentru parametri folosește add_query_arg() și apoi esc_url() la afișare.

Comenzi înrudite

• esc_attr: Escapează o valoare pentru un atribut HTML (value, title, alt, data-*), ca ghilimelele să nu închidă atributul.
• esc_html: Escapează textul pentru afișare în HTML: transformă < > & și ghilimelele în entități, ca să nu fie interpretate ca cod.
• check_admin_referer: Verifică nonce-ul unei cereri din administrare și oprește execuția cu o pagină de eroare dacă e invalid sau a expirat.