Amazon S3 (Cloud Storage)

The artiframe add s3 extension liberates your projects from the limitations of the local file system (disk space issues, backup costs) and connects them to Object Storage providers like AWS S3, DigitalOcean Spaces, MinIO, or Cloudflare R2. It abstracts the operations of the complex aws/aws-sdk-php package and exposes them as smooth methods under the src/Service/S3Storage.php class.

1. Installation and Configuration

To install the extension, type the following command in your terminal:

terminal

$ artiframe add s3

Then enter your access credentials obtained from your Storage provider into your .env file:

.env

AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_DEFAULT_REGION=eu-central-1
AWS_BUCKET=my-app-storage

# Optional: If you are using a non-AWS S3 service (MinIO, DO Spaces):
# AWS_ENDPOINT=https://fra1.digitaloceanspaces.com

Broad Compatibility: The moment you provide the AWS_ENDPOINT variable, ArtiFrame's S3 service automatically begins to integrate seamlessly with any S3-compatible cloud provider (Cloudflare R2, Minio, etc.).

2. File Upload

It's possible to transfer a physical file on your server to the cloud, or directly write text-based data (without creating a temporary file) to the cloud.

1. Physical File Upload

example.php

<?php
use Src\Service\S3Storage;

$s3 = new S3Storage();

// Save the avatar.jpg on the local server as 'users/avatars/1.jpg' on the cloud
// The 3rd Parameter (public-read) allows the file to be read via a direct URL
$result = $s3->upload('/var/www/tmp/avatar.jpg', 'users/avatars/1.jpg', 'public-read');

if ($result['status'] === true) {
    echo "Uploaded! URL: " . $result['url'];
} else {
    echo "Error: " . $result['error'];
}

2. Uploading String / Raw Data

Sometimes you need to directly send a dynamically generated JSON, CSV, or HTML data to the cloud without saving it to the disk.

example.php

<?php
$json = json_encode(['name' => 'Ali', 'age' => 30]);

// Directly write the string to the cloud without creating a file on disk (application/json)
$result = $s3->uploadFromString($json, 'exports/data.json', 'application/json', 'private');

3. Link Generation (Public & Private)

Public URL

If you uploaded the file with public permissions (e.g., Logos, CSS files):

example.php

<?php
$publicUrl = $s3->url('users/avatars/1.jpg');
// Output: https://bucket-name.s3.eu-central-1.amazonaws.com/users/avatars/1.jpg

Pre-Signed (Temporary) URL

Secure links meant for private files (e.g., purchased e-book, personal invoice) that become inaccessible once the URL expires.

example.php

<?php
// This link will only be accessible for 15 minutes
$temporaryLink = $s3->signedUrl('private/invoices/INV-100.pdf', 15);

echo "<a href='{$temporaryLink}'>Download Invoice</a>";

4. Download and Delete

For pulling data from the cloud to your server or deleting it from the cloud (to free up space).

example.php

<?php
// 1. Download the file from the cloud to the local server
$s3->download('exports/data.json', '/var/www/downloads/data.json');

// 2. Single file deletion
$s3->delete('users/avatars/1.jpg');

// 3. Bulk Delete - Sends bulk requests to avoid hitting S3 API limits
$s3->deleteMany([
    'logs/old-log-1.txt',
    'logs/old-log-2.txt'
]);

5. File Management and Checking Methods

Method	Parameters	Description
exists()	string remotePath	Checks if the file exists in the cloud (returns bool).
list()	string prefix	Lists the files under the specified folder. Returns an array: `[ ['key'=>'...', 'size'=>..., 'last_modified'=>'...'], ... ]`
copy()	string from, string to	Copies a file in the cloud to another name/folder.
move()	string from, string to	First copies (copy), then deletes the old one (delete). Effectively renames/moves it.
size()	string remotePath	Returns the file size in bytes. It is extremely fast because it only checks the Header (headObject) without downloading the file.