Przechowywanie plików

• Wprowadzenie
• Konfiguracja
  • Sterownik lokalny
  • Dysk publiczny
  • Warunki wstępne sterownika
  • Buforowanie
• Uzyskiwanie instancji dyskowych
• Pobieranie plików
  • Pobieranie plików
  • Adresy URL plików
  • Metadane plików

  .

• Przechowywanie plików
  • Wysyłanie plików
  • Widoczność plików
• Usuwanie plików
• Katalogi
• Systemy plików niestandardowych Systemy plików

Wprowadzenie

Laravel zapewnia potężną abstrakcję systemu plików dzięki wspaniałemu pakietowi Flysystem PHP autorstwa Franka de Jonge. Integracja Laravel Flysystem zapewnia proste sterowniki do pracy z lokalnymi systemami plików, SFTP i Amazon S3. Nawet lepiej, jest to zdumiewająco proste, aby przełączać się między tymi opcjami przechowywania danych między lokalną maszyną deweloperską a serwerem produkcyjnym, ponieważ API pozostaje takie samo dla każdego systemu.

Konfiguracja

Plik konfiguracyjny systemu plików Laravela znajduje się pod adresem config/filesystems.php. W tym pliku, możesz skonfigurować wszystkie swoje „dyski” systemu plików. Każdy dysk reprezentuje konkretny sterownik i miejsce przechowywania danych. Przykładowe konfiguracje dla każdego obsługiwanego sterownika są zawarte w pliku konfiguracyjnym, więc możesz zmodyfikować konfigurację, aby odzwierciedlić swoje preferencje przechowywania i poświadczenia.

Sterownik local wchodzi w interakcję z plikami przechowywanymi lokalnie na serwerze z aplikacją Laravel, podczas gdy sterownik s3 jest używany do zapisu do usługi przechowywania w chmurze Amazon S3.

{tip} Możesz skonfigurować tyle dysków, ile chcesz, a nawet możesz mieć wiele dysków korzystających z tego samego sterownika.

Sterownik lokalny

Podczas korzystania ze sterownika local wszystkie operacje na plikach są względne względem katalogu root zdefiniowanego w Twoim pliku konfiguracyjnym filesystems. Domyślnie wartość ta jest ustawiona na katalog storage/app. Dlatego poniższa metoda spowodowałaby zapis do storage/app/example.txt:

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

Dysk publiczny

Dysk public zawarty w pliku konfiguracyjnym filesystems aplikacji jest przeznaczony dla plików, które będą publicznie dostępne. Domyślnie dysk public używa sterownika local i przechowuje swoje pliki w storage/app/public.

Aby udostępnić te pliki z sieci, należy utworzyć dowiązanie symboliczne z public/storage do storage/app/public. Wykorzystanie tej konwencji folderów pozwoli zachować publicznie dostępne pliki w jednym katalogu, który może być łatwo współdzielony w ramach wdrożeń przy użyciu systemów wdrażania bez przestojów, takich jak Envoyer.

Aby utworzyć dowiązanie symboliczne, możesz użyć polecenia storage:link Artisan:

php artisan storage:link

Po zapisaniu pliku i utworzeniu dowiązania symbolicznego możesz utworzyć adres URL do plików za pomocą asset helpera:

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

Możesz skonfigurować dodatkowe dowiązania symboliczne w swoim pliku konfiguracyjnym filesystems. Każdy ze skonfigurowanych linków zostanie utworzony po uruchomieniu polecenia storage:link:

'links' => ,

Warunki wstępne sterownika

Pakiety Composera

Przed użyciem sterowników S3 lub SFTP należy zainstalować odpowiedni pakiet za pośrednictwem menedżera pakietów Composera:

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

Dodatkowo możesz zdecydować się na zainstalowanie adaptera buforowanego w celu zwiększenia wydajności:

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

Konfiguracja sterownika S3

Informacje o konfiguracji sterownika S3 znajdują się w pliku konfiguracyjnym użytkownika config/filesystems.php. Ten plik zawiera przykładową tablicę konfiguracyjną dla sterownika S3. Możesz dowolnie modyfikować tę tablicę za pomocą własnej konfiguracji S3 i poświadczeń. Dla wygody, te zmienne środowiskowe odpowiadają konwencji nazewnictwa używanej przez AWS CLI.

Konfiguracja sterownika FTP

Integracje Flysystem Laravela świetnie współpracują z FTP, jednak przykładowa konfiguracja nie jest dołączona do domyślnego filesystems.phppliku konfiguracyjnego frameworka. Jeśli potrzebujesz skonfigurować system plików FTP, możesz użyć poniższego przykładu konfiguracji:

'ftp' => ,

Konfiguracja sterownika SFTP

Integracje Flysystem Laravela działają świetnie z SFTP; jednakże przykładowa konfiguracja nie jest dołączona do domyślnego filesystems.php pliku konfiguracyjnego frameworka. Jeśli potrzebujesz skonfigurować system plików SFTP, możesz użyć poniższego przykładu konfiguracji:

'sftp' => ,

Caching

Aby włączyć buforowanie dla danego dysku, możesz dodać dyrektywę cache do opcji konfiguracyjnych dysku. Opcja cache powinna być tablicą opcji buforowania zawierającą nazwę disk, czas expire w sekundach oraz pamięć podręczną prefix:

's3' => ,],

Otrzymywanie instancji dysków

Fasada Storage może być używana do interakcji z dowolnymi skonfigurowanymi dyskami. Na przykład możesz użyć metody put na fasadzie, aby przechowywać awatara na domyślnym dysku. Jeśli wywołasz metody na elewacji Storage bez uprzedniego wywołania metody disk, metoda zostanie automatycznie przekazana do dysku domyślnego:

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

Jeżeli Twoja aplikacja współdziała z wieloma dyskami, możesz użyć metody disk na fasadzie Storage do pracy z plikami na określonym dysku:

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

Pobieranie plików

Metoda get może być użyta do pobrania zawartości pliku. Metoda zwróci zawartość pliku w postaci surowego łańcucha znaków. Pamiętaj, że wszystkie ścieżki do plików powinny być podawane względem lokalizacji „root” dysku:

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

Metoda exists może być użyta do określenia, czy plik istnieje na dysku:

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

Metoda missing może być użyta do określenia, czy brakuje pliku na dysku:

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

Pobieranie plików

Metoda download może być użyta do wygenerowania odpowiedzi, która zmusza przeglądarkę użytkownika do pobrania pliku pod podaną ścieżką. Metoda download przyjmuje nazwę pliku jako drugi argument metody, który określi nazwę pliku widzianą przez użytkownika pobierającego plik. Wreszcie, możesz przekazać tablicę nagłówków HTTP jako trzeci argument metody:

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

Adresy URL plików

Możesz użyć metody url, aby uzyskać adres URL dla danego pliku. Jeśli używasz sterownika local, będzie to zazwyczaj tylko przedrostek /storage do podanej ścieżki i zwróci względny adres URL do pliku. Jeśli korzystasz ze sterownika s3, zwrócony zostanie w pełni kwalifikowany zdalny adres URL:

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

Przy korzystaniu ze sterownika local wszystkie pliki, które powinny być publicznie dostępne, powinny być umieszczone w katalogu storage/app/public. Ponadto należy utworzyć dowiązanie symboliczne pod adresem public/storage, które wskazuje na katalog storage/app/public.

{note} Podczas korzystania ze sterownika local wartość zwracana przez url nie jest zakodowana w adresie URL. Z tego powodu zalecamy, aby zawsze przechowywać pliki przy użyciu nazw, które utworzą prawidłowe adresy URL.

Tymczasowe adresy URL

Używając metody temporaryUrl, można utworzyć tymczasowe adresy URL do plików przechowywanych przy użyciu sterownika s3. Ta metoda akceptuje ścieżkę i instancję DateTime określającą, kiedy adres URL powinien wygasnąć:

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

Jeśli musisz określić dodatkowe parametry żądania S3, możesz przekazać tablicę parametrów żądania jako trzeci argument metody temporaryUrl:

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

URL Host Customization

Jeśli chciałbyś wstępnie zdefiniować host dla adresów URL generowanych przy użyciu fasady Storage, możesz dodać opcję url do tablicy konfiguracyjnej dysku:

'public' => ,

File Metadata

Oprócz odczytu i zapisu plików Laravel może również dostarczać informacji o samych plikach. Na przykład, metoda size może być użyta do uzyskania rozmiaru pliku w bajtach:

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

Metoda lastModified zwraca UNIX-owy znacznik czasu ostatniej modyfikacji pliku:

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

Ścieżki plików

Możesz użyć metody path do uzyskania ścieżki dla danego pliku. Jeśli używasz sterownika local, zwróci to bezwzględną ścieżkę do pliku. Jeśli używasz sterownika s3, ta metoda zwróci względną ścieżkę do pliku w wiadrze S3:

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

Przechowywanie plików

Metoda put może być użyta do przechowywania zawartości pliku na dysku. Możesz również przekazać PHP resource do metody put, która użyje obsługi strumieni Flysystemu. Pamiętaj, że wszystkie ścieżki do plików powinny być określone względem lokalizacji „root” skonfigurowanej dla dysku:

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

Automatyczne strumieniowanie

Strumieniowanie plików do pamięci masowej oferuje znacznie zmniejszone zużycie pamięci. Jeśli chciałbyś, aby Laravel automatycznie zarządzał strumieniowaniem danego pliku do miejsca przechowywania, możesz użyć metody putFile lub putFileAs. Metoda ta akceptuje instancję Illuminate\Http\File lub Illuminate\Http\UploadedFile i automatycznie prześle plik do wybranej lokalizacji:

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');

Jest kilka ważnych rzeczy, na które należy zwrócić uwagę w metodzie putFile. Zauważ, że podaliśmy tylko nazwę katalogu, a nie nazwę pliku. Domyślnie, metoda putFile wygeneruje unikalny identyfikator, który posłuży jako nazwa pliku. Rozszerzenie pliku zostanie określone przez zbadanie jego typu MIME. Ścieżka do pliku zostanie zwrócona przez metodę putFile, więc możesz przechowywać ścieżkę, w tym wygenerowaną nazwę pliku, w swojej bazie danych.

Metody putFile i putFileAs przyjmują również argument określający „widoczność” przechowywanego pliku. Jest to szczególnie przydatne, jeśli przechowujesz plik na dysku w chmurze, takim jak Amazon S3, i chciałbyś, aby plik był publicznie dostępny za pośrednictwem wygenerowanych adresów URL:

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

Prepending & Appending To Files

Metody prepend i append pozwalają na zapisywanie na początku lub końcu pliku:

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

Kopiowanie & Przenoszenie plików

Metoda copy może być użyta do skopiowania istniejącego pliku w nowe miejsce na dysku, natomiast metoda move może być użyta do zmiany nazwy lub przeniesienia istniejącego pliku w nowe miejsce:

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

Przesyłanie plików

W aplikacjach internetowych jednym z najczęstszych przypadków użycia do przechowywania plików jest przechowywanie plików przesłanych przez użytkownika, takich jak zdjęcia czy dokumenty. Laravel bardzo ułatwia przechowywanie przesłanych plików używając metody store na instancji przesłanego pliku. Wywołaj metodę store ze ścieżką, w której chcesz przechowywać przesłany plik:

<?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; }}

Jest kilka ważnych rzeczy, na które należy zwrócić uwagę w tym przykładzie. Zauważ, że podaliśmy tylko nazwę katalogu, a nie nazwę pliku. Domyślnie, metoda store wygeneruje unikalny identyfikator, który posłuży jako nazwa pliku. Rozszerzenie pliku zostanie określone przez zbadanie jego typu MIME. Ścieżka do pliku zostanie zwrócona przez metodę store, więc możesz przechowywać ścieżkę, w tym wygenerowaną nazwę pliku, w swojej bazie danych.

Możesz również wywołać metodę putFile na fasadzie Storage, aby wykonać tę samą operację przechowywania pliku, co w powyższym przykładzie:

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

Specifying A File Name

Jeśli nie chcesz, aby nazwa pliku została automatycznie przypisana do przechowywanego pliku, możesz użyć metody storeAs, która otrzymuje ścieżkę, nazwę pliku i (opcjonalny) dysk jako swoje argumenty:

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

Możesz również użyć metody putFileAs na fasadzie Storage, która wykona taką samą operację przechowywania pliku, jak w powyższym przykładzie:

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

{note} Niedrukowalne i niepoprawne znaki unicode będą automatycznie usuwane ze ścieżek do plików. Dlatego też, możesz chcieć oczyścić swoje ścieżki do plików przed przekazaniem ich do metod Laravela służących do przechowywania plików. Ścieżki plików są normalizowane przy użyciu metody League\Flysystem\Util::normalizePath.

Specifying A Disk

Domyślnie, metoda store tego przesłanego pliku użyje twojego domyślnego dysku. Jeśli chcesz określić inny dysk, przekaż nazwę dysku jako drugi argument metody store:

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

Jeśli używasz metody storeAs, możesz przekazać nazwę dysku jako trzeci argument metody:

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

Inne informacje o przesłanym pliku

Jeśli chcesz uzyskać oryginalną nazwę przesłanego pliku, możesz to zrobić za pomocą metody getClientOriginalName:

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

Metoda extension może być użyta do uzyskania rozszerzenia wgrywanego pliku:

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

Widoczność plików

W integracji Laravela z Flysystem, „widoczność” jest abstrakcją uprawnień do plików na wielu platformach. Pliki mogą być albo zadeklarowane public lub private. Kiedy plik jest zadeklarowany public, wskazujesz, że plik powinien być ogólnie dostępny dla innych. Na przykład, gdy używasz sterownika S3, możesz pobrać adresy URL dla plików public.

Możesz ustawić widoczność podczas zapisywania pliku za pomocą metody put:

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

Jeśli plik został już zapisany, jego widoczność można odzyskać i ustawić za pomocą metod getVisibility i setVisibility:

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

Podczas interakcji z przesłanymi plikami można użyć metod storePublicly i storePubliclyAs, aby przechowywać przesłany plik z widocznością public:

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

Local Files & Visibility

Podczas korzystania ze sterownika local widoczność public przekłada się na uprawnienia 0755 dla katalogów i 0644 dla plików. Mapowania uprawnień można zmodyfikować w pliku konfiguracyjnym filesystems aplikacji:

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

Usuwanie plików

Metoda delete przyjmuje pojedynczą nazwę pliku lub tablicę plików do usunięcia:

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

W razie potrzeby można określić dysk, z którego plik ma zostać usunięty:

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

Directories

Get All Files Within A Directory

Metoda files zwraca tablicę wszystkich plików w danym katalogu. Jeśli chcesz pobrać listę wszystkich plików w obrębie danego katalogu, w tym wszystkich podkatalogów, możesz użyć metody allFiles:

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

Get All Directories Within A Directory

Metoda directories zwraca tablicę wszystkich katalogów w obrębie danego katalogu. Dodatkowo możesz użyć metody allDirectories, aby uzyskać listę wszystkich katalogów w obrębie danego katalogu i wszystkich jego podkatalogów:

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

Create A Directory

Metoda makeDirectory utworzy podany katalog, łącznie z wszelkimi potrzebnymi podkatalogami:

Storage::makeDirectory($directory);

Delete A Directory

Wreszcie, metoda deleteDirectory może być użyta do usunięcia katalogu i wszystkich jego plików:

Storage::deleteDirectory($directory);

Niestandardowe systemy plików

Integracja Flysystem w Laravel zapewnia wsparcie dla kilku „sterowników” po wyjęciu z pudełka; jednakże Flysystem nie ogranicza się do nich i posiada adaptery dla wielu innych systemów pamięci masowej. Możesz stworzyć własny sterownik, jeśli chcesz użyć jednego z tych dodatkowych adapterów w swojej aplikacji Laravel.

Aby zdefiniować niestandardowy system plików, będziesz potrzebował adaptera Flysystem. Dodajmy utrzymywany przez społeczność adapter Dropbox do naszego projektu:

composer require spatie/flysystem-dropbox

Następnie możesz zarejestrować sterownik w metodzie boot jednego z dostawców usług Twojej aplikacji. Aby to osiągnąć, należy użyć metody extend fasady 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)); }); }}

Pierwszym argumentem metody extend jest nazwa sterownika, a drugim jest zamknięcie, które otrzymuje zmienne $app i $config. Domknięcie musi zwracać instancję League\Flysystem\Filesystem. Zmienna $config zawiera wartości zdefiniowane w config/filesystems.php dla określonego dysku.

Po utworzeniu i zarejestrowaniu dostawcy usług rozszerzenia możesz użyć sterownika dropbox w swoim pliku konfiguracyjnym config/filesystems.php.

.