PP مستندات فضای ابری پارس‌پک
PHP 8.1+ · AWS SDK for PHP v3

S3Client را برای پارس‌پک پیکربندی کنید

این نمونه با AWS SDK for PHP کار می‌کند. مشخصات اتصال از .env خوانده می‌شود، Client با Endpoint اختصاصی ساخته می‌شود و عملیات مهم، از PutObject تا URL امضاشده، با کد قابل اجرا نشان داده می‌شود.

AWS SDK v3خروجی JSONPresigned GET و PUT
برنامه PHP متصل به فضای ذخیره‌سازی
PHP lint و تست درخواست موفق

فایل hello.txt با Key برابر tutorial/hello.txt آپلود می‌شود. سپس کد، وجود فایل و متادیتای آن را چک می‌کند، دانلود و URL موقت را می‌سنجد و در پایان Object آزمایشی را حذف می‌کند.

این ترتیب را حفظ کنید: خطای 404 در head یا download پیش از آپلود، نشانهٔ خرابی اتصال نیست؛ Object هنوز وجود ندارد.

۱

پیش‌نیاز و ساختار پروژه

PHP 8.1 یا جدیدتر و Composer برای اجرای نمونه لازم است.

terminal
php -v
composer --version
ساختار فایل‌ها
examples/php/
├── .env                 # پس از کپی‌کردن فایل نمونه ساخته می‌شود
├── composer.json        # وابستگی‌های PHP
├── composer.lock        # نسخه دقیق وابستگی‌ها
└── parspack_s3.php      # Client و هفت فرمان مدیریت فایل
۲

نصب AWS SDK

Composer کتابخانه AWS و فایل Autoload را داخل پوشه vendor می‌سازد.

terminal · از ریشه مستندات
(cd examples/php && composer install)
Generating autoload files
فایل composer.lock همراه پروژه است؛ بنابراین composer install همان نسخه‌های ثبت‌شده را نصب می‌کند. اگر از صفر پروژه می‌سازید، فرمان اصلی composer require aws/aws-sdk-php است.
۳

ساخت فایل .env

پنج مقدار را از پنل فضای ابری پارس‌پک کپی کنید. معنی هر متغیر و شکل معمول Endpoint در صفحه شروع آمده است.

بعد از کپی، فقط مقدارها را عوض کنید؛ نام متغیرها را کوتاه نکنید. اگر اسلش ته Endpoint بماند یا Region را بی‌دلیل عوض کنید، اولین upload با خطای امضا می‌خوابد.
terminal
cp examples/.env.example examples/php/.env
examples/php/.env
PARSPACK_S3_ENDPOINT=https://c123456.parspack.net
PARSPACK_S3_BUCKET=c123456
PARSPACK_S3_REGION=us-east-1
PARSPACK_S3_ACCESS_KEY=YOUR_ACCESS_KEY
PARSPACK_S3_SECRET_KEY=YOUR_SECRET_KEY
متغیرچه چیزی در آن می‌گذاریداگر اشتباه باشد
PARSPACK_S3_ENDPOINTآدرس HTTPS پنل، بدون / در انتها؛ شکل معمول https://c123456.parspack.netTimeout یا خطای امضا
PARSPACK_S3_BUCKETنام باکت؛ اغلب با شناسه داخل Endpoint یکی استNoSuchBucket
PARSPACK_S3_REGIONفقط برای امضای Signature V4 است. اگر پنل Region نداد، us-east-1 را ثابت نگه داریدSignatureDoesNotMatch
PARSPACK_S3_ACCESS_KEY / SECRET_KEYکلیدهای API از پنل؛ فقط روی سرورAccessDenied یا خطای امضا
!

فایل .env را Commit نکنید. Access Key و Secret Key فقط روی سرور می‌مانند؛ مرورگر فقط لینک کوتاه‌عمر می‌گیرد.

۴

اتصال برنامه به فضای پارس‌پک

Client را یک بار با مقدارهای .env بسازید. همین شیء برای هر هفت فرمان کافی است.

این تنظیمات SDK را به باکت شما وصل می‌کند، نه به AWS. endpoint همان آدرس HTTPS پنل است؛ rtrim اسلش انتها را برمی‌دارد. region موقعیت سرور نیست؛ اگر پنل چیزی نگفت us-east-1 را عوض نکنید. use_path_style_endpoint باید true باشد تا URL به شکل /bucket/key ساخته شود.
Access Key و Secret Key فقط روی سرور می‌مانند. مرورگر حداکثر لینک کوتاه‌عمر می‌گیرد. در Laravel یا Symfony همین Client را یک Service مشترک کنید، نه اینکه در هر Request دوباره بسازید.
PHP · اتصال
use Aws\Credentials\Credentials;
use Aws\S3\S3Client;

$env = parse_ini_file(__DIR__ . '/.env', false, INI_SCANNER_RAW);
$bucket = $env['PARSPACK_S3_BUCKET'];

$s3 = new S3Client([
  'version' => 'latest',
  'region' => $env['PARSPACK_S3_REGION'],
  'endpoint' => rtrim($env['PARSPACK_S3_ENDPOINT'], '/'),
  'use_path_style_endpoint' => true,
  'signature_version' => 'v4',
  'credentials' => new Credentials(
      $env['PARSPACK_S3_ACCESS_KEY'],
      $env['PARSPACK_S3_SECRET_KEY']
  ),
  'retries' => 3,
]);
۵

آپلود فایل با PutObject

اولین فرمان سناریو: فایل محلی را با یک نام مشخص در باکت بگذارید.

فایل روی سیستم شما ./hello.txt است؛ داخل باکت با نام tutorial/hello.txt ذخیره می‌شود. اسلش پوشه واقعی نمی‌سازد، فقط بخشی از نام است. ETag اثر انگشت محتواست. اگر همین نام از قبل در باکت باشد، محتوای قبلی عوض می‌شود.
PHP · upload
$localFile = './hello.txt';
$objectKey = 'tutorial/hello.txt';

$result = $s3->putObject([
  'Bucket' => $bucket,
  'Key' => $objectKey,
  'SourceFile' => $localFile,
  'ContentType' => mime_content_type($localFile) ?: 'application/octet-stream',
]);

echo $result['ETag'];
پارامترمثالکاربرد
Bucketاز .envمحل ذخیره فایل
Keytutorial/hello.txtنام کامل فایل در S3
SourceFile./hello.txtفایل موجود روی سیستم
ContentTypetext/plainنوع محتوای فایل
terminal
printf 'hello ParsPack\n' > hello.txt
php examples/php/parspack_s3.php upload ./hello.txt tutorial/hello.txt
خروجی نمونه
{ "ok": true, "operation": "upload", "key": "tutorial/hello.txt", "etag": "..." }
!

اگر tutorial/hello.txt از قبل وجود داشته باشد، Upload جدید همان Key را جایگزین می‌کند.

۶

فهرست فایل‌ها و مشخصات یک فایل

بعد از آپلود، اول ببینید فایل در فهرست هست؛ بعد حجم و نوع را بدون دانلود بخوانید.

list tutorial/ خود فایل را نمی‌آورد؛ فقط نام، حجم و زمان تغییر فایل‌هایی را برمی‌گرداند که با این Prefix شروع می‌شوند. اگر آرایه خالی بود، یا آپلود انجام نشده یا Prefix را اشتباه نوشته‌اید.
head وقتی لازم است که فقط بخواهید بدانید فایل هست یا نه، یا حجم و نوعش چیست. اگر Key نباشد معمولاً 404 می‌گیرید. این فرمان را با دانلود عوض نکنید؛ بدنه فایل را منتقل نمی‌کند.
PHP · ListObjectsV2 paginator
foreach ($s3->getPaginator('ListObjectsV2', [
  'Bucket' => $bucket,
  'Prefix' => 'tutorial/',
]) as $page) {
  foreach ($page['Contents'] ?? [] as $object) {
      echo $object['Key'] . ' — ' . $object['Size'] . PHP_EOL;
  }
}
PHP · HeadObject
$info = $s3->headObject([
  'Bucket' => $bucket,
  'Key' => 'tutorial/hello.txt',
]);

echo $info['ContentLength'];
echo $info['ContentType'];
echo $info['ETag'];
terminal
php examples/php/parspack_s3.php list tutorial/
خروجی نمونه
{ "ok": true, "prefix": "tutorial/", "objects": [ { "key": "tutorial/hello.txt", "bytes": 14, "last_modified": "2026-08-18T10:00:00+00:00" } ] }
terminal
php examples/php/parspack_s3.php head tutorial/hello.txt
خروجی نمونه
{ "ok": true, "key": "tutorial/hello.txt", "bytes": 14, "content_type": "text/plain", "etag": "...", "last_modified": "2026-08-18T10:00:00+00:00" }
اگر فایل‌ها زیاد باشند، Paginator صفحه‌های بعدی را هم می‌گیرد. برای Key ناموجود، Head معمولاً 404 می‌دهد.
۷

دانلود روی سرور

فایل را از باکت بگیرید و روی دیسک همین برنامه بنویسید. این کار لینک برای کاربر نمی‌سازد.

این فرمان فایل را از باکت می‌گیرد و روی دیسک همین برنامه می‌نویسد. کاربر سایت آن را نمی‌بیند مگر خودتان بعداً برایش بفرستید. وقتی به آن نیاز دارید که سرور باید فایل را پردازش کند، در ایمیل ضمیمه کند، یا جای دیگری نگه دارد. پوشه مقصد اگر نباشد، نمونه آن را می‌سازد.
PHP · ذخیره فایل روی سرور
$s3->getObject([
  'Bucket' => $bucket,
  'Key' => 'tutorial/hello.txt',
  'SaveAs' => './downloads/hello.txt',
]);
terminal
php examples/php/parspack_s3.php download tutorial/hello.txt ./downloads/hello.txt
خروجی نمونه
{ "ok": true, "operation": "download", "key": "tutorial/hello.txt", "local_file": "./downloads/hello.txt", "bytes": 14 }
۸

لینک موقت دانلود برای کاربر

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

باکت خصوصی است و کلید API را نباید به کاربر بدهید. این کد فایل را ذخیره نمی‌کند؛ فقط یک URL چند دقیقه‌ای می‌سازد. مثال: کاربر بعد از ورود روی «دانلود فاکتور» می‌زند، سرور مجوز را چک می‌کند، لینک را برمی‌گرداند، مرورگر همان آدرس را باز می‌کند. فایل از سرور شما رد نمی‌شود.
همان URL را در مرورگر باز کنید، در <a href> بگذارید، یا با curl --output file.pdf "$URL" بگیرید. Header اضافه لازم نیست. 900 یعنی پانزده دقیقه؛ بعد از آن آدرس کار نمی‌کند.
PHP · ساخت لینک موقت دانلود
$request = $s3->createPresignedRequest(
  $s3->getCommand('GetObject', [
      'Bucket' => $bucket,
      'Key' => 'tutorial/hello.txt',
  ]),
  '+15 minutes'
);

$url = (string) $request->getUri();
terminal
php examples/php/parspack_s3.php presign-get tutorial/hello.txt 900
خروجی نمونه
{ "ok": true, "operation": "presign-get", "key": "tutorial/hello.txt", "method": "GET", "expires_in": 900, "url": "https://c123456.parspack.net/c123456/tutorial/hello.txt?X-Amz-..." }
curl · گرفتن فایل با لینک موقت دانلود
curl --output invoice.pdf "$SIGNED_DOWNLOAD_URL"
!

لینک را کوتاه نگه دارید؛ بین ۱ ثانیه تا ۷ روز (۶۰۴۸۰۰ ثانیه). فقط همان Key را می‌خواند. لینک را فقط بعد از ورود کاربر و چک مجوز بسازید.

۹

لینک موقت آپلود مستقیم

کاربر فایل را از مرورگر به باکت می‌فرستد. فایل از سرور شما رد نمی‌شود و کلید API هم به کاربر نمی‌رسد.

وقتی کاربر باید فایل را از مرورگر بفرستد، ولی نباید کلید را ببیند و نباید کل فایل از سرور شما عبور کند، سرور نام و نوع را خودش قفل می‌کند و URL می‌سازد. مثال: آپلود عکس پروفایل. کاربر فقط حق دارد همان یک نام را با روش PUT بنویسد.
بدنه فایل را با PUT به همان URL بفرستید و Content-Type را دقیقاً همان مقدار زمان ساخت لینک بگذارید؛ وگرنه معمولاً خطای امضا می‌گیرید. از مرورگر فقط وقتی کار می‌کند که CORS باکت سایت شما را مجاز کرده باشد؛ وگرنه از curl یا سرور خودتان استفاده کنید.
PHP · ساخت لینک موقت آپلود
$contentType = 'text/plain';
$request = $s3->createPresignedRequest(
  $s3->getCommand('PutObject', [
      'Bucket' => $bucket,
      'Key' => 'tutorial/upload.txt',
      'ContentType' => $contentType,
  ]),
  '+15 minutes'
);

$uploadUrl = (string) $request->getUri();
terminal · ساخت لینک آپلود
php examples/php/parspack_s3.php presign-put tutorial/upload.txt text/plain 900
خروجی نمونه
{ "ok": true, "operation": "presign-put", "key": "tutorial/upload.txt", "method": "PUT", "headers": { "Content-Type": "text/plain" }, "expires_in": 900, "url": "https://c123456.parspack.net/c123456/tutorial/upload.txt?X-Amz-..." }
curl · فرستادن فایل با لینک موقت آپلود
curl -X PUT -H 'Content-Type: text/plain' \
--upload-file ./hello.txt "$SIGNED_UPLOAD_URL"
مرورگر · fetch
await fetch(signed.url, {
method: "PUT",
headers: { "Content-Type": signed.headers["Content-Type"] },
body: file,
});
!

اگر موقع ساخت لینک text/plain گذاشته‌اید، هنگام ارسال هم باید همان را بفرستید؛ وگرنه معمولاً خطای امضا می‌گیرید. از مرورگر این کار فقط وقتی درست است که CORS باکت سایت شما را مجاز کرده باشد؛ وگرنه از curl یا سرور خودتان استفاده کنید.

۱۰

حذف فایل با DeleteObject

نام را از باکت برمی‌دارد. لازم نیست اول دانلودش کنید. فایل روی سیستم شما دست نمی‌خورد.

اگر آن نام در باکت نباشد، معمولاً باز هم پاسخ موفق می‌آید. پس خود برنامه باید بداند کدام Key را حذف کرده است، نه اینکه فقط به موفق بودن پاسخ اعتماد کند.
PHP · delete
$s3->deleteObject([
  'Bucket' => $bucket,
  'Key' => 'tutorial/hello.txt',
]);
terminal
php examples/php/parspack_s3.php delete tutorial/hello.txt
خروجی نمونه
{ "ok": true, "operation": "delete", "key": "tutorial/hello.txt" }
۱۱

جزئیات AwsException را نگه دارید

نمونه، پیام خطا را روی stderr می‌نویسد و با کد غیرصفر تمام می‌شود. کد خطای سرویس و Status Code معمولاً سریع‌تر از متن عمومی exception شما را به علت می‌رسانند.

خطاعلت معمولبررسی
Local file not foundمسیر فایل اشتباه استمسیر را نسبت به Terminal بررسی کنید
AccessDeniedکلید یا دسترسی Bucket کافی نیستمقدارهای پنل و نوع دسترسی کاربر فضای ابری
SignatureDoesNotMatchامضای درخواست با تنظیمات یکی نیستSlash انتهای Endpoint، Region، کلیدها و Content-Type در PUT
NoSuchBucketنام Bucket با مقدار پنل یکی نیستPARSPACK_S3_BUCKET
Timeout / connectionEndpoint در دسترس نیست یا HTTPS قطع استآدرس پنل را بدون تغییر و بدون / انتها وارد کنید
PHP · catch
catch (Aws\Exception\AwsException $error) {
  $code = $error->getAwsErrorCode() ?: 'S3Error';
  fwrite(STDERR, $code . ': ' . $error->getMessage() . PHP_EOL);
  exit(1);
}
۱۲

اجرای کامل همین سناریو

کد همراه مستندات تمام Helperهای خواندن .env، اعتبارسنجی ورودی و خروجی JSON را دارد. اگر خروجی هر فرمان شبیه نمونه‌های بالا بود، می‌توانید Key و مسیر را با نام فایل‌های برنامه خودتان عوض کنید.

terminal · از ابتدا تا انتها
(cd examples/php && composer install)
cp examples/.env.example examples/php/.env

# مقدارهای examples/php/.env را کامل کنید
printf 'hello ParsPack\n' > hello.txt
php examples/php/parspack_s3.php upload ./hello.txt tutorial/hello.txt
php examples/php/parspack_s3.php list tutorial/
php examples/php/parspack_s3.php head tutorial/hello.txt
php examples/php/parspack_s3.php download tutorial/hello.txt ./downloads/hello.txt
php examples/php/parspack_s3.php presign-get tutorial/hello.txt 900
php examples/php/parspack_s3.php presign-put tutorial/upload.txt text/plain 900
php examples/php/parspack_s3.php delete tutorial/hello.txt
Laravel / SymfonyS3Client را یک Service مشترک بسازید و عملیات فایل را در StorageService قرار دهید.
ورودی وبقبل از Upload وجود فایل را بررسی کنید و Key را در Backend بسازید.
DatabaseKey خروجی Upload را کنار رکورد مربوط ذخیره کنید تا عملیات بعدی همان مقدار را دریافت کنند.
پاسخ APIخروجی موفق یا خطای SDK را به Status مناسب برنامه خود تبدیل کنید.
پروژهٔ PHP آماده دانلود است.کد کامل به‌همراه composer.json در این zip است؛ کافی است باز کنید و composer install بزنید.
دریافت php.zip