آموزش ذخیره سازی ابری در لاراول

ذخیره سازی ابری / سیستم فایل

1. مقدمه
2. تنظیمات و کانفیگ
3. کاربرد و استفاده پایه ای
   • دسترسی به دیسک مشخص
   • واکشی محتویات فایل مشخص
   • ذخیره سازی فایل ها
   • سطح دسترسی و قابلیت رویت فایل ها
   • حذف فایل ها
   • پوشه ها
4. سیستم فایل های سفارشی

مقدمه

چارچوب نرم افزاری Laravel با بهره گیری از پکیج کارآمد Flysystem که توسط Frank de Jonge برای زبان PHP تنظیم شد، امکانات سیستم فایل قدرتمندی ویژه ی توسعه اپلیکیشن های تحت وب ارائه می دهد. در واقع ادغام کتابخانه ی Flysystem با لاراول سبب اضافه شدن تعدادی درایور بهینه جهت کار با سیستم فایل های محلی، Amazon S3 و Rackspace Cloud Storage شده است. همچنین از آنجایی که API همانAPI است (رابط برنامه سازی کاربردی مورد استفاده ی سیستم های ذخیره سازی یکسان بوده و تغییر نمی کند)، می توان به راحتی از یک سرویس ذخیره سازی (storage option) به دیگری تغییر کاربری داد (بین آن ها سوئیچ کرد).

تنظیمات و کانفیگ

برای دستیابی به فایل تنظیمات filesystem بایستی به آدرس config/filesystems.php مراجعه نمایید. داخل این فایل می توانید اقدام به تنظیم تمامی دیسک های خود نمایید. همان طور که می دانید هر دیسک نشانگر یک درایور و مکان ذخیره سازی خاص می باشد. همچنین به ازای هر درایور تنظیمات نمونه و پیش فرضی در فایل کانفیگ لحاظ شده که با ویرایش مقادیر آن ها می توانید تنظیمات ، مجوزهای دسترسی (credentials = نام کاربری و گذرواژه ی مورد نیاز برای دسترسی) به محل ذخیره سازی مد نظر خود را مشخص نمایید.
می توانید هر تعداد که اپلیکیشن شما ایجاب می کند، دیسک تنظیم نمایید و حتی چندین دیسک پیکربندی کنید که از یک درایور واحد استفاده می کنند.

دیسکی با سطح دسترسی public

دیسکی که با سطح دسترسی public تعریف شده ویژه ی فایل هایی می باشد که برای عموم قابل دسترسی هستند. به طور پیشفرض دیسک public از درایور local بهره گرفته و فایل ها را در مسیر storage/app/public ذخیره می کند. برای اینکه فایل ها از طریق وب قابل دسترسی باشند، لازم است یک symlink از public/storage به storage/app/public ایجاد نمایید (symlink یک روش ایجاد لینک به دو فایل از سیستم فایل است که دارای محتویات یکسان هستند و تغییر در هریک در دیگری نیز منعکس می شود). این قرارداد سبب می شود تمامی فایل های public شما تحت یک پوشه نگهداری شده و نیز به شما امکان می دهد تا زمانی که از سیستم های مستقرسازی و نصب بدون downtime (بدون خرابی و مدت از کار افتادگی) نظیر Envoyer استفاده می کنید، به راحتی بتوانید فایل ها را بین چندین deployment به اشتراک بگذارید.
می توان پس از ذخیره ی فایل و ایجاد یک symlink به آن، با استفاده از تابع کمکی asset یک URL برای فایل ها ایجاد نمود:

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

درایور local

به هنگام استفاده از درایور local لازم است توجه داشته باشید که تمامی عملیات مربوط به فایل نسبت به دایرکتوری root که در فایل تنظیمات تعریف شده، انجام می گیرد. به صورت پیش فرض، این مقدار با دایرکتوری storage/app برابر قرار داده و تنظیم شده است. با توجه به آنچه گفته شد متد زیر فایل مورد نظر را در آدرس storage/app/file.txt ذخیره می کند:

پیش نیازهای استفاده از دیگر درایورها

جهت استفاده از درایورهای S3 یا Rackspace ابتدا بایستی پکیج های مربوطه را به وسیله ی Composer نصب نمایید:

• Amazon S3: league/flysystem-aws-s3-v3 ~1.0
• Rackspace: league/flysystem-rackspace ~1.0

تنظیم درایور FTP

پکیج Flysystem که با فریم ورک لاراول ادغام شده، سازگاری قابل توجهی با FTP دارد. اما لازم به ذکر است ویژه ی این درایور هیچ پیکربندی و تنظیمات نمونه ای در فایل کانفیگ پیش فرض این فریم ورک filesystems.php لحاظ نشده است. برای تنظیم و پیکربندی سیستم فایل FTP می توانید از config نمونه ی زیر بهره ببرید:

'ftp' => [
   'driver'  => 'ftp',
   'host'    => 'ftp.example.com',
   'username' => 'your-username',
   'password' => 'your-password',
   // Optional FTP Settings...
   // 'port'    =>21,
   // 'root'    =>'',
   // 'passive' =>true,
   // 'ssl'     =>true,
   // 'timeout' =>30,
],

تنظیم درایور Rackspace

پکیج Flysystem که با فریم ورک لاراول ادغام شده، سازگاری قابل توجهی با Rackspace دارد. اما لازم به ذکر است ویژه ی این درایور هیچ پیکربندی و تنظیمات نمونه ای در فایل کانفیگ پیش فرض این فریم ورک filesystems.php لحاظ نشده است. برای تنظیم و پیکربندی سیستم فایلRackspace می توانید از config نمونه ی زیر بهره ببرید:

'rackspace' => [
   'driver'   => 'rackspace',
   'username' => 'your-username',
   'key'      => 'your-key',
   'container' => 'your-container',
   'endpoint' => 'https://identity.api.rackspacecloud.com/v2.0/',
   'region'   => 'IAD',
   'url_type' => 'publicURL',
],

کاربرد و استفاده پایه ای

دسترسی به دیسک مشخص

جهت کار با دیسک های تنظیم شده، می توانید از فاساد Storage استفاده نمایید. به عنوان مثال با فراخوانی متد put در facade ذکر شده، می توان یک آواتار در دیسک پیش فرض ذخیره نمود. چنانچه پیش از فراخوانی توابع دلخواه در Storage، متد disk را (اول) صدا نزده باشید، آنگاه متد فراخوانده شده (مثلا put) به صورت خودکار به دیسک پیش فرض پاس داده می شود:

<?php
namespace App\Http\Controllers;
use Storage;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
class UserController extends Controller
{
 /**
    * Update the avatar for the given user.
    *
    * @param Request $request
    * @param int $id
    * @return Response
    */
   public function updateAvatar(Request $request, $id)
   {
 $user = User::findOrFail($id);
       Storage::put(
           'avatars/'.$user->id,
           file_get_contents($request->file('avatar')->getRealPath())
       );
   }
}

اگر همزمان از چندین دیسک استفاده می کنید، در آن صورت می توانید با فراخوانی متد disk در facade مذکور به دیسک مورد نظر دسترسی داشته باشید. همچنین می توانید متدها را به صورت زنجیره ای بر روی دیسک مورد نظر فراخوانی نمایید:

$disk = Storage::disk('s3');
$contents = Storage::disk('local')->get('file.jpg')

واکشی محتویات فایل مشخص

متد get قادر است محتویات فایلی که به عنوان آرگومان به آن پاس داده شده را واکشی کند:

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

محتویات فایل در قالب رشته ی خام به عنوان خروجی برگردانده می شود.
متد exists بررسی می کند آیا فایل ارسالی به عنوان آرگومان، وجود خارجی دارد یا خیر:

                    $exists = Storage::disk('s3')->exists('file.jpg');

URL های فایل

اگر از درایور local یا s3 استفاده می کنید، در آن صورت با اجرای متد url، می توانید آدرس URL فایل مورد نظر را بدست آورید. اما اگر درایور مورد استفاده ی شما local باشد، در آن صورت این متد معمولا فقط /storage را به پیش از مسیر (path) مورد نظر الصاق کرده و در خروجی یک URLنسبی (relative و آدرس دهی شده نسبت به فایل مربوطه) برمی گرداند. در صورت استفاده از درایور s3، آدرس URL کامل راه دور (remote) بازگردانی می شود.

                    $url = Storage::url('file1.jpg');

Meta information فایل

متد size حجم فایل را به بایت برمی گرداند:

$size = Storage::size('file1.jpg');

متد lastModified برچسب زمانی UNIX آخرین باری که فایل ویرایش شده را در خروجی برمی گرداند:

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

ذخیره سازی فایل ها

با بهره گیری از متد put می توانید اطلاعات یک فایل را بر روی دیسک ذخیره نمایید. همچنین می توانید یک resource پی اچ پی به عنوان آرگومان به متد put ارسال کنید که از قابلیت زیرساختی stream پکیج Flysystem بهره می گیرد. توصیه می کنیم به هنگام کار با فایل های بزرگ و سنگین ازstream ها استفاده نمایید.

Storage::put('file.jpg', $contents);
Storage::put('file.jpg', $resource);

متد copy به منظور کپی فایل جاری به مکان مورد نظر در دیسک بکار می رود:

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

متد move را می توان جهت تغییر اسم یا انتقال فایل جاری به مکانی جدید در دیسک بکار برد:

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

اضافه کردن محتوای جدید به قبل / بعد از یک فایل

توابع prepend و append به شما این امکان را می دهد تا به آسانی محتوای جدید به ابتدا یا انتهای فایل الصاق کنید:

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

سطح دسترسی و قابلیت رویت یک فایل

File visibility یا سطح دسترسی به یک فایل را می توان توسط دو متد getVisibility و setVisibility به ترتیب بازیابی کرده و مقداری دهی نمود

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

می توان سطح دسترسی به فایل را در زمان تنظیم و ذخیره ی فایل در دیسک توسط متد put، مشخص کرد (visibility را داخل پرانتز متد put به عنوان آرگومان سوم به آن پاس داد). دو مقدار تنظیم سطح دسترسی قابل استفاده و معتبر عبارت است از: public و private.

                    Storage::put('file.jpg', $contents, 'public');

حذف فایل ها

متد delete به عنوان آرگومان یک اسم فایل یا آرایه ای از اسم فایل ها را می پذیرد. سپس فایل هایی که به عنوان پارامتر به این متد پاس داده شده را از دیسک حذف می کند:

Storage::delete('file.jpg');
Storage::delete(['file1.jpg', 'file2.jpg']);

دایرکتوری و پوشه ها

بازیابی تمامی فایل های مقیم در یک دایرکتوری

متد files آرایه ای از تمامی فایل های موجود در یک پوشه را به عنوان خروجی برمی گرداند. چنانچه می خواهید لیستی از تمامی فایل های داخل یک دایرکتوری مشخص از جمله کلیه ی sub-directory ها را برگردانید، کافی است متد allFiles را فراخوانی نمایید:

$files = Storage::files($directory);
$files = Storage::allFiles($directory);

بازیابی تمامی دایرکتوری های موجود در یک دایرکتوری دیگر

متد directories آرایه ای از تمامی دایرکتوری های موجود در یک پوشه یا دایرکتوری را در خروجی برمی گرداند. حال به منظور بازیابی تمامی پوشه های موجود در یک دایرکتوری و نیز کلیه ی sub-directory های آن، بایستی allDirectories را صدا بزنید:

$directories = Storage::directories($directory);
// Recursive...
$directories = Storage::allDirectories($directory);

ایجاد یک دایرکتوری جدید

متد makeDirectory دایکرتوری مورد نظر را به همراه تمامی sub-directory های لازم ایجاد می کند:

                    Storage::makeDirectory($directory);

حذف یک دایرکتوری

در پایان متد deleteDirectory را داریم که دایرکتوری مورد نظر را به همراه تمامی فایل های آن (که به عنوان پارامتر به متد ارسال شده اند) را از دیسک پاک می کند.

                    Storage::deleteDirectory($directory);

سیستم فایل های سفارشی

ادغام پکیج Flysystem با لاراول درایورهای متعددی را در اختیار برنامه نویس قرار می دهد. هرچند Flysystem محدود به این سیستم فایل ها نبوده و adapter (مبدل) هایی هم برای دیگر سیستم های ذخیره سازی دربر می گیرد. اگر می خواهید از adapter های این پکیج در اپلیکیشن تحت وب لاراول خود استفاده نمایید، در آن صورت بایستی یک درایور سفارشی ایجاد کنید.
به منظور تنظیم و راه اندازی filesystem اختصاصی خود، لازم است یک service provider همچون DropboxServiceProvider ایجاد نمایید. حال جهت تعریف یک درایور اختصاصی می بایست داخل متد boot، تابع extend فاساد Storage را به صورت زیر فرابخوانید:

<?php
namespace App\Providers;
use Storage;
use League\Flysystem\Filesystem;
use Dropbox\Client as DropboxClient;
use Illuminate\Support\ServiceProvider;
use League\Flysystem\Dropbox\DropboxAdapter;
class DropboxServiceProvider extends ServiceProvider
{
   /**
    * Perform post-registration booting of services.
    *
    * @return void
    */
   public function boot()
   {
       Storage::extend('dropbox', function($app, $config) {
           $client = new DropboxClient(
               $config['accessToken'], $config['clientIdentifier']
           );
           return new Filesystem(new DropboxAdapter($client));
       });
   }
   /**
    * Register bindings in the container.
    *
    * @return void
    */
   public function register()
   {
      //
   }
}

اولین آرگومان متد extend، اسم درایور و دومین آرگومان یک تابع Closure هست که دو متغیر $app و $configرا به عنوان پارامتر ورودی دریافت می کند. تابع Closure باید در خروجی یک نمونه از League\Flysystem\Filesystem را برگرداند. متغیر $config دربردارنده ی مقادیر تعریف شده در فایل config/filesystems.php دیسک مشخص شده می باشد. پس از اینکه service provider مورد نظر را برای ثبت افزونه (extension) ایجاد کردید، می توانید درایور dropbox موجود در فایل تنظیماتconfig/filesystem.php را مورد استفاده قرار دهید.