Files

Jakub Zych e06e0cc8bf feat(12-01): record multipart uploads and match Winter upload URLs

- attach.PublicURL and (*File).URL build Winter File::getPath() URLs; the
  thumbnailer decodes webp via golang.org/x/image v0.46.0 and checks the
  image size from the header before decoding
- tide requests carry multipart parts (files beside the fixture pinned by
  sha256) encoded with the fixed MultipartBoundary, so PHP and Go receive
  byte-identical bodies
- tide masks the random partition, disk name and file id of url/thumb_url
  upload URLs while still diffing prefix, size, mode and extension, and
  NormalizePublications masks Carbon dates in the published album

2026-10-02 11:33:42 +02:00

3.2 KiB

Raw Blame History

title, description, section, order

title	description	section	order
Storage	Configure the uploads bucket that serve opens, choose file or memory bucket URLs, serve stored files, and size upload routes.	services	90

Storage

WinterCMS stores uploads on a Laravel filesystem disk. SummerCMS stores them in one gocloud.dev bucket, opened from storage.uploads.bucket_url by the attach package of lagoon. The serve command opens the bucket at start-up, before it accepts requests, and publishes it on the application; an empty bucket_url stops the start-up.

Bucket URLs

URL	Stores
`file:///var/lib/acme/uploads`	In a directory on the server.
`mem://`	In memory, for tests. Everything is lost when the process exits.

The keys go in config/storage.yaml:

uploads:
  bucket_url: file:///var/lib/acme/uploads
  public_path_prefix: /storage/uploads

Files are laid out as WinterCMS lays out its uploads disk, so a copy of a WinterCMS storage/app/uploads/public directory can serve as the bucket after a port. public_path_prefix is the URL prefix that file and thumbnail URLs start with. attach.PublicURL builds the URL of any blob key from it, and attach.File.URL the URL of an original.

The WinterCMS layout

A port whose clients already store or compare upload URLs keeps WinterCMS's URLs too. WinterCMS serves public uploads from storage/app/uploads/public under the URL path /storage/app/uploads/public (cms.storage.uploads.path plus /public). Root the bucket at that directory and use the same prefix:

uploads:
  bucket_url: file://./storage/app/uploads/public
  public_path_prefix: /storage/app/uploads/public

An original then has the URL /storage/app/uploads/public/<partition>/<disk_name>, as WinterCMS's File::getPath() returns, and a 200 by 200 cropped thumbnail /storage/app/uploads/public/<partition>/thumb_<id>_200_200_0_0_crop.<ext>, as getThumb() returns. The framework default stays /storage/uploads, so only an application that sets these keys changes its URLs.

Application code gets the bucket with app.Lookup[*blob.Bucket]() and reads and writes it through the gocloud.dev/blob API. Model attachments, thumbnails and deleting files after commit are covered in Attachments.

Serving files

The framework does not mount a file route by itself. The application decides where files are served: mount attach.StaticHandlerPublic under public_path_prefix to serve originals and thumbnails and answer 404 for files whose row is not public, or put a web server or CDN in front of the bucket directory. Serve uploads from a separate origin when you can; the Attachments page explains why.

Upload size

Every non-raw route has a request body limit of http.body_limits.default_bytes. A route that accepts uploads raises its own limit with the body.limit:<bytes> middleware; see Routing. http.body_limits.upload_bytes is required and validated at start-up, but the framework applies it to no route; a plugin that wants its upload routes to follow it reads it in Register and puts the value in the route's body.limit.

3.2 KiB Raw Blame History