کار با فایل‌ها و پوشه‌ها

پیش‌نیازها

در صورتی که با سرویس فایل آشنایی ندارید، به معرفی سرویس فایل مراجعه کنید.
در صورتی که هنوز در پنل توسعه‌دهنده خود تنظیمات لازم برای سرویس فایل خود را انجام نداده‌اید، به تنظیمات پنل مراجعه کنید.
در صورتی که با سرویس کاربران بکتوری آشنایی ندارید، به معرفی سرویس کاربران مراجعه کنید.
در صورتی که هنوز SDK PHP بکتوری را راه‌اندازی نکرده‌اید، به راه‌اندازی SDK PHP مراجعه کنید.

کار با پوشه‌ها

ایجاد یک پوشه

برای ایجاد یک پوشه در بکتوری از تابع createDirectory استفاده می‌کنیم. این تابع یک مسیر، به عنوان مسیر ساخت پوشه از شما دریافت می‌کند و پوشه را در مسیر ذکر شده می‌سازد. لازم به ذکر است که تمام پوشه‌های مسیر، در صورتی که وجود نداشته‌باشند ساخته ‌خواهند شد.

BacktoryStorage::createDirectory("dir1/dir2/dir3");

خروجی این تابع true در صورت موفقیت‌آمیز بودن و false در صورت fail شدن است.

بدست آوردن اطلاعات یک پوشه

برای بدست‌آوردن اطلاعات تمام فایل‌ها و پوشه‌های درون یک پوشه از تابع directoryInfo استفاده می‌کنیم. ممکن است فایل‌ها و پوشه‌های درون یک پوشه زیاد باشند، به همین علت به صورت صفحه بندی شده در اختیار شما قرار می‌گیرند. . شما می‌توانید تعداد آیتم‌های هر صفحه را تعیین کنید (حداکثر ۵۰ تا).

ورودی‌های این تابع عبارت‌اند از:

path: ‌مسیر پوشه‌ای که اطلاعات آن را می‌خواهیم.
pageNumber: شماره صفحه.
pageSize: تعداد آیتم‌ها در هر صفحه.
field: برای مشخص کردن این که نتایج بر حسب چه ویژگی‌ای مرتب شده‌باشند.‌
sort: نحوه مرتب سازی، یکی از دو مقدار ASC(صعودی) یا DES(نزولی) را می‌گیرد.

هر یک از ورودی ها اختیاری هستند، مقدار پیش‌فرض برای هرکدام به ترتیب عبارت است از: “/” و “0” و “50” و “id” و “ASC”. همچنین مقادیر مورد قبول برای field عبارت‌اند از: “url”و”fileSizeInBytes”و”numberOfDirectChildren”و”creationDate” که url درواقع همان نام فایل می‌باشد.

خروجی این تابع آرایه‌ای حاوی اطلاعات هر فایل یا پوشه‌ی درون پوشه است، اطلاعات آبجکت‌هایی هستند با مقادیر زیر:

guid, url, ownerId, creationDate, lastModificationDate, isDirectory, level, fileSizeInBytes, realFileSizeInBytes, numberOfDirectChildren, numberOfTotalChildren, md5Hash, crcHash, thumbnails, defaultThumbnail, metaData

نمونه استفاده‌ از این تابع:

$obj = BacktoryStorage::directoryInfo("dir1")[0];
echo $obj -> isDirectory;
print_r(BacktoryStorage::directoryInfo("dir1",0,50,"numberOfDirectChildren", "ASC"));

کار با ‌فایل‌ها

آپلود یک فایل

برای آپلود کردن یک فایل روی سرور بکتوری از تابع put استفاده‌ می‌کنیم. ورودی‌های این تابع عبارت‌اند از:

fileOrPath: یک فایل یا آدرس آن.
backtoryStoragePath: محل آپلود در بکتوری، این آرگومان اختیاری است و مقدار پیش‌فرض آن “/” می‌باشد. همچنین در صورتی که آدرس داده شده وجود نداشته‌باشد سرویس فایل آن را ایجاد ‌خواهد‌کرد.
replace:‌ اگر فایل با این نام موجود بود، جایگزین شود یا خیر. این آرگومان اختیاری است و مقدار پیش فرض آن false می‌باشد.

BacktoryStorage::put( __DIR__ . "file 1.txt", "dir1/dir2");
BacktoryStorage::put( fopen("file2.txt",'r'), "dir1/dir2", "true" );

خروجی این تابع در صورت موفقیت‌آمیز بودن آپلود، آدرس فایل آپلود شده و در صورت fail شدن، پیغام خطای سرور می‌باشد.

در صورتی که نام فایل شما حاوی حروف فارسی یا کاراکتر‌هایی مثل فاصله باشد هنگام آپلود نام آن‌ها تغییر می‌کند و اینجا پاسخ سرور مهم خواهد بود.

نمونه پاسخ سرور برای فایل با نام file 1:

Array ( [0] => /dir1/dir12/file+1.txt )

آپلود چند فایل باهم

برای آپلود دسته‌ای فایل‌ها از تابع putFiles استفاده می‌کنیم. این تابع به عنوان ورودی آرایه‌ای از associative arrayها می‌گیرد. هر کدام از associative arrayها باید دارای مقادیر زیر باشند:

file: فایل یا آدرس فایلی که قصد آپلود آن را دارید.
path: پوشه مورد نظر در بکتوری برای آپلود(اختیاری).
replace: در صورت وجود فایل با این نام، جایگزین شود یا خیر(اختیاری).

نمونه استفاده از تابع:

BacktoryStorage::putFiles([
    [
        "file" =>  "/home/root/docs/file1.txt",
        "path" => "dir1/dir2"
        "replace" => "true"
    ],
    [
        "file" =>  __DIR__ . "/file2.txt",
    ],
    [
        "file" => fopen( "file3.txt", 'r'),
        "path" => "dir1"
    ]
]);

خروجی این تابع در صورت موفقیت‌آمیز بودن آپلود، آرایه‌ای حاوی آدرس‌های فایل‌های آپلود شده و در صورت fail شدن، پیغام خطای سرور می‌باشد.

بدست آوردن اطلاعات یک فایل

برای بدست اوردن اطلاعات مربوط به یک فایل از تابع fileInfo استفاده می‌کنیم. این تابع مسیر یک فایل در بکتوری را می‌گیرد و اطلاعات مربوط به آن از قبیل

guid, url, ownerId, creationDate, lastModificationDate, fileSizeInBytes, realFileSizeInBytes, md5Hash, crcHash, thumbnails, defaultThumbnail, metaData

را در قالب یک associative array بازمی‌گرداند. نمونه استفاده از این تابع:

$response = BacktoryStorage::fileInfo("dir1/file1.txt");
echo $response["guid"];

تعویض نام فایل(rename)

دو تابع rename و renameFiles برای تعویض نام فایل‌‌ها استفاده می‌شوند. تابع rename دو ورودی می‌گیرد، آدرس فایل مورد نظر در بکتوری و نام جدید آن، همچنین تابع renameFiles یک آرایه ورودی می‌گیرد که حاوی آرایه‌هایی با آدرس و نام جدید فایل‌ها است.خروجی تابع آرایه حاوی آدرس جدید فایل‌ها می‌باشد. نمونه استفاده از توابع:

 BacktoryStorage::rename("dir1/file1.txt", "newFile1.txt");
 BacktoryStorage::renameFiles([
     ["dir2/file2.txt", "newFile2.txt"],
     ["dir1/file3.txt", "newFile3.txt"]
 ]);

نمونه خروجی توابع:

 Array ( [0] => notduplicate/dir1/newFile1.txt )
 Array ( [0] => notduplicate/dir2/newFile2.txt [1] => notduplicate/dir1/newFile3.txt )

دقت کنید که notduplicate نام مخزن شما می‌باشد.

بدست آوردن آدرس یک فایل

زمانی که فایلی را روی بکتوری آپلود می‌کنید، آدرس آن به صورت زیر می‌باشد:

http://storage.backtory.com/<bucket-name>/<path>/<FILENAME>.<EXTENTION>

SDK این امکان را در اختیار شما قرار می‌دهد که با استفاده از تابع url این آدرس را بدست آورید:

BacktoryStorage::url("dir4/file+1.txt");

توجه: نام فایل باید نامی باشد که هنگام آپلود سرور به شما بازگردانده است! مثال بالا نام فایل file 1 بوده که پس از آپلود به file+1 تبدیل شده‌است.

وجود یک فایل

در صورتی که بخواهیم بدانیم فایلی در پوشه مشخصی وجود دارد یا نه از تابع exists استفاده می‌کنیم:

BacktoryStorage::exists("/dir1/test.txt");

خروجی این تابع true به ازای وجود فایل و false به ازای ناموجود بودن آن می‌باشد.

کار‌های مشترک (copy/move)

copy

در صورتی که قصد کپی کردن یک یا چند فایل و پوشه را که همگی دارای پدر مشترک هستند (یعنی در یک پوشه یکسان جای دارند) را داشته‌باشیم از تابع copy استفاده می‌‌کنیم. این تابع یک آدرس یا آرایه‌ای از آدرس‌‌‌های فایل‌ها را به همراه آدرس مقصد می‌گیرد و فایل‌های مشخص‌ شده را در مقصد جدید کپی می‌کند. همچنین می‌توان یک آرگومان اختیاری force را که مقدر true یا false می‌گیرد به آن ورودی داد که مشخص کننده این است که اگر فایلی با نام یکسان در مقصد وجود داشت، جایگزین شود یا خیر، مقدار پیش‌فرض برای این آرگومان false می‌باشد.

BacktoryStorage::copy("dir2/file2.txt", "newDir");
BacktoryStorage::copy(["dir1/file1.txt", "dir1/file3.txt"], "newDir", "true");

خروجی این تابع true به ازای موفقیت‌آمیز بودن و false به ازای fail شدن عملیات می‌باشد. توجه داشته باشید که آدرس جدید مشخص شده باید وجود داشته‌باشد.

move

در صورتی که قصد move یا همان کات کردن یک یا چند فایل و پوشه را که همگی دارای پدر مشترک هستند (یعنی در یک پوشه یکسان جای دارند) را داشته‌باشیم از تابع move استفاده می‌‌کنیم. این تابع یک آدرس یا آرایه‌ای از آدرس‌‌‌های فایل‌ها را به همراه آدرس مقصد می‌گیرد و فایل‌های مشخص‌ شده به در مقصد جدید انتقال می‌دهد. همچنین می‌توان یک آرگومان اختیاری force را که مقدر true یا false می‌گیرد به آن ورودی داد که مشخص کننده این است که اگر فایلی با نام یکسان در مقصد وجود داشت، جایگزین شود یا خیر، مقدار پیش‌فرض برای این آرگومان false می‌باشد.

BacktoryStorage::move("dir2/file2.txt", "newDir");
BacktoryStorage::move(["dir1/file1.txt", "dir1/file3.txt"], "newDir", "false");

دانلود

برای دانلود کردن فایلی از سرور بکتوری از تابع get استفاده می‌کنیم. این تابع به عنوان ورودی می‌تواند ۳ آرگومان بگیرد، اولی که اجباری می‌باشد مسیر فایل در بکتوری است، در صورتی که تنها این آرگومان وارد شود خروجی تابع فایل درخواستی شما خواهد‌بود. آرگومان دوم که ورود آن اختیاری است مسیر دانلود است که همان مسیری است که می‌خواهید فایل در آن‌جا در سیستم شما ذخیره شود، در صورت وارد شدن این مقدار، خروجی تابع نتیجه دانلود خواهد بود، ture برای موفقیت و false برای fail شدن. آرگومان سوم که ورود آن هم اختیاری است نام جدید برای دانلود فایل است، در صورتی که این آرگومان را وارد کنید فایل دانلود شده با این اسم روی سیستم شما ذخیره خواهد شد.

$content = BacktoryStorage::get("/dir1/file1.txt");
BacktoryStorage::get("/dir1/file1.txt", "/local/path");
BacktoryStorage::get("/dir1/file3.txt", "/local/path" , "newFile");

افزودن هدر و پارامتر‌

در صورتی که از وب‌هوک استفاده می‌کنید یا می‌خواهید به هر دلیل دیگری اطلاعات اضافه‌ای را ارسال کنید، میتوانید با اسفاده از SDK هدرها و پارامترهای دلخواه خودتان را همراه با درخواست ارسال نمایید. برای این کار از توابع setHeader و setParameters می‌توان استفاده کرد.

 BacktoryStorage::setHeader(["h1" => "v1"]);
 BacktoryStorage::setParameters(["p1" => "v1"]);

استفاده از این توابع مقادیر قبلی را پاک خواهد کرد.

و در صورتی که قصد اضافه کردن هدر یا پارامتر به مقادیر ست شده قبلی را دارید می‌توانید از توابع addParameter و addHeader استفاده نمایید.

 BacktoryStorage::addHeader("h2", "v2");
  BacktoryStorage::addParameter("p1", "v2");

این توابع خروجی ندارند.

به این ترتیب با تمام امکانات SDK آشنا شده‌اید. همچنین پس از نصب SDK در پوشه vendor/backtory/storage-php/example می‌توانید در فایل examle.php نمونه‌هایی از کدهای آورده شده در این مستند را مشاهده نمایید.

کار با فایل‌ها و پوشه‌ها - PHP