Dopo aver introdotto il lettore al web service proposto da Flickr, e alla classe phpFlickr che ci consente di utilizzarlo, è il momento di approfondire l'argomento per scoprire altre funzionalità interessanti di questo servizio. Naturalmente rimane valido tutto quando già descritto nella prima parte dell'articolo, per quanto riguarda gli strumenti necessari, l'uso della chiave API fornita da Flickr, la sintassi delle funzioni implementate da phpFlickr e tutti gli altri dettagli. Come già accennato, per accedere ad alcune funzionalità è necessaria una procedura di autenticazione, mentre per altre l'accesso è libero. Nei prossimi paragrafi tratteremo anche questo aspetto.
Cercare un utente
Nel primo esempio proposto nella parte precedente dell'articolo, abbiamo effettuato una ricerca all'interno dell'archivio pubblico. Potrebbe essere interessante circoscrivere la ricerca all'interno delle foto pubblicate da un determinato utente, ma per fare ciò sono necessarie due condizioni: per prima cosa dobbiamo conoscere il suo identificativo (user_id), ma soprattutto è l'utente stesso che ha la facoltà di impostare le proprie opzioni sulla privacy, scegliendo di non essere incluso nelle ricerche pubbliche.
Non avendo ovviamente il controllo su questa seconda condizione, a meno di essere noi stessi l'oggetto della ricerca, ci concentriamo sul primo aspetto, ossia scoprire lo user_id di un utente. Il web service ci mette a disposizione due funzioni adatte allo scopo, ossia flickr.people.findByUsername e flickr.people.findByEmail, che vengono implementate dalle omonime funzioni della classe. Proponiamo un esempio di ricerca per username, considerando che la ricerca per indirizzo e-mail funziona in modo sostanzialmente identico:
<?php
$api_key = 'mia-api-key';
require_once('phpflickr/phpFlickr.php');
$flickr = new phpFlickr($api_key);
if (isset($_POST['submit'])) {
$result = $flickr->people_findByUsername($_POST['cerca']);
// Gestione dei risultati
echo '<pre>'; print_r($result); echo '</pre>';
}
echo '
<form method="post">
Cerca utente per username: <input type="text" name="cerca" />
<input type="submit" name="submit" value="Cerca" />
</form>';
?>Questo esempio stampa a video un semplice modulo che consente di inserire lo username dell'utente che stiamo cercando. Il dato inserito viene passando come parametro alla funzione people_findByUsername() della classe phpFlickr, la quale restituisce un array associativo se l'utente viene trovato, oppure false in caso contrario (l'utente non esiste, o il suo profilo è privato). Da notare che la ricerca per indirizzo e-mail funziona allo stesso modo, sostituendo la funzione people_findByUsername() con people_findByEmail().
Il risultato, con entrambe le tipologie di ricerca, sarà quindi un array associativo contenente tre campi:
- nsid, l'identificativo dell'utente, usato anche per costruire gli indirizzi del profilo e degli album come proposto nella prima parte dell'articolo;
- id, l'identificativo dell'utente, usato internamente da Flickr, che per i nostri scopi può essere ignorato e che spesso è uguale al campo nsid;
- username, lo username dell'utente.
Cercare le foto di un determinato utente
Il passo successivo, una volta ottenuto l'identificativo dell'utente che stiamo cercando, potrebbe essere quello di cercare le foto da lui pubblicate. In questo caso potrebbero esserci due possibilità: la funzione people_getPublicPhotos(), oppure la funzione photos_search() già usata nella prima puntata di questo articolo.
<?php
$api_key = 'mia-api-key';
require_once('phpflickr/phpFlickr.php');
$flickr = new phpFlickr($api_key);
if (isset($_POST['submit'])) {
$user = $flickr->people_findByUsername($_POST['cerca']);
if ($user) {
$photos = $flickr->people_getPublicPhotos($user['nsid']);
// Gestione dei risultati
echo '<pre>'; print_r($photos); echo '</pre>';
}
}
echo '
<form method="post">
Cerca utente per username: <input type="text" name="cerca" />
<input type="submit" name="submit" value="Cerca" />
</form>';
?>Il form di questo esempio è riciclato da quello precedente: inserendo il nome dell'utente, la chiamata a people_findByUsername() va a creare l'array $user, che sfruttiamo subito dopo come parametro di people_getPublicPhotos().
Il blocco di codice che effettua la ricerca potrebbe essere sostituito dal seguente, del tutto analogo:
if (isset($_POST['submit'])) {
$user = $flickr->people_findByUsername($_POST['cerca']);
if ($user) {
$param = array(
'user_id' => $user['nsid'],
);
$photos = $flickr->photos_search($param);
// Gestione dei risultati
echo '<pre>'; print_r($photos); echo '</pre>';
}
}In questo caso il vantaggio di usare photos_search() potrebbe derivare dall'uso di altri parametri di ricerca, ad esempio per gestire la paginazione, come è stato accennato nella puntata precedente. In entrambi i casi il risultato della ricerca è l'array associativo già descritto nel precedente articolo.
Il processo di autenticazione
Alcune funzioni del servizio, come abbiamo visto finora, sono fruibili senza autenticazione, principalmente quando si tratta di accedere in lettura a dati che sono comunque pubblici, ma per poter usufruire a pieno di tutte le funzionalità dell'API è necessario in alcuni casi effettuare una qualche forma di autenticazione. La procedura può risultare inizialmente macchinosa, per cui prima di utilizzarla cercheremo di descriverla in breve.
Vengono proposte tre differenti tipologie di autenticazione:
- autenticazione web, il nostro caso, che richiede all'utente che naviga sulla nostra applicazione di autenticarsi presso Flickr;
- autenticazione desktop, utilizzata per le applicazioni di tipo desktop, in cui le credenziali dell'utente vengono memorizzate dall'applicazione;
- autenticazione mobile, utilizzata dalle applicazioni pensate per i dispositivi mobili.
Il processo di autenticazione web è il caso che ci interessa. Quando l'applicazione richiede l'utilizzo di una funzione che necessita di autenticazione, l'utente viene dirottato su una pagina di login di Flickr (a meno che non abbia già effettuato tale login nella stessa sessione di navigazione). Dopo l'autenticazione su Flickr, il sistema chiede all'utente in che modo è arrivato su tale pagina (una sorta di precauzione contro il phishing) per assicurarsi che l'utente stesso stia autorizzando l'applicazione in modo consapevole. L'ultimo passo consiste nel riassumere i privilegi di accesso che vengono richiesti dall'applicazione: se l'utente fornisce la conferma, viene riportato sulla nostra applicazione.
Affinché la procedura vada a buon fine, è necessario a monte configurare la nostra applicazione in modo adeguato. Dalla pagina con l'elenco delle proprie chiavi API, possiamo modificarne i dettagli: il titolo e la descrizione dell'applicazione sono importanti per far capire all'utente di cosa si sta parlando; allo stesso modo, le note sull'applicazione devono essere dettagliate per consentire allo staff di Flickr di effettuare delle verifiche sulla nostra applicazione; infine, è importante impostare il tipo di autenticazione (Applicazione Web) e l'URL di richiamata, ossia l'indirizzo di ritorno verso cui l'utente viene mandato dopo che ha effettuato il login su Flickr.
Assumiamo che tale indirizzo sia nella forma: http://www.mio-sito.xyz/auth.php dove auth.php è uno script fornito dal pacchetto phpFlickr, che ci semplifica notevolmente la stesura del codice.
Dal punto di vista del nostro codice, è infatti sufficiente inserire due piccole modifiche:
- Indicare la stringa del "segreto condiviso" come secondo parametro del costruttore della classe;
- Invocare, prima di chiamare qualsiasi altra funzione, il metodo
phpFlickr::auth()indicando il tipo di permesso richiesto.
Le tipologie di permessi possibili sono tre:
- read, ossia il permesso in sola lettura;
- write, ossia il permesso in sola scrittura;
- delete, ossia la possibilità di cancellare informazioni.
Nella documentazione ufficiale di Flickr, per ogni funzione viene indicato se è necessaria l'autenticazione ed eventualmente quale tipologia di permesso è richiesta. I tre permessi sono in ordine di importanza (cioè "read" è il basilare, invece con il permesso "write", avrò anche "read", mentre se ottengo "delete" avrò in automatico tutti e tre). Una regola di buon uso consiste nel richiedere la minima autorizzazione necessaria alla nostra applicazione.
Nota: il tipo di permesso ci viene accordato dall'utente solo con il primo utilizzo dell'applicazione. Se inizialmente chiediamo il permesso "read" ed in seguito ad una successiva modifica l'applicazione richiede il permesso "write", questo ci verrà negato.
Proponiamo di seguito un semplice esempio di codice che richiede l'autenticazione:
<?php
$api_key = 'mia-api-key';
$api_secret = 'mio-segreto-condiviso';
require_once('phpflickr/phpFlickr.php');
$flickr = new phpFlickr($api_key, $api_secret);
// Richiesta autorizzazione in lettura
$flickr->auth('read');
// Lista dei contatti dell'utente autenticato
$contacts = $flickr->contacts_getList();
// Gestione dei risultati
echo '<pre>'; print_r($contacts); echo '</pre>';
?>La funzione scelta per l'esempio, contacts_getList(), richiede che venga accordato il permesso in lettura per poter accedere alla lista dei contatti personali dell'utente autenticato. Come dicevamo, le modifiche al codice riguardano la variabile $api_secret, passata come secondo parametro al costruttore di phpFlickr, e il fatto di dover richiamare la funzione auth() utilizzando 'read' come parametro. Questa chiamata verifica la necessità di effettuare il login su Flickr, ed eventualmente dirotta l'utente in tal senso. Dopo aver effettuato la procedura indicata in precedenza l'utente viene riportato all'URL iniziale, passando per il nostro script auth.php (se abbiamo indicato correttamente l'URL di ritorno).
Nota: utilizzando lo script auth.php fornito con phpFlickr, è necessario modificarlo ed impostare correttamente le variabili per la gestione della chiave API, dei percorsi dei file e del tipo di permesso richiesto.
Caricamento di una foto
Il caricamento di una foto richiede un permesso di tipo "write". Esistono sostanzialmente due tipi di permessi: sincrono e asincrono. Il primo prevede che l'applicazione, e quindi di riflesso l'utente, rimanga in attesa fino a che il caricamento non sia completato. Il secondo, invece, consente di proseguire l'esecuzione dell'applicazione senza attendere la fine del caricamento, ma richiede ovviamente di effettuare dei controlli successivi per verificare che il caricamento stesso sia andato a buon fine. Dal punto di vista del codice, il caricamento sincrono è leggermente più semplice da gestire ed è quello che proponiamo nell'esempio.
La funzione da utilizzare è sync_upload() che richiede come primo parametro, l'unico obbligatorio, il percorso del file immagine, che dovrà quindi essere presente sul nostro server. Se decidiamo di consentire all'utente il caricamento di una propria foto, potremmo decidere di salvarlo sul nostro server, utilizzando una classica procedura di upload, oppure possiamo girare il file direttamente a Flickr, sfruttando una procedura simile alla seguente:
<?php
$api_key = 'mia-api-key';
$api_secret = 'mio-segreto-condiviso';
require_once('phpflickr/phpFlickr.php');
$flickr = new phpFlickr($api_key, $api_secret);
$flickr->auth('write');
if (isset($_POST['submit'])) {
// Non ho caricato la foto
if (!isset($_FILES['foto'])) {
echo 'Non hai inserito la foto<br />';
}
else {
// Titolo e descrizione fittizi
$title = 'La mia foto';
$description = 'Foto caricata tramite Flickr API';
if ($id = $flickr->sync_upload($_FILES['foto']['tmp_name'], $title, $description)) {
echo 'Foto caricata: <a href="http://www.flickr.com/photos/me/' . $id . '">vedi</a><br />';
}
else {
echo 'Caricamento non riuscito<br />';
}
}
}
echo '<form method="post" enctype="multipart/form-data">
Carica foto: <input type="file" name="foto" />
<input type="submit" name="submit" value="Carica" />
</form>';
?>La procedura stampa un banale modulo per effettuare il caricamento della foto. Sfruttando $_FILES['foto']['tmp_name'] andiamo a pescare il file temporaneo che viene caricato sul nostro server, senza effettuarne quindi il salvataggio, e lo spediamo direttamente a Flickr. In un'applicazione reale, potremmo invece avere la necessità di salvare il file sul nostro server prima di mandarlo a Flickr. In ogni caso, la funzione sync_upload() richiede come primo parametro il percorso del file da caricare. I parametri successivi sono tutti facoltativi, e sono, nell'ordine:
- Titolo dell'immagine (stringa);
- Descrizione dell'immagine (stringa);
- Tag, ossia l'elenco di etichette separate da virgola (stringa);
- Foto pubblica, 1 se la foto è pubblica, 0 se non lo è;
- Amici, 1 se la foto è visibile agli amici, 0 se non lo è;
- Familiari, 1 se la foto è visibile ai familiari, 0 se non lo è.
La funzione restituisce false in caso di errore, oppure l'identificativo della foto appena caricata. Tramite questo identificativo, possiamo costruire l'URL della foto, che è nella forma: http://www.flickr.com/photos/me/{id_foto} dove "me" è un alias che rappresenta il nome dell'utente correttamente autenticato.
Altri spunti e conclusioni
Tutte le altre possibilità offerte dalla Flickr API sono descritte nella documentazione ufficiale. In sostanza, ogni operazione eseguibile tramite il sito, è disponibile anche tramite l'API. Ecco quindi che potremmo voler modificare i dati delle nostre foto, aggiungere o togliere tag, aggiungere riferimenti geografici e via dicendo. La lettura della documentazione ufficiale è quindi d'obbligo per avere una visione d'insieme, mentre l'uso di phpFlickr, come abbiamo visto, ci semplifica notevolmente il lavoro visto che la sintassi delle sue funzioni rispecchia la struttura offerta dall'API.
