esc_url() | Fonctions Wordpress

Description

Certains caractères peuvent alors être supprimés de l'URL. Si l'URL est affichée (comportement par défaut), les esperluettes (&) seront aussi remplacées.
Le filtre 'clean_url' est appliqué à la valeur de sortie.

Protocoles acceptés : http, https, ftp, ftps, mailto, news, irc, gopher, nntp, feed, et telnet.

Paramètres

$url

(string) (Requis) L'URL à nettoyer.

$protocols

(string[]) (Optionnel) Un tableau de protocoles acceptables. Par défaut, la valeur retournée de wp_allowed_protocols().

Valeur par défaut : null

$_context

(string) (Optionnel) Privé. Utilise esc_url_raw() pour un usage en base de donnée.

Valeur par défaut : 'display'

Retourne

(string) L'URL nettoyée après que le filtre 'clean_url' ait été appliqué. Une chaîne vide est retournée si $url spécifie un autre protocole que ceux proposés, ou si $url est chaîne vide.

Structure de la fonction `esc_url()`

Définie dans le fichier wp-includes/formatting.php à la ligne 4330 :

function esc_url( $url, $protocols = null, $_context = 'display' ) {
    $original_url = $url;

    if ( '' === $url ) {
        return $url;
    }

    $url = str_replace( ' ', '%20', ltrim( $url ) );
    $url = preg_replace( '|[^a-z0-9-~+_.?#=!&;,/:%@$\|*\'()\[\]\\x80-\\xff]|i', '', $url );

    if ( '' === $url ) {
        return $url;
    }

    if ( 0 !== stripos( $url, 'mailto:' ) ) {
        $strip = array( '%0d', '%0a', '%0D', '%0A' );
        $url   = _deep_replace( $strip, $url );
    }

    $url = str_replace( ';//', '://', $url );
    /*
     * If the URL doesn't appear to contain a scheme, we presume
     * it needs http:// prepended (unless it's a relative link
     * starting with /, # or ?, or a PHP file).
     */
    if ( strpos( $url, ':' ) === false && ! in_array( $url[0], array( '/', '#', '?' ), true ) &&
        ! preg_match( '/^[a-z0-9-]+?\.php/i', $url ) ) {
        $url = 'http://' . $url;
    }

    // Replace ampersands and single quotes only when displaying.
    if ( 'display' === $_context ) {
        $url = wp_kses_normalize_entities( $url );
        $url = str_replace( '&', '&#038;', $url );
        $url = str_replace( "'", '&#039;', $url );
    }

    if ( ( false !== strpos( $url, '[' ) ) || ( false !== strpos( $url, ']' ) ) ) {

        $parsed = wp_parse_url( $url );
        $front  = '';

        if ( isset( $parsed['scheme'] ) ) {
            $front .= $parsed['scheme'] . '://';
        } elseif ( '/' === $url[0] ) {
            $front .= '//';
        }

        if ( isset( $parsed['user'] ) ) {
            $front .= $parsed['user'];
        }

        if ( isset( $parsed['pass'] ) ) {
            $front .= ':' . $parsed['pass'];
        }

        if ( isset( $parsed['user'] ) || isset( $parsed['pass'] ) ) {
            $front .= '@';
        }

        if ( isset( $parsed['host'] ) ) {
            $front .= $parsed['host'];
        }

        if ( isset( $parsed['port'] ) ) {
            $front .= ':' . $parsed['port'];
        }

        $end_dirty = str_replace( $front, '', $url );
        $end_clean = str_replace( array( '[', ']' ), array( '%5B', '%5D' ), $end_dirty );
        $url       = str_replace( $end_dirty, $end_clean, $url );

    }

    if ( '/' === $url[0] ) {
        $good_protocol_url = $url;
    } else {
        if ( ! is_array( $protocols ) ) {
            $protocols = wp_allowed_protocols();
        }
        $good_protocol_url = wp_kses_bad_protocol( $url, $protocols );
        if ( strtolower( $good_protocol_url ) != strtolower( $url ) ) {
            return '';
        }
    }

    /**
     * Filters a string cleaned and escaped for output as a URL.
     *
     * @since 2.3.0
     *
     * @param string $good_protocol_url The cleaned URL to be returned.
     * @param string $original_url      The URL prior to cleaning.
     * @param string $_context          If 'display', replace ampersands and single quotes only.
     */
    return apply_filters( 'clean_url', $good_protocol_url, $original_url, $_context );
}

Fonctions et Hook utilisés par `esc_url()`

wp_parse_url(): Fonction qui englobe la fonction php parse_url() et qui apporte de la cohérence en fonction des versions php.
_deep_replace(): Exécute une profonde opération de remplacement sur $url pour s'assurer que les valeurs à chercher ne soient plus présentes.
clean_url: Filtre une URL nettoyée et échappée.
wp_kses_normalize_entities(): Convertit et répare les entités HTML d'une chaîne.
wp_kses_bad_protocol(): Nettoie une chaîne et supprime les protocoles URL non permis.
wp_allowed_protocols(): Retourne une liste de protocoles autorisés dans des attributs HTML.
apply_filters(): Appel les fonctions qui ont été attaché à un filtre (hook).

Où trouver la fonction `esc_url()` dans le CMS Wordpress

Exemples

<a href=" echo esc_url( home_url( '/' ) ); ?>">Home</a>

Étendre la liste des protocoles :

function wporg_extend_allowed_protocols( $protocols ){
    $protocols[] = 'skype';
    $protocols[] = 'spotify';
    $protocols[] = 'macappstores';
    return $protocols;
}
add_filter( 'kses_allowed_protocols' , 'wporg_extend_allowed_protocols' );

Sources

Codex Wordpress : esc_url()

Autres fonctions dans le même fichier : wp-includes/formatting.php

Retour