nette-cloudflare-r2

nette-cloudflare-r2 is a Nette extension for storing files in Cloudflare R2: multipart uploads with progress, signed temporary links, several buckets, lifecycle rules and a Tracy panel.

nette-cloudflare-r2: upload, signed link, multipart upload and delete against a local MinIO, and a 404 as ObjectException

nette-cloudflare-r2 is a Nette extension through which an application stores files in Cloudflare R2 instead of on the server's disk. An application where users upload invoices, photos or videos keeps filling its uploads/ directory, which grows in every backup and has to be shared somehow once the site moves to two servers. R2 keeps the files off the server, speaks the same interface as Amazon S3, and Cloudflare charges no fee for outbound data transfer from it. This extension turns it into a service in the Nette container: $r2->upload(), $r2->get(), $r2->getPresignedUrl().

Why not the AWS SDK directly

The library is built on the official AWS SDK for PHP, and its S3 client can be taken out at any time (getS3Client()). The SDK, however, knows nothing about Nette: about configuration in NEON, about the FileUpload object from a form, about the Tracy panel, or about R2 having an endpoint based on the account ID and separate endpoints for the EU and FedRAMP jurisdictions. The extension builds all of that from the configuration and adds a Cloudflare REST API client for things the S3 interface lacks: custom bucket domains, the public r2.dev domain, event notifications, account metrics and temporary credentials.

What the application gets

Large files in parts

A file over 100 MB switches to multipart upload with 8 MB parts on its own. For long uploads there is ChunkedUploader, which calls a function with the number of bytes sent after each part, so progress can be shown, and it can continue an interrupted upload (resume()). In the screenshot above it sent a 20 MB file in three parts. The statistics from getStats() (operations, bytes uploaded and downloaded, errors) count these uploads too: after the test run bytesUploaded shows 20,000,037.

Temporary links instead of public files

getPresignedUrl() creates a signed download link, and getPresignedUploadUrl() a link the browser can upload to directly. Validity is at most seven days; the library shortens a longer value. An invoice can therefore stay in a private bucket while the customer gets a link valid for an hour.

Forms, several buckets and storage classes

uploadFile() takes a FileUpload from a Nette form, reads its content type and stores the file under a unique name in the chosen directory. Several buckets can be named in the configuration (for example images and backups), each with its own public URL and storage class, and R2ClientFactory creates a client for each. Rarely used data can go into the STANDARD_IA class straight at upload, or later through lifecycle rules, which can move files after a set time, delete them or clean up unfinished multipart uploads.

Fetching from a remote URL without risk to the internal network

StreamUploader::uploadFromUrl() downloads a file from a URL and stores it in R2. Before downloading, it resolves the host name to an IP and refuses any scheme other than http and https as well as addresses in private, loopback and reserved ranges, so nobody can reach services inside the network through an "upload from URL" form.

Tested against the S3 interface

Without a Cloudflare account, real R2 cannot be called. The screenshot therefore shows the R2Client connected over the S3 interface to a local MinIO: upload, metadata, a signed link downloaded without credentials, a multipart upload, a listing, a batch delete and a 404 error for the deleted file, which arrived as an ObjectException with R2 code 10007. The tests in Nette Tester (configuration, upload options, error mapping and statistics over a mocked S3 client) passed on PHP 8.1 and 8.4; the integration test against R2 is skipped without the R2_* variables.

Errors by type

R2Client converts S3 errors into exceptions by the error code and, when the response carries none, by the HTTP status. A missing object ends as ObjectException (code 10007), a missing bucket as BucketException, bad or insufficient credentials as AuthenticationException, multipart upload problems as UploadException and an exceeded limit as RateLimitException, whose getRetryAfter() reads the Retry-After header. getR2ErrorCode() returns the R2 error number, getHttpStatusCode() the HTTP status and getPrevious() the original SDK exception. An error the library does not recognise stays a generic R2Exception with code 0.

Getting started

composer require nks-hub/nette-cloudflare-r2
extensions:
    r2: NksHub\NetteCloudflareR2\DI\CloudflareR2Extension

r2:
    accountId: %env.R2_ACCOUNT_ID%
    accessKeyId: %env.R2_ACCESS_KEY_ID%
    secretAccessKey: %env.R2_SECRET_ACCESS_KEY%
    defaultBucket: faktury
    publicUrl: 'https://cdn.example.com'
    tracy: %debugMode%

It needs PHP 8.1 or newer, Nette 3 and a Cloudflare account with an R2 access key. The latest version is 1.1.2 from 6 November 2026.

Source code

The code is on GitHub in the nks-hub/nette-cloudflare-r2 repository under the MIT licence, and the package is on Packagist as nks-hub/nette-cloudflare-r2.

← Back to overview