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.

This article is part of the CakeDC Advent Calendar 2025 (December 15th 2025) Did you ever wanted to provide a partial result as part of an existing report? Window functions were added in CakePHP 4.1 and provide a way to pull a rolling result expressed naturally using the ORM. We'll use CakePHP 5 code in this article. Apart from the examples described in the book https://book.cakephp.org/5/en/orm/query-builder.html#window-functions One common scenario where window functions are very useful are rolling results. Imagine we have a transactions table, where account transactions are stored including a dollar amount of the transaction. The following migration would describe an example transactions table class CreateTransactions extends \Migrations\BaseMigration { public function change(): void { $table = $this->table('transactions'); $table ->addColumn('occurred_on', 'date', [ 'null' => false, ]) ->addColumn('debit_account', 'string', [ 'limit' => 255, 'null' => false, ]) ->addColumn('credit_account', 'string', [ 'limit' => 255, 'null' => false, ]) ->addColumn('amount_cents', 'biginteger', [ 'null' => false, 'signed' => false, ]) ->addColumn('currency', 'string', [ 'limit' => 3, 'null' => false, 'default' => 'USD', ]) ->addColumn('reference', 'string', [ 'limit' => 255, 'null' => true, ]) ->addColumn('description', 'string', [ 'limit' => 255, 'null' => true, ]) ->addTimestamps('created', 'modified') ->addIndex(['occurred_on'], ['name' => 'idx_transactions_occurred_on']) ->addIndex(['debit_account'], ['name' => 'idx_transactions_debit_account']) ->addIndex(['credit_account'], ['name' => 'idx_transactions_credit_account']) ->addIndex(['reference'], ['name' => 'idx_transactions_reference']) ->create(); } } Now, let's imagine we want to build a report to render the transaction amounts, but we also want a rolling total. Using a window function, we could define a custom finder like this one: public function findWindowReport( SelectQuery $query, ?string $account, ?Date $from, ?Date $to ): SelectQuery { $q = $query ->select([ 'id', 'occurred_on', 'debit_account', 'credit_account', 'amount_cents', 'currency', 'reference', 'description', ]); // Optional filters if ($account) { $q->where(['debit_account' => $account]); } if ($from) { $q->where(['occurred_on >=' => $from]); } if ($to) { $q->where(['occurred_on <=' => $to]); } $runningWin = (new WindowExpression()) ->partition('debit_account') ->orderBy([ 'occurred_on' => 'ASC', 'id' => 'ASC' ]); $q->window('running_win', $runningWin); $q->select([ 'running_total_cents' => $q ->func()->sum('amount_cents') ->over('running_win'), ]); return $q->orderBy([ 'debit_account' => 'ASC', 'occurred_on' => 'ASC', 'id' => 'ASC' ]); } Note the WindowExpression defined will sum the amount for each debit_account to produce the running_total_cents. The result of the report, after formatting will look like this Occurred On Debit Account Credit Account Amount (USD) Running Total (USD) 1/3/25 assets:bank:checking income:services $2,095.75 $2,095.75 1/3/25 assets:bank:checking income:sales $2,241.42 $4,337.17 1/7/25 assets:bank:checking income:services $467.53 $4,804.70 1/10/25 assets:bank:checking income:subscriptions $2,973.41 $7,778.11 1/12/25 assets:bank:checking income:sales $2,747.07 $10,525.18 1/17/25 assets:bank:checking income:subscriptions $2,790.36 $13,315.54 1/21/25 assets:bank:checking income:subscriptions $1,891.35 $15,206.89 1/28/25 assets:bank:checking equity:owner $353.00 $15,559.89 Other typical applications of window functions are leaderboards (building paginated rankins with scores, sales, activities), analytics for cumulative metrics (like inventory evolution) and comparison between rows (to compute deltas) and de-duplication (to pick the most recent record for example). This is a very useful tool to provide a solution for these cases, fully integrated into the CakePHP ORM. This article is part of the CakeDC Advent Calendar 2025 (December 15th 2025)

This article is part of the CakeDC Advent Calendar 2025 (December 2th 2025)

CounterCacheBehavior in CakePHP: what it is, when to use it, and what’s new in CakePHP 5.2

As your application grows, a very common pattern appears: you need to display things like “number of comments”, “number of tasks”, or “number of orders”, and you need to do it fast. Calculating these values with COUNT() queries can work until performance starts to suffer (and complexity increases because of filters, states, or joins). This is exactly where CounterCacheBehavior* becomes useful.

What is CounterCacheBehavior?

CounterCacheBehavior is a CakePHP ORM behavior that keeps a counter field in a “parent” table synchronized based on the records in a related table. Typical example:

• Articles hasMany Comments
• You want to store the number of comments in articles.comment_count

The behavior automatically increments, decrements, or recalculates that value when related records are created, deleted, or modified.

When should you use it?

Common use cases include:

• Listings with counters (e.g. “Posts (123 comments)”).
• Sorting by counters (most commented, most active, etc.).
• Filtering by counters (categories with more than X products).
• Avoiding repeated and expensive COUNT( ) queries.

The idea is simple: accept a small cost on writes in exchange for much faster reads.

Basic configuration

CounterCache is configured in the child table (the one that belongs to the parent). If Comments belongsTo Articles, the behavior lives in CommentsTable. // src/Model/Table/CommentsTable.php namespace App\Model\Table; use Cake\ORM\Table; class CommentsTable extends Table { public function initialize(array $config): void { parent::initialize($config); $this->belongsTo('Articles'); $this->addBehavior('CounterCache', [ 'Articles' => ['comment_count'] ]); } } Doing this, CakePHP will automatically keep articles.comment_count up to date.

CounterCache with conditions (scoped counters)

Often you don’t want to count everything, but only a subset: published comments, active records, non-spam items, etc. $this->addBehavior('CounterCache', [ 'Articles' => [ 'published_comment_count' => [ 'conditions' => ['Comments.is_published' => true] ] ] ]); This pattern is very useful for dashboards such as:

• open issues.
• completed tasks.
• approved records.

CounterCache with callbacks (custom calculations)

In some cases, conditions are not enough and you need more complex logic (joins, dynamic filters, or advanced queries). CounterCacheBehavior allows you to define a callable to calculate the counter value. Important: when using callbacks, bulk updates with updateCounterCache() will not update counters defined with closures. This is an important limitation to keep in mind.

What’s new in CakePHP 5.2: rebuild counters from the console

Before CakePHP 5.2, rebuilding counters often meant writing your own scripts or commands, especially after:

• bulk imports done directly in the database.
• manual data fixes.
• adding a new counter cache in production.
• data becoming out of sync.

New command: bashbin/cake counter_cache CakePHP 5.2 introduced an official command to rebuild counter caches: bin/cake counter_cache --assoc Comments Articles This command recalculates all counters related to Comments in the Articles table. Processing large tables in batches For large datasets, you can rebuild counters in chunks: bin/cake counter_cache --assoc Comments --limit 100 --page 2 Articles When using --limit and --page, records are processed ordered by the table’s primary key. This command is ideal for maintenance tasks and for safely backfilling new counter caches without custom tooling.

What’s new in CakePHP 5.2: bulk updates from the ORM

In addition to the console command, CakePHP 5.2 added a new ORM method: CounterCacheBehavior::updateCounterCache() This allows you to update counters programmatically, in batches: // Update all configured counter caches in batches $this->Comments->updateCounterCache(); // Update only a specific association, 200 records per batch $this->Comments->updateCounterCache('Articles', 200); // Update only the first page $this->Comments->updateCounterCache('Articles', page: 1); This is available since CakePHP 5.2.0.

Complete practical example: Articles and Comments

Assume the following database structure:

• articles: id, title, comment_count (int, default 0), published_comment_count (int, default 0).
• comments: id, article_id, body, is_published.

1) Behavior configuration in CommentsTable:

$this->addBehavior('CounterCache', [ 'Articles' => [ 'comment_count', 'published_comment_count' => [ 'conditions' => ['Comments.is_published' => true] ] ] ]);

2) Populate existing data (production)

After deploying, rebuild counters: bin/cake counter_cache --assoc Comments Articles From that point on, counters will stay synchronized automatically.

Best practices and Common Mistakes

Here you have some best practices and common mistakes:

• Add indexes to foreign keys (comments.article_id) and fields used in conditions (comments.is_published) for large datasets.
• If you perform direct database imports (bypassing the ORM), remember to rebuild counters using bin/cake counter_cache or updateCounterCache().
• Counters defined using closures are not updated by updateCounterCache().
• If a record changes its foreign key (e.g. moving a comment from one article to another), CounterCache handles the increments and decrements safely.

This article is part of the CakeDC Advent Calendar 2025 (December 2th 2025)