CakeDC Blog

Uploading Files with CakePHP and Uppy: Direct to S3

Modern web applications increasingly require fast, resilient, and user‑friendly file uploads. Whether it’s profile photos, documents, or large media files, users expect progress indicators, drag‑and‑drop, and reliable uploads even on unstable connections.

In this article, we’ll look at how to combine CakePHP on the backend with Uppy on the frontend, and how to upload files directly to Amazon S3 using signed requests.

Why Uppy for Direct S3 Uploads??

Uppy is a modular JavaScript file uploader built by the team behind Transloadit. It provides a polished upload experience out of the box and integrates well with modern backends.

Key advantages

• Direct-to-Cloud Uploads: File data flows directly from the user's browser to the S3 bucket, without passing through your CakePHP server.
  • Lower Server Load and Cost: Your server only generates a short-lived, secure pre-signed URL. The actual file transfer avoids the “double handling,” drastically reducing your application's bandwidth consumption and infrastructure footprint.
  • Better Performance: By eliminating your application server as a middleman, uploads complete faster. Uppy can also utilize S3's multipart upload capabilities for improved throughput and reliability for large files.
• Excellent UX: Drag-and-drop support, progress bars, previews, and retry support.
• Modular Architecture: Only load the necessary plugins.
• Framework‑agnostic: Works seamlessly with CakePHP.

Architecture Overview

• This scalable and production-friendly approach uses the following flow:

• The browser initializes Uppy.

• CakePHP provides temporary S3 credentials or signed URLs (Authorization).

• Uppy uploads files directly to S3 (Data Transfer).

• CakePHP stores metadata (filename, path, size, etc.) if needed (Database Record).

Architecture Overview

This scalable and production-friendly approach uses the following flow:

1. The browser initializes Uppy
2. CakePHP provides temporary S3 credentials or signed URLs (Authorization)
3. Uppy uploads files directly to S3 (Data Transfer).
4. CakePHP stores metadata (filename, path, size, etc.) if needed (Database Record).

Prerequisites

• CakePHP 5.x (or 4.x with minor adjustments)
• AWS account with an S3 bucket
• AWS SDK for PHP
• A modern browser to use Uppy's MJS modules

Installing Dependencies

Backend (CakePHP)

Install the required AWS SDK for PHP via Composer:

composer require aws/aws-sdk-php

Configure your AWS credentials (environment variables recommended):

AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
AWS_REGION=eu-west-1
AWS_BUCKET=your-bucket-name

Frontend (Uppy)

Instead of a build step, we will use Uppy's modular JS files directly from a Content Delivery Network (CDN), which is simpler for many CakePHP applications.

We will load the required modules—Uppy, Dashboard, and AwsS3—directly within the <script type="module"> tag in your view.

Creating the CakePHP Endpoint

We need a CakePHP endpoint to securely generate and return the necessary S3 upload parameters (the pre-signed URL) to the browser.

Controller

// src/Controller/UploadsController.php

namespace App\Controller;

use Aws\S3\S3Client;
use Cake\Http\Exception\UnauthorizedException;

class UploadsController extends AppController
{
    public function sign()
    {
        $this->getRequest()->allowMethod(['post']);

        // 1. Initialize S3 Client using credentials from environment
        $s3Client = new S3Client([
            'version' => 'latest',
            'region' => env('AWS_REGION'),
            'credentials' => [
                'key' => env('AWS_ACCESS_KEY_ID'),
                'secret' => env('AWS_SECRET_ACCESS_KEY'),
            ],
        ]);

        // Define a unique path with a placeholder for the actual filename
        $path = 'uploads/' . uniqid() . '/${filename}';

        // 2. Create the command for a PutObject request
        $command = $s3->getCommand('PutObject', [
            'Bucket' => env('AWS_BUCKET');,
            'Key' => $path,
            'ACL' => 'private',
            'ContentType' => '${contentType}',
        ]);

        // 3. Generate the pre-signed URL (valid for 15 minutes)
        $presignedRequest = $s3->createPresignedRequest($command, '+15 minutes');

        $this->set([
            'method' => 'PUT',
            'url' => (string)$presignedRequest->getUri(),
            '_serialize' => ['method', 'url'],
        ]);
    }
}

Add a route:

// config/routes.php

$routes->post('/uploads/s3-sign', ['controller' => 'Uploads', 'action' => 'sign']);

Frontend: Initializing Uppy and the S3 Plugin

Place the following code in your CakePHP view along with the HTML container for the uploader:

<div id="uploader"></div>

<script type="module">
  // Load Uppy modules directly from CDN (v5.2.1 example)
  import {
    Uppy,
    Dashboard,
    AwsS3
  } from 'https://releases.transloadit.com/uppy/v5.2.1/uppy.min.mjs'

  const uppy = new Uppy({
    autoProceed: false,
    restrictions: {
      maxNumberOfFiles: 5,
      allowedFileTypes: ['image/*', 'application/pdf'],
    },
  })

  uppy.use(Dashboard, {
    inline: true,
    target: '#uploader',
  })

  // Configure the AwsS3 plugin to fetch parameters from the CakePHP endpoint
  uppy.use(AwsS3, {
    async getUploadParameters(file) {
      const response = await fetch('/uploads/s3-sign', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
      })

      const data = await response.json()

      // 2. Return the parameters Uppy needs for the direct upload
      return {
        method: data.method,
        url: data.url,
        headers: {
          'Content-Type': file.type,
        },
      }
    },
  })

  uppy.on('complete', (result) => {
    console.log('Upload complete:', result.successful)
  })
</script>

Storing File Metadata (Optional but Recommended)

Once the direct S3 upload is successful, you must notify your CakePHP application to save the file's metadata (e.g., the S3 key) in your database.

uppy.on('upload-success', (file, response) => {
  fetch('/files/save', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: file.name,
      size: file.size,
      type: file.type,
      s3_key: response.uploadURL,
    }),
  })
})

Security Considerations

Remember to implement robust security checks in your sign controller action:

• Authenticate users: Ensure the user is logged in and authorized before issuing S3 parameters.
• Restrict Input: Restrict allowed MIME types and maximum file size.
• Access Control: Use private S3 buckets and serve files via signed URLs to maintain security.
• Time Limit: Set short expiration times for the pre-signed requests (e.g., the +15 minutes in the example).

Conclusion

Combining CakePHP and Uppy gives you the best of both worlds: a robust PHP backend and a modern, user‑friendly upload experience. By uploading directly to Amazon S3, you reduce server load, successfully reduce server load, improve scalability, and ensure reliable, fast large file uploads.

This setup allows your backend to focus on validation, authorization, and business logic rather than raw data transfer.