Come creare un’applicazione PHP per Dropbox

Oggi vedremo come realizzare una semplice applicazione in PHP che ci permetta di interagire completamente con il nostro account Dropbox attraverso le API messe a disposizione dal team di sviluppo.

Le API sono state progettate in modo tale che uno sviluppatore possa abilitare gli altri utenti a collegare il proprio account con l’applicazione desiderata. Ad esempio per effettuare il backup di determinati file in modo automatico, per condividere documenti con amici o colleghi, ecc…

Per chi non lo conoscesse, Dropbox è un servizio cloud gratuito di file hosting che permette l’archiviazione e la sincronizzazione remota di qualsiasi tipo di documento attraverso le applicazioni desktop, web e mobile. Per maggiori info non esitate a visitare il sito ufficiale.

Per implementare la nostra applicazione faremo uso delle Core API disponibili per diversi linguaggi di programmazione e scripting tra cui appunto PHP.

Le Core API sono necessarie per lo sviluppo di applicazioni server-based e si differenziano dalle più semplici Drop-ins e Sync API perché includono il supporto a funzionalità avanzate come la ricerca, la revisione ed il ripristino dei file.

Registrazione Dropbox App

Per prima cosa dobbiamo registrare una nuova applicazione tramite la pagina App Console del sito di Dropbox.

Clicchiamo su Create App, selezioniamo “Dropbox API app“, scegliamo le opzioni che più ci interessano e diamogli un nome originale (come da loro suggerito).

Una volta creata, potremo cambiare le impostazioni e i dettagli tramite la seguente pagina (vedi immagine), ma quello che ci interessa per il momento sono le due stringhe alfanumeriche “App key” e “App secret”.

Installazione dell’SDK PHP

Dropbox mette a disposizione per gli sviluppatori i propri SDK per i sistemi operativi Android, iOS e OSX nonchè per linguaggi di programmazione come PHP, Java, Python e Ruby.
(Sono disponibili anche librerie di terze parti alla seguente pagina).

Scarichiamo l’archivio dalla sezione relativa a PHP e scompattiamolo dove ci capita prima.
L’SDK è contenuto nella cartella lib/ del file zip, copiamola all’interno della cartella del nostro progetto e rinominiamola in dropbox-sdk/.

Adesso non ci resta che creare il nostro file myApp.php (il nome è indifferente) e includere il file autoload.php nella nostra applicazione:

#!/usr/bin/php
<?php
require_once "dropbox-sdk/autoload.php";

Come potete vedere dal codice, cercheremo di lanciare lo script PHP direttamente da shell unix. La prima riga indica il percorso del motore PHP che eseguirà il parsing del nostro codice. Di solito il percorso di default è /usr/bin/php, ma per sicurezza controlliamolo lanciando il comando which php.

Non dimentichiamoci quindi di impostare i permessi di esecuzione al nostro file lanciando il seguente comando:

chmod 755 myApp.php

Per eseguire lo script invece basterà digitare:

./myScript.php

Se invece utilizzi Windows, elimina la prima riga e digita il comando:

php -f myApp.php

Autenticazione

Le Core API fanno uso del protocollo OAuth 2.0 che verrà utilizzato direttamente dall’SDK. Se volete approfondire il discorso vi rimando al sito ufficiale https://oauth.net/2/.

Quello che serve a noi è solo includere l’app key e l’app secret generati poco fa da Dropbox durante la registrazione della nostra app.

Possiamo utilizzare un file JSON per memorizzare questi due parametri e tenerli separati dal codice. Creiamo quindi un nuovo file chiamato config.json e incolliamo il seguente codice sostituendo le due stringhe con le nostre chiavi alfanumeriche:

{
    "key": "INSERT_APP_KEY_HERE",
    "secret": "INSERT_SECRET_HERE"
}

Salviamolo nella stessa cartella del nostro progetto ed aggiungiamo queste altre righe di codice al nostro file myapp.php:

use \Dropbox as dbx;
$appInfo = dbx\AppInfo::loadFromJsonFile("config.json");
$webAuth = new dbx\WebAuthNoRedirect($appInfo, "PHP-Example/1.0");

La classe WebAuthNoRedirect ci servirà per completare l’autenticazione con il protocollo OAuth 2.0, per accedere quindi all’account Dropbox dell’utente.

L’autenticazione avverrà in tre passi:
1. Inviare l’utente alla pagina “app approval” del sito di Dropbox.
2. Ricevere un “authorization code” da Dropbox.
3. Convertire il codice in un “access token“, il quale sarà necessario per effettuare la chiamata alle Core API.

Per prima cosa abbiamo quindi bisogno di indirizzare l’utente alla pagina di approvazione. Ricaviamo l’URL di tale pagina richiamando il metodo start.

$authorizeUrl = $webAuth->start();

Utilizziamo il codice per stampare alcune istruzioni per l’utente.

echo "1. Vai alla pagina: " . $authorizeUrl . "\n";
echo "2. Clicca su \"Consenti\" (potrebbe essere necessario effettuare il login prima).\n";
echo "3. Copia il codice di autorizzazione.\n";
$authCode = \trim(\readline("Inserisci il codice di autorizzazione qui: "));

Convertiamo infine il nostro “authorization code” (appena inserito) in un “access token“.

list($accessToken, $dropboxUserId) = $webAuth->finish($authCode);
print "Access Token: " . $accessToken . "\n";

L’access token è tutto ciò che ci serve per effettuare le richieste API per conto dell’utente in questione. Memorizzando il token di accesso, non sarà necessario ripetere questa procedura di autenticazione a meno che non venga revocato l’accesso tramite il sito web di Dropbox.

Il prossimo step sarà quello di instanziare la classe $dbxClient:

$dbxClient = new dbx\Client($accessToken, "MyApp/1.0");

Utilizziamo infine il metodo getAccountInfo per testare l’effettivo collegamento con le Core API stampando l’array contenente le informazioni relative all’utente collegato.

$accountInfo = $dbxClient->getAccountInfo();
print_r($accountInfo);

Con queste righe concludiamo la fase di autenticazione necessaria per iniziare a comunicare con Dropbox attraverso la nostra applicazione.

Di seguito invece vedremo i metodi principali per effettuare l’upload ed il download dei file.

Upload file

Prenderemo come esempio l’upload di un semplice file .txt già presente nella stessa cartella del progetto.

Per caricare il nostro file sul server dobbiamo fare uso del metodo uploadFile della classe Client.

$f = fopen("file-da-caricare.txt", "rb");
$result = $dbxClient->uploadFile("/file-su-dropbox.txt", dbx\WriteMode::add(), $f);
fclose($f);

Apriamo il nostro file con fopen e lo passiamo al metodo sopracitato insieme al percorso (ed il nome) che punta alla posizione da prendere una volta caricato su Dropbox.

Se l’operazione andrà a buon fine, uploadFile restituirà un array contenente i metadati del file appena caricato, utilizziamo print_r per stamparlo.

print_r($result);

Il risultato sarà visibile nella seguente forma:

Array
(
    [revision] => 2210172
    [rev] => 21b97c00dd2406
    [thumb_exists] =>
    [bytes] => 21
    [modified] => Thu, 31 Oct 2013 08:43:50 +0000
    [client_mtime] => Thu, 31 Oct 2013 08:43:50 +0000
    [path] => /file-su-dropbox.txt
    [is_dir] =>
    [icon] => page_white_text
    [root] => dropbox
    [mime_type] => text/plain
    [size] => 21 bytes
)

Elencare i file

Dropbox ci permette di ricavare i metadata di tutti i nostri file e delle cartelle presenti sul server. Per fare ciò dobbiamo utilizzare la chiamata getMetadataWithChildren.

$folderMetadata = $dbxClient->getMetadataWithChildren("/");

La funzione restituirà l’array con l’elenco dei file e delle cartelle relative al percorso specificato, nel nostro caso la root.

Utilizziamo sempre print_r per vedere il risultato, che sarà simile al seguente:

Array
(
    [hash] => f576eb071486e32a0a3af2e47e8983f9
    [thumb_exists] =>
    [bytes] => 0
    [path] => /
    [is_dir] => 1
    [size] => 0 bytes
    [root] => app_folder
    [contents] => Array
        (
            [0] => Array
                (
                    [revision] => 2210172
                    [rev] => 21b97c00dd2406
                    [thumb_exists] =>
                    [bytes] => 21
                    [modified] => Thu, 31 Oct 2013 08:43:50 +0000
                    [client_mtime] => Thu, 31 Oct 2013 08:43:50 +0000
                    [path] => /file-su-dropbox.txt
                    [is_dir] =>
                    [icon] => page_white_text
                    [root] => dropbox
                    [mime_type] => text/plain
                    [size] => 21 bytes
                )
        )
    [icon] => folder
)

Nell’esempio sopra vediamo le informazioni della cartella principale di Dropbox contenente il file che abbiamo appena caricato online.

Download file

Abbiamo caricato il nostro file sul server con uploadFile, abbiamo verificato l’effettiva posizione e le varie info con getMetadataWithChildren, adesso proviamo a scaricarlo nuovamente in locale, magari salvandolo con un nome diverso dal precedente.

Per fare questo usiamo la funzione getFile.

$f = fopen("working-draft.txt", "w+b");
$fileMetadata = $dbxClient->getFile("/working-draft.txt", $f);
fclose($f);

Anche questo metodo ritornerà i metadata del file relativi all’attuale revisione. Se vogliamo stamparlo aggiungiamo la reguente riga di codice:

print_r($fileMetadata);

Per ottenere questo risultato:

Array
(
    [revision] => 2210172
    [rev] => 21b97c00dd2406
    [thumb_exists] =>
    [bytes] => 21
    [modified] => Thu, 31 Oct 2013 08:43:50 +0000
    [client_mtime] => Thu, 31 Oct 2013 08:43:50 +0000
    [path] => /file-su-dropbox.txt
    [is_dir] =>
    [icon] => page_white_text
    [root] => dropbox
    [mime_type] => text/plain
    [size] => 21 bytes
)

Applicazione demo

Come suggerito da Marco nei commenti, allego la cartella della demo realizzata con il codice scritto sopra. Scarica il file

Conclusioni

Dropbox è un servizio totalmente gratuito per i primi 2GB (espandibili fino a 20 tramite referall e bonus vari). Lo utilizzo già da qualche anno per avere sempre in tasca tutti i miei lavori, senza contare le volte che mi è tornato utile dopo la cancellazione volontaria (ma soprattutto involontaria :S) di alcuni file. Il server infatti tiene sempre traccia di tutto ciò che viene eliminato dalla nostra cartella, comodo no?

Esistono molte alternative a Dropbox che danno anche un maggiore spazio di archiviazione gratuito iniziale, ma non ho avuto ancora il piacere di utilizzarle a fondo.

E tu di quale servizio cloud (gratuito o a pagamento) fai uso? Con quale scopo?