Come usare le API di Gravatar: la propria immagine ovunque

Non sono il tipo che si registra a qualunque cosa su due piedi, spesso utilizzo le email da 10 minuti e via. Ma questa volta ho dovuto, per forza di cose, utilizzare uno dei miei indirizzi principali. Pensavo che me ne sarei pentito, ma mi sono dovuto ricredere!

L’essere autori di YIW richiede la registrazione a Gravatar.
Prima di allora non conoscevo questo sito e il suo ottimo servizio! Immediatamente mi è venuta l’ispirazione per scrivere questa utilissima classe. Ti mostrerò come utilizzare il tuo avatar in ogni tuo sito o blog con poche righe di codice. Ma iniziamo dalle basi, cos’è un gravatar e come lo si ottiene?

Cos’è un Gravatar?

Cito dal sito gravatar.com

“Un Gravatar è una immagine che ti segue di sito in sito ed appare accanto al tuo nome quando fai qualche cosa come commentare o scrivere su un blog. Gli avatar ti aiutano ad identificare i tuoi commenti sui blog e sui forum web, quindi perchè non su ogni sito?”

In poche parole, un avatar è la tua immagine personale, l’immagine che ti identifica, l’immagine che più ti rispecchia.

Un Gravatar invece è un avatar riconosciuto globalmente su moltissimi siti e blog grazie al servizio offerto dai geni che l’hanno inventato.

Come ottenere il tuo gravatar

Inizia con il visitare il sito www.gravatar.com al quale dovrai registrarti.

Pagina di registrazione al sito Gravatar.com

Pagina di registrazione al sito Gravatar.com

Dopo esserti registrato, riceverai un’email di conferma e successivamente potrai impostare la tua password.

Se tutto è andato bene, dovresti essere in grado di impostare tutte le tue informazioni personali e l’immagine da utilizzare come gravatar.

Si ok, ma a cosa mi serve?

Ora puoi portarti in giro il tuo gravatar semplicemente con un link.

Certo, puoi farlo anche caricando l’immagine su altri siti, ma il concetto non è lo stesso.

Abbiamo detto che i gravatar sono riconosciuti globalmente. Prova a registrarti e a commentare un articolo anche qui su YIW.

Nel commento, potrai inserire il tuo nome, il tuo indirizzo email (che dovrà essere quello a cui hai associato il tuo gravatar) e il tuo sito web.

Una volta pubblicato il commento, vedrai che il tuo gravatar comparirà “magicamente” accanto al commento, al posto di quel brutto omino grigio e anonimo. La cosa bella è che se un domani cambierai il gravatar associato al tuo indirizzo email, questo cambierà automaticamente anche in tutti i posti dove è stato utilizzato, compresi quelli precedenti al cambiamento.

Utilizzare il proprio gravatar davvero ovunque

Ovviamente noi non ci accontentiamo solo di questo e i creatori di Gravatar lo sanno.

Hanno messo a disposizione degli sviluppatori delle API per poter utilizzare il loro servizio anche sul nostro sito personale ad esempio.

Ed ecco il perchè di questo articolo. Ho creato per te la classe Gravatar che potrai utilizzare per tutti i tuoi esperimenti (e perchè no, anche in produzione) con questo ottimo servizio.
Iniziamo a scriverne il codice.

class Gravatar {
	public $useSSL;
	public $imgWrapper;
	public $forceDef;
	private $_email;
	private $_size;
	private $_default;
	private $_rating;
	private $_extras;

	public function __construct($email = FALSE) {
		$this->useSSL = false;
		$this->imgWrapper = false;
		$this->forceDef = false;

		$this->_size = 80;
		$this->_default = 'mm';
		$this->_rating = NULL;
		$this->_extras = '';

		if(!empty($email)) {
			$email = trim(strtolower($email));
			$email = $this->_isValidEmail($email) ? $email : FALSE;
		}

		$this->_email = $email;
	}
}

Ecco qui le proprietà della classe:

  • $useSSL: Gravatar mette a disposizione l’utilizzo del protocollo HTTPS per ottenere il proprio gravatar. Se vuoi puoi utilizzarlo, altrimenti verrà utilizzato il protocollo HTTP.
  • $imgWrapper: Puoi scegliere se farti restituire dalla classe soltanto il link al tuo gravatar o direttamente il tag <img /> settato a dovere.
  • $forceDef: Puoi forzare l’utilizzo dell’immagine di default (vedi $_default).
  • $_email: L’indirizzo email associato al tuo gravatar.
  • $_size: Le dimensioni in cui vuoi che ti venga restituito il tuo gravatar.
  • $_default: Nel caso non sia associato nessun gravatar all’indirizzo email fornito, Gravatar restituirà un’immagine di default. Ce ne sono di diversi tipi:
    • ‘404’ indica di non restituire nessun immagine.
    • ‘mm’ indica di restituire l’omino con sfondo grigio.
    • ‘identicon’ indica di restituire un disegno geometrico creato in base all’hash dell’email.
    • ‘monsterid’ indica di restituire l’immaginetta di un mostriciattolo creato automaticamente.
    • ‘wavatar’ invece è una faccina generata dinamicamente da gravatar
    • ‘retro’ è una faccina ma in formato old school ad 8bit.
  • $_rating: quando associerai un’immagine al tuo indirizzo email ti verrà chiesto di indicare di che tipo di immagine si tratta:
    • ‘g’ indica un’ immagine utilizzabile su ogni tipo di sito.
    • ‘pg’ è un’immagine che contiene gesti volgari, individui vestiti in modo provocatorio, parole volgari o violenza.
    • ‘r’ indica intensa violenza, blasfemia, nudità o utilizzo di droghe.
    • ‘x’ significa che l’immagine è a sfondo sessuale o violenza estrema.
  • $_extras: viene utilizzato solo nel caso $imgWrapper sia settato a TRUE. Contiene un array associativo che viene usato per aggiungere attributi extra al tag <img /> come ad esempio gli attributi title, id, class ecc…
Vari tipi di Gravatar

Vari tipi di Gravatar

Il costruttore della classe non fa altro che settare i valori di default di queste proprietà. Nel caso venga invocato passandogli un indirizzo email, ne controlla la validità e lo imposta come predefinito.

Successivamente ci sono tutti i setter della classe. Servono a impostare tutte queste proprietà con i valori che vogliamo noi. Non li analizzerò in dettaglio perchè non fanno altro che effettuare controlli di sicurezza sulla validità dei dati immessi, ma nel file di download sono ampiamente documentati.

/* … */
	public function setEmail($email) {
		if(!empty($email)) {
			$email = trim(strtolower($email));
			$email = $this->_isValidEmail($email) ? $email : FALSE;

			$this->_email = $email;
		}

		return (bool) $email;
	}

	public function setDefault($d) {
		$allowed = array('mm', '404', 'identicon', 'monsterid', 'wavatar', 'retro');
		$d = trim(strtolower($d));

		if(in_array($d, $allowed)) {
			$this->_default = $d;
			return true;
		}

		return false;
	}

	public function setSize($s) {
		if(is_int($s)) {
			if($s > 0 AND $s < 513) {
				$this->_size = $s;
				return true;
			}
		}

		return false;
	}

	public function setRating($r) {
		$allowed = array('g', 'pg', 'r', 'x');
		$r = trim(strtolower($r));

		if(in_array($r, $allowed)) {
			$this->_rating = $r;
			return true;
		}

		return false;
	}

	public function setExtras($params) {
		if(is_array($params)) {
			$extras = '';

			foreach($params as $key => $value) {
				$extras .= trim(strtolower($key)) . '="' . trim($value) .'" ';
			}

			$this->_extras = $extras;
			return true;
		}

		return false;
	}
/* … */

Un metodo interessante è quello utilizzato per controllare la validità dell’email sia nel costruttore che nel metodo setEmail():

private function _isValidEmail($email) {
    return preg_match('/^[\w.-]+(\+[\w.-]+)*@\w+[\w.-]*?\.\w{2,4}$/', $email);
}

Utilizza un’espressione regolare per controllare la validità dell’indirizzo email.

So bene che potrebbero risultare validi alcuni indirizzi email che non lo sono, ma scrivere un’espressione regolare che verifichi solo gli indirizzi realmente validi è dannatamente complicato!

Anche seguendo gli standard RFC 2822 verranno validati indirizzi email che effettivamente nessun provider permette di utilizzare. Ma vi posso assicurare che la maggior parte di indirizzi non validi, vengono riconosciuti.

Se non dovessi essere contento dei risultati di questa espressione, su regular-expressions.info e regexlib.com ce ne sono di molte altre, ti basta sceglierne una e sostituirla a quella del metodo _isValidEmail().

Richiesta del gravatar

Abbiamo scritto quasi tutta la classe, resta soltanto il metodo per effettuare la richiesta del gravatar al sito web.

public function getGravatar() {
    $url  = $this->useSSL ? 'https://' : 'https://';
    $url .= 'www.gravatar.com/avatar/';

    if(!$this->_email) {
        return false;
    }

    $url .= md5($this->_email);
    $url .= '?s=' . $this->_size;
    $url .= '&d=' . $this->_default;

    if(!empty($this->_rating)) {
        $url .= '&r=' . $this->_rating;
    }

    if($this->forceDef) {
        $url .= '&f=y';
    }

    if($this->imgWrapper) {
        $gravatar  = '';
        $gravatar .= '<img src="' . $url .'" ' . $this->_extras . '/>';

        return $gravatar;
    } else {
        return $url;
    }
}

public function __toString() {
    return $this->getGravatar();
}

Nel metodo getGravatar(), come prima cosa controlliamo che tipo di protocollo hai scelto di utilizzare. Successivamente controlliamo se l’utente ha inserito un indirizzo email valido, altrimenti restituiamo FALSE.

Se fin qui è tutto ok, Gravatar richiede che l’email sia codificata in MD5. Detto fatto. Codifichiamola con la funzione nativa di PHP e la aggiungiamo all’URL di Gravatar.

Dopodichè possiamo aggiungere tutti i parametri aggiuntivi quali dimensione del gravatar, immagine di default, rating e la restituzione forzata dell’immagine di default.

A questo punto, la richiesta del gravatar è completa. Ma noi abbiamo aggiunto un ulteriore controllo. Se volessi ottenere direttamente un tag <img /> con il link già inserito, puoi farlo settando la proprietà $imgWrapper, come già detto. Qui facciamo esattamente questo.

Controlliamo se questa variabile sia stata impostata e, nel caso, includiamo il link del gravatar in un tag <img /> aggiungendo eventuali parametri extra.

Il metodo __toString() invece, è un metodo magico che ci permette di specificare cosa fare nel caso venga effettuato un echo() della classe stessa:

$gravatar = new Gravatar();
echo $gravatar; //Qui viene invocato automaticamente il metodo __toString()

Conclusioni

Oggi abbiamo conosciuto un servizio veramente utile che è quello offerto da Gravatar.com ed abbiamo scritto un’ottima classe per utilizzarlo. Nel file allegato all’articolo è presente anche un esempio per l’utilizzo della classe (per la vostra felicità ho usato il mio gravatar nell’esempio).

Download

Conoscevi già Gravatar prima d’ora? In che tipologia di progetti pensi possa tornare utile?

Tag: , ,

L'autore

Sviluppo per il web da alcuni anni. Ultimamente mi sono specializzato in WordPress tramite Your Inspiration, con il quale attualmente lavoro nell'area di supporto clienti e sviluppo temi e plugin per WP.

Sito web dell'autore | Altri articoli scritti da

Articoli correlati

30 commenti

Trackback e pingback

Non ci sono trackback e pingback disponibili per questo articolo