Tsugi

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|null

cautionFileOpensInline()

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
bool

checkFileSafety()

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
string

emptyPost()

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
int

phpUploadLimitLabel()

Human-readable PHP upload cap, e.g. "8 MB".

public static phpUploadLimitLabel() : string
Return values
string

phpUploadTooLargeMessage()

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
string

replaceStoredFile()

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
bool

resolveDiskBlobPath()

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"|null

copyToContentPath()

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|null

placeContent()

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}|false

sqlNow()

SQL clock expression. SQLite is only for unit tests.

private static sqlNow() : string
Return values
string

storedTypeCanRunAsPage()

True when a stored upload type would execute or render as a page.

private static storedTypeCanRunAsPage(string $storedType) : bool
Parameters
$storedType : string
Return values
bool

unlinkUnreferencedDisk()

private static unlinkUnreferencedDisk(string $storedPath, string $sha256) : mixed
Parameters
$storedPath : string
$sha256 : string

        
On this page

Search results