Articles /

Archiviazione di file

  • Introduzione
  • Configurazione
    • Il driver locale
    • Il disco pubblico
    • Pre-requisiti del driver
    • Caching
  • Ricerca delle istanze del disco
  • Ricerca dei file
    • Scarico dei file
    • Urls dei file
    • Metadati dei file
  • Memorizzazione dei file
    • Caricamento dei file
    • Visibilità dei file
  • Eliminazione dei file
  • Direzioni
  • Custom Filesystems

Introduzione

Laravel fornisce una potente astrazione del filesystem grazie al meraviglioso pacchetto Flysystem PHP di Frank de Jonge. L’integrazione Flysystem di Laravel fornisce semplici driver per lavorare con filesystem locali, SFTP e Amazon S3. Ancora meglio, è incredibilmente semplice passare tra queste opzioni di archiviazione tra la tua macchina di sviluppo locale e il server di produzione poiché l’API rimane la stessa per ogni sistema.

Configurazione

Il file di configurazione del filesystem di Laravel si trova a config/filesystems.php. All’interno di questo file, puoi configurare tutti i tuoi “dischi” di filesystem. Ogni disco rappresenta un particolare driver di archiviazione e una posizione di archiviazione. Configurazioni di esempio per ogni driver supportato sono incluse nel file di configurazione in modo da poter modificare la configurazione per riflettere le proprie preferenze e credenziali di archiviazione.

Il driver local interagisce con i file memorizzati localmente sul server che esegue l’applicazione Laravel mentre il driver s3 viene utilizzato per scrivere sul servizio di cloud storage S3 di Amazon.

{tip} Puoi configurare tutti i dischi che vuoi e puoi anche avere più dischi che usano lo stesso driver.

Il driver locale

Quando usi il driver local, tutte le operazioni sui file sono relative alla directory root definita nel tuo file di configurazione filesystems. Per impostazione predefinita, questo valore è impostato alla directory storage/app. Pertanto, il seguente metodo scriverebbe su storage/app/example.txt:

use Illuminate\Support\Facades\Storage;Storage::disk('local')->put('example.txt', 'Contents');

Il disco pubblico

Il disco public incluso nel file di configurazione filesystems della tua applicazione è destinato ai file che saranno accessibili pubblicamente. Per default, il disco public usa il driver local e memorizza i suoi file in storage/app/public.

Per rendere questi file accessibili dal web, dovresti creare un collegamento simbolico da public/storage a storage/app/public. Utilizzando questa convenzione di cartelle si manterranno i file accessibili pubblicamente in una directory che può essere facilmente condivisa tra le distribuzioni quando si utilizzano sistemi di distribuzione a tempo zero come Envoyer.

Per creare il link simbolico, puoi usare il comando storage:link Artisan:

php artisan storage:link

Una volta che un file è stato memorizzato e il link simbolico è stato creato, puoi creare un URL ai file usando l’helper asset:

echo asset('storage/file.txt');

Puoi configurare ulteriori link simbolici nel tuo file di configurazione filesystems. Ognuno dei link configurati verrà creato quando eseguirai il comando storage:link:

'links' => ,

Pre-requisiti del driver

Pacchetti Composer

Prima di usare i driver S3 o SFTP, dovrai installare il pacchetto appropriato tramite il gestore dei pacchetti Composer:

  • Amazon S3: league/flysystem-aws-s3-v3 ~1.0
  • SFTP: league/flysystem-sftp ~1.0

Inoltre, puoi scegliere di installare un adattatore cache per aumentare le prestazioni:

  • CachedAdapter: league/flysystem-cached-adapter ~1.0

Configurazione del driver S3

Le informazioni sulla configurazione del driver S3 si trovano nel tuo file di configurazione config/filesystems.php. Questo file contiene un array di configurazione di esempio per un driver S3. Sei libero di modificare questo array con la tua configurazione S3 e le tue credenziali. Per comodità, queste variabili d’ambiente corrispondono alla convenzione di denominazione utilizzata da AWS CLI.

Configurazione del driver FTP

Le integrazioni Flysystem di Laravel funzionano benissimo con FTP; tuttavia, una configurazione di esempio non è inclusa nel file di configurazione predefinito del framework filesystems.php. Se hai bisogno di configurare un filesystem FTP, puoi usare l’esempio di configurazione che segue:

'ftp' => ,

Configurazione del driver SFTP

Le integrazioni Flysystem di Laravel funzionano benissimo con SFTP; tuttavia, una configurazione di esempio non è inclusa nel file di configurazione predefinito filesystems.php del framework. Se hai bisogno di configurare un filesystem SFTP, puoi usare l’esempio di configurazione che segue:

'sftp' => ,

Caching

Per abilitare la cache per un dato disco, puoi aggiungere una direttiva cache alle opzioni di configurazione del disco. L’opzione cache dovrebbe essere un array di opzioni di caching contenente il nome disk, il tempo expire in secondi, e la cache prefix:

's3' => ,],

Obtaining Disk Instances

La facciata Storage può essere usata per interagire con qualsiasi disco configurato. Per esempio, puoi usare il metodo put sulla facciata per memorizzare un avatar sul disco predefinito. Se chiamate i metodi sulla facciata Storage senza prima chiamare il metodo disk, il metodo verrà automaticamente passato al disco di default:

use Illuminate\Support\Facades\Storage;Storage::put('avatars/1', $content);

Se la tua applicazione interagisce con più dischi, puoi usare il metodo disk sulla facciata Storage per lavorare con i file su un particolare disco:

Storage::disk('s3')->put('avatars/1', $content);

Recupero dei file

Il metodo get può essere usato per recuperare il contenuto di un file. Il metodo restituisce il contenuto della stringa grezza del file. Ricorda, tutti i percorsi dei file dovrebbero essere specificati relativi alla posizione “root” del disco:

$contents = Storage::get('file.jpg');

Il metodo exists può essere usato per determinare se un file esiste sul disco:

if (Storage::disk('s3')->exists('file.jpg')) { // ...}

Il metodo missing può essere usato per determinare se un file manca dal disco:

if (Storage::disk('s3')->missing('file.jpg')) { // ...}

Downloading Files

Il metodo download può essere usato per generare una risposta che forza il browser dell’utente a scaricare il file nel percorso dato. Il metodo download accetta un nome di file come secondo argomento del metodo, che determinerà il nome del file che viene visto dall’utente che scarica il file. Infine, puoi passare un array di intestazioni HTTP come terzo argomento al metodo:

return Storage::download('file.jpg');return Storage::download('file.jpg', $name, $headers);

Urls di file

Puoi usare il metodo url per ottenere l’URL di un dato file. Se stai usando il driver local, questo tipicamente aggiungerà solo /storage al percorso dato e restituirà un URL relativo al file. Se stai usando il driver s3, verrà restituito l’URL remoto completamente qualificato:

use Illuminate\Support\Facades\Storage;$url = Storage::url('file.jpg');

Quando usi il driver local, tutti i file che dovrebbero essere accessibili pubblicamente dovrebbero essere messi nella directory storage/app/public. Inoltre, dovresti creare un collegamento simbolico a public/storage che punti alla directory storage/app/public.

{note} Quando si usa il driver local, il valore di ritorno di url non è codificato come URL. Per questo motivo, raccomandiamo di memorizzare sempre i tuoi file usando nomi che creino URL validi.

Utilizzando il metodo temporaryUrl, puoi creare URL temporanei ai file memorizzati usando il driver s3. Questo metodo accetta un percorso e un’istanza DateTime che specifica quando l’URL dovrebbe scadere: 

use Illuminate\Support\Facades\Storage;$url = Storage::temporaryUrl( 'file.jpg', now()->addMinutes(5));

Se hai bisogno di specificare ulteriori parametri di richiesta S3, puoi passare l’array di parametri di richiesta come terzo argomento al metodo temporaryUrl:

$url = Storage::temporaryUrl( 'file.jpg', now()->addMinutes(5), );

Personalizzazione dell’host dell’URL

Se vuoi predefinire l’host per gli URL generati usando la facciata Storage, puoi aggiungere un’opzione url all’array di configurazione del disco:

'public' => ,

File Metadata

Oltre a leggere e scrivere file, Laravel può anche fornire informazioni sui file stessi. Per esempio, il metodo size può essere usato per ottenere la dimensione di un file in byte:

use Illuminate\Support\Facades\Storage;$size = Storage::size('file.jpg');

Il metodo lastModified restituisce il timestamp UNIX dell’ultima volta che il file è stato modificato:

$time = Storage::lastModified('file.jpg');

File Paths

Puoi usare il metodo path per ottenere il percorso di un dato file. Se state usando il driver local, questo restituirà il percorso assoluto del file. Se stai usando il driver s3, questo metodo restituirà il percorso relativo al file nel bucket S3:

use Illuminate\Support\Facades\Storage;$path = Storage::path('file.jpg');

Stoccaggio dei file

Il metodo put può essere usato per memorizzare il contenuto dei file su un disco. Puoi anche passare un PHP resource al metodo put, che userà il supporto per il flusso sottostante di Flysystem. Ricorda, tutti i percorsi dei file dovrebbero essere specificati relativi alla posizione “root” configurata per il disco:

use Illuminate\Support\Facades\Storage;Storage::put('file.jpg', $contents);Storage::put('file.jpg', $resource);

Automatic Streaming

Lo streaming dei file verso lo storage offre un utilizzo della memoria significativamente ridotto. Se vuoi che Laravel gestisca automaticamente lo streaming di un dato file nella tua posizione di memorizzazione, puoi usare il metodo putFile o putFileAs. Questo metodo accetta un’istanza Illuminate\Http\File o Illuminate\Http\UploadedFile e farà automaticamente lo streaming del file nella posizione desiderata:

use Illuminate\Http\File;use Illuminate\Support\Facades\Storage;// Automatically generate a unique ID for filename...$path = Storage::putFile('photos', new File('/path/to/photo'));// Manually specify a filename...$path = Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg');

Ci sono alcune cose importanti da notare sul metodo putFile. Notate che abbiamo specificato solo un nome di directory e non un nome di file. Per impostazione predefinita, il metodo putFile genererà un ID unico che servirà come nome del file. L’estensione del file sarà determinata esaminando il tipo MIME del file. Il percorso del file sarà restituito dal metodo putFile in modo da poter memorizzare il percorso, incluso il nome del file generato, nel vostro database.

I metodi putFile e putFileAs accettano anche un argomento per specificare la “visibilità” del file memorizzato. Questo è particolarmente utile se stai memorizzando il file su un disco cloud come Amazon S3 e vuoi che il file sia accessibile pubblicamente tramite gli URL generati:

Storage::putFile('photos', new File('/path/to/photo'), 'public');

Preparazione & Appending To Files

I metodi prepend e append ti permettono di scrivere all’inizio o alla fine di un file:

Storage::prepend('file.log', 'Prepended Text');Storage::append('file.log', 'Appended Text');

Copiare & Spostare file

Il metodo copy può essere usato per copiare un file esistente in una nuova posizione sul disco, mentre il metodo move può essere usato per rinominare o spostare un file esistente in una nuova posizione:

Storage::copy('old/file.jpg', 'new/file.jpg');Storage::move('old/file.jpg', 'new/file.jpg');

File Uploads

Nelle applicazioni web, uno dei casi d’uso più comuni per la memorizzazione dei file è la memorizzazione dei file caricati dall’utente come foto e documenti. Laravel rende molto facile memorizzare i file caricati usando il metodo store su un’istanza di file caricato. Chiama il metodo store con il percorso in cui desideri memorizzare il file caricato:

<?phpnamespace App\Http\Controllers;use App\Http\Controllers\Controller;use Illuminate\Http\Request;class UserAvatarController extends Controller{ /** * Update the avatar for the user. * * @param \Illuminate\Http\Request $request * @return \Illuminate\Http\Response */ public function update(Request $request) { $path = $request->file('avatar')->store('avatars'); return $path; }}

Ci sono alcune cose importanti da notare su questo esempio. Notate che abbiamo specificato solo un nome di directory, non un nome di file. Per impostazione predefinita, il metodo store genererà un ID unico che servirà come nome del file. L’estensione del file sarà determinata esaminando il tipo MIME del file. Il percorso del file sarà restituito dal metodo store in modo da poter memorizzare il percorso, incluso il nome del file generato, nel vostro database.

Puoi anche chiamare il metodo putFile sulla facciata Storage per eseguire la stessa operazione di memorizzazione dei file dell’esempio precedente:

$path = Storage::putFile('avatars', $request->file('avatar'));

Specificare un nome di file

Se non vuoi che un nome di file sia assegnato automaticamente al tuo file memorizzato, puoi usare il metodo storeAs, che riceve come argomenti il percorso, il nome del file e il disco (opzionale):

$path = $request->file('avatar')->storeAs( 'avatars', $request->user()->id);

Puoi anche usare il metodo putFileAs sulla facciata Storage, che eseguirà la stessa operazione di memorizzazione dei file dell’esempio precedente:

$path = Storage::putFileAs( 'avatars', $request->file('avatar'), $request->user()->id);

{note} I caratteri unicode non stampabili e non validi saranno automaticamente rimossi dai percorsi dei file. Pertanto, si potrebbe desiderare di sanitizzare i percorsi dei file prima di passarli ai metodi di archiviazione dei file di Laravel. I percorsi dei file sono normalizzati usando il metodo League\Flysystem\Util::normalizePath.

Specificare un disco

Di default, il metodo store di questo file caricato userà il tuo disco predefinito. Se vuoi specificare un altro disco, passa il nome del disco come secondo argomento al metodo store:

$path = $request->file('avatar')->store( 'avatars/'.$request->user()->id, 's3');

Se stai usando il metodo storeAs, puoi passare il nome del disco come terzo argomento al metodo:

$path = $request->file('avatar')->storeAs( 'avatars', $request->user()->id, 's3');

Altre informazioni sul file caricato

Se vuoi ottenere il nome originale del file caricato, puoi farlo usando il metodo getClientOriginalName:

$name = $request->file('avatar')->getClientOriginalName();

Il metodo extension può essere usato per ottenere l’estensione del file caricato:

$extension = $request->file('avatar')->extension();

Visibilità del file

Nell’integrazione Flysystem di Laravel, la “visibilità” è un’astrazione dei permessi dei file su più piattaforme. I file possono essere dichiarati public o private. Quando un file è dichiarato public, stai indicando che il file dovrebbe essere generalmente accessibile agli altri. Per esempio, quando si usa il driver S3, si possono recuperare gli URL per i file public.

Puoi impostare la visibilità quando scrivi il file tramite il metodo put:

use Illuminate\Support\Facades\Storage;Storage::put('file.jpg', $contents, 'public');

Se il file è già stato memorizzato, la sua visibilità può essere recuperata e impostata tramite i metodi getVisibility e setVisibility:

$visibility = Storage::getVisibility('file.jpg');Storage::setVisibility('file.jpg', 'public');

Quando si interagisce con i file caricati, si possono usare i metodi storePublicly e storePubliclyAs per memorizzare il file caricato con public visibilità:

$path = $request->file('avatar')->storePublicly('avatars', 's3');$path = $request->file('avatar')->storePubliclyAs( 'avatars', $request->user()->id, 's3');

File locali & Visibilità

Quando si usa il driver local, public visibilità si traduce in 0755 permessi per le directory e 0644 permessi per i file. Puoi modificare le mappature dei permessi nel file di configurazione filesystems della tua applicazione:

'local' => , 'dir' => , ],],

Eliminazione di file

Il metodo delete accetta un singolo nome di file o un array di file da eliminare:

use Illuminate\Support\Facades\Storage;Storage::delete('file.jpg');Storage::delete();

Se necessario, potete specificare il disco da cui il file deve essere cancellato:

use Illuminate\Support\Facades\Storage;Storage::disk('s3')->delete('path/file.jpg');

Directories

Get All Files Within A Directory

Il metodo files restituisce un array di tutti i file in una data directory. Se vuoi recuperare una lista di tutti i file all’interno di una data directory, incluse tutte le sottodirectory, puoi usare il metodo allFiles:

use Illuminate\Support\Facades\Storage;$files = Storage::files($directory);$files = Storage::allFiles($directory);

Get All Directories Within A Directory

Il metodo directories restituisce un array di tutte le directory all’interno di una data directory. Inoltre, potete usare il metodo allDirectories per ottenere una lista di tutte le directory all’interno di una data directory e di tutte le sue sottodirectory:

$directories = Storage::directories($directory);$directories = Storage::allDirectories($directory);

Create A Directory

Il metodo makeDirectory creerà la directory data, incluse le sottodirectory necessarie:

Storage::makeDirectory($directory);

Delete A Directory

Infine, il metodo deleteDirectory può essere usato per rimuovere una directory e tutti i suoi file:

Storage::deleteDirectory($directory);

Custom Filesystems

L’integrazione Flysystem di Laravel fornisce supporto per diversi “driver” fuori dalla scatola; tuttavia, Flysystem non è limitato a questi e ha adattatori per molti altri sistemi di archiviazione. Puoi creare un driver personalizzato se vuoi usare uno di questi adattatori aggiuntivi nella tua applicazione Laravel.

Per definire un filesystem personalizzato avrai bisogno di un adattatore Flysystem. Aggiungiamo un adattatore Dropbox mantenuto dalla comunità al nostro progetto:

composer require spatie/flysystem-dropbox

Poi, puoi registrare il driver all’interno del metodo boot di uno dei service provider della tua applicazione. Per fare questo, dovresti usare il metodo extend della facciata Storage:

<?phpnamespace App\Providers;use Illuminate\Support\Facades\Storage;use Illuminate\Support\ServiceProvider;use League\Flysystem\Filesystem;use Spatie\Dropbox\Client as DropboxClient;use Spatie\FlysystemDropbox\DropboxAdapter;class AppServiceProvider extends ServiceProvider{ /** * Register any application services. * * @return void */ public function register() { // } /** * Bootstrap any application services. * * @return void */ public function boot() { Storage::extend('dropbox', function ($app, $config) { $client = new DropboxClient( $config ); return new Filesystem(new DropboxAdapter($client)); }); }}

Il primo argomento del metodo extend è il nome del driver e il secondo è una chiusura che riceve le variabili $app e $config. La chiusura deve restituire un’istanza di League\Flysystem\Filesystem. La variabile $config contiene i valori definiti in config/filesystems.php per il disco specificato.

Una volta che avete creato e registrato il service provider dell’estensione, potete usare il dropbox driver nel vostro file di configurazione config/filesystems.php.

Leave a Reply