العمل مع S3 والتخزين السحابي في PHP: دليل شامل

العمل مع S3 والتخزين السحابي في PHP

\n\n

أصبحت التخزينات الكائنية السحابية المتوافقة مع بروتوكول Amazon S3 (خدمة التخزين البسيطة) المعيار الفعلي لتخزين الملفات والصور والنسخ الاحتياطية والمحتوى الثابت. توفر PHP أدوات قوية للتكامل مع هذه التخزينات مثل AWS S3 وMinIO (مستضاف ذاتيًا) وDigitalOcean Spaces وWasabi وYandex Object Storage وغيرها. في هذه المقالة، سننظر بالتفصيل في كيفية العمل مع التخزينات المتوافقة مع S3 في PHP باستخدام AWS SDK الرسمي والمكتبات البديلة.

\n\n

المفاهيم الأساسية لـ S3

\n\n

قبل الانتقال إلى الكود، من المهم فهم المفاهيم الرئيسية لـ S3:

\n

\n
• الحاوية (Bucket) — حاوية للكائنات (الملفات). يجب أن يكون اسم الحاوية فريدًا عالميًا (للسحب العامة).
\n
• الكائن (Object) — ملف وبياناته الوصفية. كل كائن له مفتاح (Key) — مسار الملف داخل الحاوية.
\n
• المنطقة (Region) — الموقع الجغرافي للتخزين.
\n
• بيانات الاعتماد (Credentials) — مفتاح الوصول (Access Key ID) والمفتاح السري (Secret Access Key) للمصادقة.
\n
• نقطة النهاية (Endpoint) — عنوان URL للتخزين (لخدمات S3 المتوافقة غير AWS، نقطة النهاية إلزامية).
\n

\n\n

تثبيت AWS SDK لـ PHP

\n\n

المكتبة الرسمية للعمل مع S3 هي aws/aws-sdk-php. التثبيت عبر Composer:

\n\n

composer require aws/aws-sdk-php

\n\n

للعمل مع MinIO أو DigitalOcean Spaces، لا حاجة لتبعيات إضافية — يدعم SDK نقاط النهاية المخصصة.

\n\n

الإعداد الأساسي لعميل S3

\n\n

لنقم بإنشاء عميل للاتصال بـ AWS S3:

\n\n

<?php\nrequire 'vendor/autoload.php';\n\nuse Aws\\S3\\S3Client;\nuse Aws\\Exception\\AwsException;\n\n$s3Client = new S3Client([\n    'version'     => 'latest',\n    'region'      => 'us-east-1',\n    'credentials' => [\n        'key'    => 'YOUR_ACCESS_KEY',\n        'secret' => 'YOUR_SECRET_KEY',\n    ],\n]);\n?>

\n\n

بالنسبة لـ MinIO (تخزين محلي متوافق مع S3)، سيكون التكوين كالتالي:

\n\n

<?php\n$s3Client = new S3Client([\n    'version'     => 'latest',\n    'region'      => 'us-east-1', // MinIO يتجاهل المنطقة\n    'endpoint'    => 'http://localhost:9000',\n    'use_path_style_endpoint' => true,\n    'credentials' => [\n        'key'    => 'minioadmin',\n        'secret' => 'minioadmin',\n    ],\n]);\n?>

\n\n

لاحظ المعامل use_path_style_endpoint — فهو ضروري لـ MinIO وبعض التخزينات غير AWS.

\n\n

إدارة الحاويات

\n\n

إنشاء حاوية

\n\n

<?php\ntry {\n    $result = $s3Client->createBucket([\n        'Bucket' => 'my-php-bucket',\n    ]);\n    echo "تم إنشاء الحاوية: " . $result['Location'];\n} catch (AwsException $e) {\n    echo "خطأ: " . $e->getMessage();\n}\n?>

\n\n

التحقق من وجود الحاوية

\n\n

<?php\n$exists = $s3Client->doesBucketExist('my-php-bucket');\nif ($exists) {\n    echo "الحاوية موجودة";\n} else {\n    echo "الحاوية غير موجودة";\n}\n?>

\n\n

قائمة جميع الحاويات

\n\n

<?php\n$buckets = $s3Client->listBuckets();\nforeach ($buckets['Buckets'] as $bucket) {\n    echo $bucket['Name'] . " (تم إنشاؤها: " . $bucket['CreationDate'] . ")<br>";\n}\n?>

\n\n

رفع الملفات إلى S3

\n\n

الرفع من نص (بيانات نصية)

\n\n

<?php\ntry {\n    $result = $s3Client->putObject([\n        'Bucket' => 'my-php-bucket',\n        'Key'    => 'hello.txt',\n        'Body'   => 'Hello, S3 from PHP!',\n    ]);\n    echo "تم رفع الملف. الرابط: " . $result['ObjectURL'];\n} catch (AwsException $e) {\n    echo "خطأ في الرفع: "