BlobUtil
in package
Table of Contents
Constants
- BAD_FILE_SUFFIXES : mixed = "/(\\.|\\/)(bat|exe|cmd|sh|php|pl|cgi|386|dll|c...
Methods
- absoluteBlobPathFromStored() : string|false
- Turn blob_file.path into an absolute path using only dataroot prefix rules (no legacy last-three-segment remap). Relative paths are under $CFG->dataroot.
- blob2blob() : mixed
- Check and migrate a blob from blob_file to blob_blob
- blob2file() : mixed
- Check and migrate a blob to its corresponding file
- cautionFileKind() : string|null
- Label when a course-file open should ask for confirmation. Null for ordinary files such as PDF and images.
- cautionFileOpensInline() : bool
- HTML and SVG can be shown after confirmation. Other caution kinds download.
- checkFileSafety() : mixed
- deleteBlob() : mixed
- Delete a blob based on its id
- downloadContentType() : string
- Type to send for a course-file download.
- emptyPost() : mixed
- Check to see if the $_POST is completely broken in file upload Sometimes, if the maxUpload_SIZE is exceeded, it deletes all of $_POST
- emptyPostSessionLost() : mixed
- Check to see if the $_POST is completely broken in file upload Sometimes, if the maxUpload_SIZE is exceeded, it deletes all of $_POST and we lose our session.
- fixFileName() : mixed
- getAccessUrlForBlob() : mixed
- getBlobFolder() : mixed
- getFolderName() : mixed
- isPngOrJpeg() : mixed
- Make sure the contents of this file are a PNG or JPEG
- isTestKey() : mixed
- isTestKey - Indicate if this is a key that is supposed to stay in blob_file
- maxUpload() : mixed
- maxUploadBytes() : mixed
- migrate() : mixed
- Check and migrate a blob from an old place to the right new place
- mkdirSha256() : mixed
- phpUploadLimitBytes() : int
- Smaller of upload_max_filesize and post_max_size (bytes).
- phpUploadLimitLabel() : string
- Human-readable PHP upload cap, e.g. "8 MB".
- phpUploadTooLargeMessage() : string
- Flash-ready explanation when PHP rejected an upload for size.
- replaceStoredFile() : true|string
- Point one blob_file row at new bytes.
- requestLargerThanPhpPostLimit() : bool
- True when PHP discarded the POST because it exceeded post_max_size.
- resolveDiskBlobPath() : string|false
- Resolve blob_file.path to an absolute on-disk path if the file exists.
- return_bytes() : mixed
- safeFileSuffix() : mixed
- setBackref() : mixed
- Set the backref for a file entry
- uploadFileToBlob() : mixed
- Legacy code - returns array [id, sha256]
- uploadFileToString() : mixed
- uploadPathToBlob() : mixed
- Read a file off local disk and put it into a blob
- uploadToBlob() : mixed
- uploadToBlob - returns blob_id or false
- uploadTooLarge() : mixed
- validateUpload() : mixed
- Returns true if this is a good upload, an error string if not
- zipOrTarKind() : "ZIP"|"TAR"|null
- ZIP or TAR when this name is one of those archives. A compressed tar (tar.gz, tgz, tar.bz2) counts. A plain .gz does not.
- copyToContentPath() : string|false|null
- Copy bytes to dataroot/aa/bb/$sha256. Never overwrites a different file.
- insertBlobRow() : int|null
- placeContent() : array{blob_id: ?int, path: ?string}|false
- Store bytes under $sha256 without changing any existing blob.
- sqlNow() : string
- SQL clock expression. SQLite is only for unit tests.
- storedTypeCanRunAsPage() : bool
- True when a stored upload type would execute or render as a page.
- unlinkUnreferencedDisk() : mixed
Constants
BAD_FILE_SUFFIXES
public
mixed
BAD_FILE_SUFFIXES
= "/(\\.|\\/)(bat|exe|cmd|sh|php|pl|cgi|386|dll|com|torrent|js|app|jar|pif|vb|vbscript|wsf|asp|cer|csr|jsp|drv|sys|ade|adp|bas|chm|cpl|crt|csh|fxp|hlp|hta|inf|ins|isp|jse|htaccess|htpasswd|ksh|lnk|mdb|mde|mdt|mdw|msc|msi|msp|mst|ops|pcd|prg|reg|scr|sct|shb|shs|url|vbe|vbs|wsc|wsf|wsh|gz|gzip|rar|ar|cpio|shar|iso|bz2|lz|rz|7z|dmg|z|sit|sitx|sea|xar|zipx|py)\$/i"
Methods
absoluteBlobPathFromStored()
Turn blob_file.path into an absolute path using only dataroot prefix rules (no legacy last-three-segment remap). Relative paths are under $CFG->dataroot.
public
static absoluteBlobPathFromStored(string $stored_path) : string|false
Parameters
- $stored_path : string
-
Value from blob_file.path
Return values
string|false —Absolute path, or false if $stored_path is empty
blob2blob()
Check and migrate a blob from blob_file to blob_blob
public
static blob2blob(mixed $file_id) : mixed
Parameters
- $file_id : mixed
Return values
mixed —true if the file was migrated, false if the file was not migrated, and a string if an error was enountered
blob2file()
Check and migrate a blob to its corresponding file
public
static blob2file(mixed $file_id) : mixed
Parameters
- $file_id : mixed
Return values
mixed —true if the file was migrated, false if the file was not migrated, and a string if an error was enountered
cautionFileKind()
Label when a course-file open should ask for confirmation. Null for ordinary files such as PDF and images.
public
static cautionFileKind(mixed $filename) : string|null
HTML is included because a page served from this site can run script. Zip and tar are legal to upload and still ask on download. The upload block list is included because cartridge import can still store those other files.
Parameters
- $filename : mixed
Return values
string|nullcautionFileOpensInline()
HTML and SVG can be shown after confirmation. Other caution kinds download.
public
static cautionFileOpensInline(string|null $kind) : bool
Parameters
- $kind : string|null
Return values
boolcheckFileSafety()
public
static checkFileSafety(mixed $FILE_DESCRIPTOR[, mixed $CONTENT_TYPES = array("image/png", "image/jpeg") ]) : mixed
Parameters
- $FILE_DESCRIPTOR : mixed
- $CONTENT_TYPES : mixed = array("image/png", "image/jpeg")
deleteBlob()
Delete a blob based on its id
public
static deleteBlob(mixed $file_id[, mixed $admin_bypass = false ]) : mixed
This cleans up files from the file table and if there are no more references to the file, eliminates the blob. This can only delete blobs in the current CONTEXT - but ultimately it is up to the calling code to decide who (i.e. an instructor) is allowed to delete a file.
Parameters
- $file_id : mixed
-
The file to delete
- $admin_bypass : mixed = false
-
Run outside the context of a launch
downloadContentType()
Type to send for a course-file download.
public
static downloadContentType(mixed $filename, mixed $storedType) : string
Zip and tar are generic bytes so a browser does not unpack them on the way down. The filename stays jquery.zip.
HTML and SVG follow the filename. A browser can label an upload as JavaScript when the file starts with an HTML comment, and nosniff would then refuse to show it as a page.
The other direction is the same rule. A notes.txt whose stored type is HTML, SVG, or JavaScript is sent as plain text, so a crafted upload type cannot run as the course.
Parameters
- $filename : mixed
- $storedType : mixed
Return values
stringemptyPost()
Check to see if the $_POST is completely broken in file upload Sometimes, if the maxUpload_SIZE is exceeded, it deletes all of $_POST
public
static emptyPost() : mixed
emptyPostSessionLost()
Check to see if the $_POST is completely broken in file upload Sometimes, if the maxUpload_SIZE is exceeded, it deletes all of $_POST and we lose our session.
public
static emptyPostSessionLost() : mixed
fixFileName()
public
static fixFileName(mixed $name) : mixed
Parameters
- $name : mixed
getAccessUrlForBlob()
public
static getAccessUrlForBlob(mixed $blob_id[, mixed $serv_file = false ]) : mixed
Parameters
- $blob_id : mixed
- $serv_file : mixed = false
getBlobFolder()
public
static getBlobFolder(mixed $sha_256[, mixed $blob_root = false ]) : mixed
Parameters
- $sha_256 : mixed
- $blob_root : mixed = false
getFolderName()
public
static getFolderName() : mixed
isPngOrJpeg()
Make sure the contents of this file are a PNG or JPEG
public
static isPngOrJpeg(mixed $FILE_DESCRIPTOR) : mixed
Parameters
- $FILE_DESCRIPTOR : mixed
isTestKey()
isTestKey - Indicate if this is a key that is supposed to stay in blob_file
public
static isTestKey(mixed $key) : mixed
Parameters
- $key : mixed
maxUpload()
public
static maxUpload() : mixed
maxUploadBytes()
public
static maxUploadBytes() : mixed
migrate()
Check and migrate a blob from an old place to the right new place
public
static migrate(mixed $file_id[, mixed $test_key = false ]) : mixed
Parameters
- $file_id : mixed
- $test_key : mixed = false
Return values
mixed —true if the file was migrated, false if the file was not migrated, and a string if an error was enountered
mkdirSha256()
public
static mkdirSha256(mixed $sha_256[, mixed $blob_root = false ]) : mixed
Parameters
- $sha_256 : mixed
- $blob_root : mixed = false
phpUploadLimitBytes()
Smaller of upload_max_filesize and post_max_size (bytes).
public
static phpUploadLimitBytes() : int
Return values
intphpUploadLimitLabel()
Human-readable PHP upload cap, e.g. "8 MB".
public
static phpUploadLimitLabel() : string
Return values
stringphpUploadTooLargeMessage()
Flash-ready explanation when PHP rejected an upload for size.
public
static phpUploadTooLargeMessage([int|null $sentBytes = null ]) : string
Parameters
- $sentBytes : int|null = null
-
CONTENT_LENGTH or uploaded file size
Return values
stringreplaceStoredFile()
Point one blob_file row at new bytes.
public
static replaceStoredFile(int $file_id, string $sourcePath) : true|string
The row keeps file_id, file_name, and contenttype. The new bytes are stored under their own SHA-256. A blob_blob row or dataroot file is removed only when no blob_file row still names the previous digest.
Parameters
- $file_id : int
- $sourcePath : string
-
Readable path to the new bytes (upload tmp file)
Return values
true|string —True, or an error message
requestLargerThanPhpPostLimit()
True when PHP discarded the POST because it exceeded post_max_size.
public
static requestLargerThanPhpPostLimit() : bool
In that case $_POST and $_FILES are empty, so callers must not treat it as “no file was chosen”.
Return values
boolresolveDiskBlobPath()
Resolve blob_file.path to an absolute on-disk path if the file exists.
public
static resolveDiskBlobPath(string $stored_path[, bool $log_remap = false ]) : string|false
Same rules as Tsugi\Blob\Access when serving disk-backed blobs: relative paths are under $CFG->dataroot; if the stored absolute path is outside the current dataroot and missing, try dataroot plus the last three path segments (two-level SHA prefix directory + filename).
Parameters
- $stored_path : string
-
Non-empty path from blob_file.path
- $log_remap : bool = false
-
If true, log when the last-three fallback is used (e.g. blob serve).
Return values
string|false —Absolute path, or false if no backing file
return_bytes()
public
static return_bytes(mixed $val) : mixed
Parameters
- $val : mixed
safeFileSuffix()
public
static safeFileSuffix(mixed $filename) : mixed
Parameters
- $filename : mixed
setBackref()
Set the backref for a file entry
public
static setBackref(mixed $file_id, mixed $backref) : mixed
This is a soft foreign key in the frorm of:
table:column:value peer_submit::submit_id::2
This is uses when we want to link a blob to a record at an even finer level than context_id and link_id which is done by default.
When an application is doing a two-phase commit where it is uploading the file and then creating the record in the table that references the file (i.e. peer_submit in the above example), it can set the back ref to have a value of -1 to indicate that the file is as yet unlinked
peer_submit::submit_id::-1
and then once the peer_submit record is committed call this routine to point to the real record in the table.
Parameters
- $file_id : mixed
- $backref : mixed
uploadFileToBlob()
Legacy code - returns array [id, sha256]
public
static uploadFileToBlob(mixed $FILE_DESCRIPTOR[, mixed $SAFETY_CHECK = true ][, mixed $backref = null ]) : mixed
Returns false for any number of failures, for better detail, use validateUpload() before calling this to do the actual upload.
Parameters
- $FILE_DESCRIPTOR : mixed
- $SAFETY_CHECK : mixed = true
- $backref : mixed = null
uploadFileToString()
public
static uploadFileToString(mixed $FILE_DESCRIPTOR) : mixed
Parameters
- $FILE_DESCRIPTOR : mixed
uploadPathToBlob()
Read a file off local disk and put it into a blob
public
static uploadPathToBlob(mixed $filename, mixed $content_type[, mixed $backref = null ]) : mixed
Parameters
- $filename : mixed
- $content_type : mixed
- $backref : mixed = null
uploadToBlob()
uploadToBlob - returns blob_id or false
public
static uploadToBlob(mixed $FILE_DESCRIPTOR[, mixed $SAFETY_CHECK = true ][, mixed $backref = null ]) : mixed
Returns false for any number of failures, for better detail, use validateUpload() before calling this to do the actual upload.
Parameters
- $FILE_DESCRIPTOR : mixed
- $SAFETY_CHECK : mixed = true
- $backref : mixed = null
uploadTooLarge()
public
static uploadTooLarge(mixed $filename) : mixed
Parameters
- $filename : mixed
validateUpload()
Returns true if this is a good upload, an error string if not
public
static validateUpload(mixed $FILE_DESCRIPTOR[, mixed $SAFETY_CHECK = true ]) : mixed
Parameters
- $FILE_DESCRIPTOR : mixed
- $SAFETY_CHECK : mixed = true
zipOrTarKind()
ZIP or TAR when this name is one of those archives. A compressed tar (tar.gz, tgz, tar.bz2) counts. A plain .gz does not.
public
static zipOrTarKind(mixed $filename) : "ZIP"|"TAR"|null
Parameters
- $filename : mixed
Return values
"ZIP"|"TAR"|nullcopyToContentPath()
Copy bytes to dataroot/aa/bb/$sha256. Never overwrites a different file.
private
static copyToContentPath(string $sourcePath, string $sha256) : string|false|null
Parameters
- $sourcePath : string
- $sha256 : string
Return values
string|false|null —Absolute path, null when disk storage is unavailable, false on conflict
insertBlobRow()
private
static insertBlobRow(string $sourcePath, string $sha256) : int|null
Parameters
- $sourcePath : string
- $sha256 : string
Return values
int|nullplaceContent()
Store bytes under $sha256 without changing any existing blob.
private
static placeContent(string $sourcePath, string $sha256) : array{blob_id: ?int, path: ?string}|false
Caller holds the transaction. Returns blob_id or path, the other null.
Parameters
- $sourcePath : string
- $sha256 : string
Return values
array{blob_id: ?int, path: ?string}|falsesqlNow()
SQL clock expression. SQLite is only for unit tests.
private
static sqlNow() : string
Return values
stringstoredTypeCanRunAsPage()
True when a stored upload type would execute or render as a page.
private
static storedTypeCanRunAsPage(string $storedType) : bool
Parameters
- $storedType : string
Return values
boolunlinkUnreferencedDisk()
private
static unlinkUnreferencedDisk(string $storedPath, string $sha256) : mixed
Parameters
- $storedPath : string
- $sha256 : string