FilePlace

The places an application keeps files, each a folder of its own.

A place names a kind of file, never a path. Where the places live is said once, in CkSettings::FilePlatform: on Joomla!, Laravel or WordPress each place is the folder that platform keeps for such files, found through the platform's own constant or function; with no platform named, your application says one root and each place is the subfolder named after it, Images, Audio, Documents, made when first written to (Your file places, set once; step by step on Setting up your file places). Every file operation on CkFile takes a place and a relative path, never a full one. With no platform and no root said, a place refuses every operation, so as shipped nothing can touch a disk. Each place also says what it takes: the extensions and the most bytes a file may have, with the library's own defaults when you set none.

There is no Root on purpose: a file is always inside a named folder, never beside the application or the site, so a path that climbs — ../configuration.php — is never in bounds.

Members

Member	Meaning	Takes by default
Uploads	Files as they arrive, before they are checked and filed.	every extension below
Temporary	Scratch files, safe to clear at any time.	every extension below
Images	Pictures.	jpg, jpeg, png, gif, webp, bmp, tif, tiff, heic, avif
Videos	Video files.	mp4, mov, webm, mkv, avi
Audio	Audio files.	mp3, wav, ogg, m4a, flac
Media	Pictures, video and audio kept together, where an application has one media folder rather than three.	the three lists above
Documents	Documents: PDFs, office files, scans.	pdf, doc, docx, xls, xlsx, ppt, pptx, odt, ods, odp, rtf, txt, csv
Imports	Data received to be read in: spreadsheets, CSV, JSON and XML feeds.	csv, xlsx, xls, json, xml, txt
Exports	Files the application makes for people to download: reports, invoices, extracts.	pdf, csv, xlsx, docx, json, zip
Archives	Archives: zip and its kin.	zip, 7z, rar, gz, tar

Every place takes 2 MB (CkSettings::DefaultMaxFileBytes) until you say otherwise, and none takes a blocked extension — a program, a script, a web page — however it is listed.

The enum is backed by an int — Uploads is 0, Temporary 1, Images 2, Videos 3, Audio 4, Media 5, Documents 6, Imports 7, Exports 8, Archives 9 — so a choice can be stored and read back with FilePlace::from().

Where it is used

Every file operation on CkFile — Write, Read, ReadOrNull, Copy, Move, Delete, Exists, Size, SizeOrNull, Files, FullPath, IsAllowed, AllowedExtensions and MaxBytes — takes a place as its first parameter, Uploads unless said, and the three settings methods CkSettings::FileRoot, FileExtensions and FileMaxBytes answer for one.

Quick look

// no-check
use SafeCoder\CommonKit\CkFile;
use SafeCoder\CommonKit\Enums\FilePlace;

CkFile::Write(FilePlace::Documents, 'claim-18/scan.pdf', $bytes);   // true: a PDF, within the limit
CkFile::Write(FilePlace::Videos, 'clip.mp4', $bytes);               // false while no folder is set for Videos

use SafeCoder\CommonKit\CkFile;
use SafeCoder\CommonKit\Enums\FilePlace;

CkFile::AllowedExtensions(FilePlace::Images);   // -> ['jpg', 'jpeg', 'png', 'gif', 'webp', 'bmp', 'tif', 'tiff', 'heic', 'avif']
CkFile::MaxBytes(FilePlace::Images);            // -> 2097152   (as shipped)