FileRepository
in package
Course Files tool rows, folders, and hrefs. Does not emit HTTP.
Generic blob I/O stays on BlobUtil / Access. This is course Files rules (folders, Public/Student/Private, backref=files) on top of blob_file.
Table of Contents
Constants
- BACKREF : mixed = 'files'
- FOLDER_CONTENTTYPE : mixed = 'inode/directory'
- HREF_PREFIX : mixed = '/files'
- Stored URL prefix; must match Controllers\Files::ROUTE.
- KIND_FILE : mixed = 'file'
- KIND_FOLDER : mixed = 'folder'
- PRIVATE_FOLDER : mixed = 'Private'
- PUBLIC_FOLDER : mixed = 'Public'
- STUDENT_FILES_FOLDER : mixed = 'Student'
- ZIP_CONTAINER_MIMES : mixed = array('application/vnd.openxmlformats-officedoc...
- Office Open XML and ODF packages are ZIP files on disk. finfo reports application/zip for them. A replacement with the same extension may keep that stored type.
Methods
- allItems() : array<int, array<string, mixed>>
- countFilesUnder() : int
- Files in this folder and every folder under it. Folder rows are not counted.
- createFolder() : mixed
- Create a folder row in this course's Files tool.
- decodeMeta() : array{kind: string, folder: string}
- deleteFolderRow() : mixed
- downloadHrefForSha256() : string|null
- Path form of a content-addressed download URL (/files/download/{sha256}).
- ensureFolderPath() : mixed
- Create each folder segment so $folder exists (e.g. code3/week1).
- ensureLink() : int|false
- Ensure the synthetic Files lti_link for this course. No session wiring.
- ensureReservedFolders() : mixed
- ensureTopFolder() : mixed
- existingLinkId() : int
- Files link for this course, or 0 when the course has no Files link yet.
- firstFolderSegment() : mixed
- folderHasChildren() : mixed
- forceFileAnchorsNewTab() : string
- Uploaded-file anchors open in a new tab. Other links are left alone.
- getFileRowByPath() : array<string, mixed>|null
- File row for a folder/name path in this course.
- getFileRowsBySha256() : array<int, array<string, mixed>>
- getItem() : array<string, mixed>|false
- getPublicFileByPath() : array<string, mixed>|null
- A Public file at this folder path, in any course. No login required.
- getPublicFileBySha256() : array<string, mixed>|null
- A Public file with this content hash, in any course. No login required.
- hrefForPath() : string|null
- Path form of a course file URL (/files/{folder}/{name}).
- importBytes() : array{file_id: int, sha256: string, filename: string, href: string}
- Store cartridge file bytes in this course's Files tool.
- isImageFile() : mixed
- True for image/* content, or a common image extension when the type is missing.
- isPrivatePath() : mixed
- isPublicPath() : mixed
- isReservedName() : mixed
- isReservedRootFolder() : mixed
- isSha256() : bool
- True when $sha is a 64-character hex SHA-256 identifier.
- isStudentFilesPath() : mixed
- isUploadedFileHref() : bool
- True when $href points at an uploaded course file.
- isValidName() : mixed
- joinFolder() : mixed
- lessonsFilePickerItem() : array<string, mixed>
- Lessons author picker fields from a blob_file row.
- listFolder() : array<int, array<string, mixed>>
- listForHome() : array<int, array{path: string, name: string, image: bool}>
- Non-private files an instructor can place on the course home.
- nameExists() : mixed
- normalizeFilePath() : string|null
- normalizeFolder() : string|false
- parentFolder() : string|null
- pathForSha256() : string|null
- Folder/name for a sha256 in this context, or null.
- pathFromFileRow() : string|null
- readExportPayload() : array{bytes: string, filename: string, content_type: string, path?: string}|null
- File bytes for Common Cartridge export, or null if the blob cannot be read.
- replaceFile() : true|string
- Replace the bytes of one course file. file_id, folder, and file_name stay.
- replacementEndingLabel() : string
- How the replace page should describe the required ending.
- replacementTypeError() : string|null
- Null when the upload may replace the stored file. Otherwise an error message naming both types.
- rewriteDownloadHrefsToPaths() : string
- Replace files/download/{sha} in stored HTML with files/{path}.
- sha256FromDownloadHref() : string|null
- Extract a SHA-256 from a Tsugi Files download href, or null.
- tagFileRow() : mixed
- canonicalMime() : string
- exportRowForSha256() : array<string, mixed>|null
- fileSuffix() : string
- readBlobBytesBySha256() : string|null
- sniffMime() : string
- suffixKey() : string
- suffixMismatchMessage() : string|null
- Null when the upload ending may replace the stored name.
- zipContainerReplacement() : bool
Constants
BACKREF
public
mixed
BACKREF
= 'files'
FOLDER_CONTENTTYPE
public
mixed
FOLDER_CONTENTTYPE
= 'inode/directory'
HREF_PREFIX
Stored URL prefix; must match Controllers\Files::ROUTE.
public
mixed
HREF_PREFIX
= '/files'
KIND_FILE
public
mixed
KIND_FILE
= 'file'
KIND_FOLDER
public
mixed
KIND_FOLDER
= 'folder'
PRIVATE_FOLDER
public
mixed
PRIVATE_FOLDER
= 'Private'
PUBLIC_FOLDER
public
mixed
PUBLIC_FOLDER
= 'Public'
STUDENT_FILES_FOLDER
public
mixed
STUDENT_FILES_FOLDER
= 'Student'
ZIP_CONTAINER_MIMES
Office Open XML and ODF packages are ZIP files on disk. finfo reports application/zip for them. A replacement with the same extension may keep that stored type.
private
mixed
ZIP_CONTAINER_MIMES
= array('application/vnd.openxmlformats-officedocument.presentationml.presentation', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'application/vnd.oasis.opendocument.presentation', 'application/vnd.oasis.opendocument.text', 'application/vnd.oasis.opendocument.spreadsheet')
Methods
allItems()
public
static allItems(mixed $link_id, mixed $context_id) : array<int, array<string, mixed>>
Parameters
- $link_id : mixed
- $context_id : mixed
Return values
array<int, array<string, mixed>>countFilesUnder()
Files in this folder and every folder under it. Folder rows are not counted.
public
static countFilesUnder(array<int, array<string, mixed>> $rows, string $folder) : int
An empty $folder counts every file in $rows (the course root).
Parameters
- $rows : array<int, array<string, mixed>>
-
blob_file rows
- $folder : string
Return values
intcreateFolder()
Create a folder row in this course's Files tool.
public
static createFolder(mixed $link_id, mixed $folder, mixed $name, mixed $context_id) : mixed
Parameters
- $link_id : mixed
- $folder : mixed
- $name : mixed
- $context_id : mixed
decodeMeta()
public
static decodeMeta(array<string, mixed> $row) : array{kind: string, folder: string}
Parameters
- $row : array<string, mixed>
Return values
array{kind: string, folder: string}deleteFolderRow()
public
static deleteFolderRow(mixed $file_id, mixed $context_id) : mixed
Parameters
- $file_id : mixed
- $context_id : mixed
downloadHrefForSha256()
Path form of a content-addressed download URL (/files/download/{sha256}).
public
static downloadHrefForSha256(mixed $sha256) : string|null
Parameters
- $sha256 : mixed
Return values
string|nullensureFolderPath()
Create each folder segment so $folder exists (e.g. code3/week1).
public
static ensureFolderPath(mixed $link_id, mixed $folder, mixed $context_id) : mixed
Parameters
- $link_id : mixed
- $folder : mixed
- $context_id : mixed
ensureLink()
Ensure the synthetic Files lti_link for this course. No session wiring.
public
static ensureLink(int $context_id) : int|false
Same row as Tool::lmsEnsureAnalyticsLink (lms:/files). Implemented here so Files pages and cartridge import work without the lms-util.php globals.
Parameters
- $context_id : int
Return values
int|falseensureReservedFolders()
public
static ensureReservedFolders(mixed $link_id, mixed $context_id) : mixed
Parameters
- $link_id : mixed
- $context_id : mixed
ensureTopFolder()
public
static ensureTopFolder(mixed $link_id, mixed $name, mixed $context_id) : mixed
Parameters
- $link_id : mixed
- $name : mixed
- $context_id : mixed
existingLinkId()
Files link for this course, or 0 when the course has no Files link yet.
public
static existingLinkId(mixed $context_id) : int
Does not create a link.
Parameters
- $context_id : mixed
Return values
intfirstFolderSegment()
public
static firstFolderSegment(mixed $folder) : mixed
Parameters
- $folder : mixed
folderHasChildren()
public
static folderHasChildren(mixed $link_id, mixed $folder, mixed $context_id) : mixed
Parameters
- $link_id : mixed
- $folder : mixed
- $context_id : mixed
forceFileAnchorsNewTab()
Uploaded-file anchors open in a new tab. Other links are left alone.
public
static forceFileAnchorsNewTab(mixed $html) : string
Parameters
- $html : mixed
Return values
stringgetFileRowByPath()
File row for a folder/name path in this course.
public
static getFileRowByPath(string $path, mixed $link_id, mixed $context_id) : array<string, mixed>|null
Parameters
- $path : string
- $link_id : mixed
- $context_id : mixed
Return values
array<string, mixed>|nullgetFileRowsBySha256()
public
static getFileRowsBySha256(mixed $sha256, mixed $context_id) : array<int, array<string, mixed>>
Parameters
- $sha256 : mixed
- $context_id : mixed
Return values
array<int, array<string, mixed>>getItem()
public
static getItem(mixed $file_id, mixed $context_id) : array<string, mixed>|false
Parameters
- $file_id : mixed
- $context_id : mixed
Return values
array<string, mixed>|falsegetPublicFileByPath()
A Public file at this folder path, in any course. No login required.
public
static getPublicFileByPath(string $path) : array<string, mixed>|null
Parameters
- $path : string
Return values
array<string, mixed>|nullgetPublicFileBySha256()
A Public file with this content hash, in any course. No login required.
public
static getPublicFileBySha256(mixed $sha256) : array<string, mixed>|null
Parameters
- $sha256 : mixed
Return values
array<string, mixed>|nullhrefForPath()
Path form of a course file URL (/files/{folder}/{name}).
public
static hrefForPath(mixed $path) : string|null
Parameters
- $path : mixed
Return values
string|nullimportBytes()
Store cartridge file bytes in this course's Files tool.
public
static importBytes(mixed $bytes, mixed $filename[, mixed $folder = '' ][, mixed $contentType = 'application/octet-stream' ]) : array{file_id: int, sha256: string, filename: string, href: string}
Empty $folder is the course root (obscure). Nested cartridge paths are created as folders from the Files root (no extra Imported wrapper). Public, Student, and Private stay those reserved folders when the cartridge path starts with them.
Parameters
- $bytes : mixed
- $filename : mixed
- $folder : mixed = ''
- $contentType : mixed = 'application/octet-stream'
Return values
array{file_id: int, sha256: string, filename: string, href: string}isImageFile()
True for image/* content, or a common image extension when the type is missing.
public
static isImageFile(mixed $name, mixed $contentType) : mixed
Parameters
- $name : mixed
- $contentType : mixed
isPrivatePath()
public
static isPrivatePath(mixed $folder) : mixed
Parameters
- $folder : mixed
isPublicPath()
public
static isPublicPath(mixed $folder) : mixed
Parameters
- $folder : mixed
isReservedName()
public
static isReservedName(mixed $name) : mixed
Parameters
- $name : mixed
isReservedRootFolder()
public
static isReservedRootFolder(mixed $path) : mixed
Parameters
- $path : mixed
isSha256()
True when $sha is a 64-character hex SHA-256 identifier.
public
static isSha256(mixed $sha) : bool
Parameters
- $sha : mixed
Return values
boolisStudentFilesPath()
public
static isStudentFilesPath(mixed $folder) : mixed
Parameters
- $folder : mixed
isUploadedFileHref()
True when $href points at an uploaded course file.
public
static isUploadedFileHref(mixed $href) : bool
The Files tool itself (analytics, replace, the folder list) is not a file.
Parameters
- $href : mixed
Return values
boolisValidName()
public
static isValidName(mixed $name) : mixed
Parameters
- $name : mixed
joinFolder()
public
static joinFolder(mixed $parent, mixed $name) : mixed
Parameters
- $parent : mixed
- $name : mixed
lessonsFilePickerItem()
Lessons author picker fields from a blob_file row.
public
static lessonsFilePickerItem(array<string, mixed> $row[, string $folder = '' ]) : array<string, mixed>
href is the stored /files/{folder}/{name} form.
Parameters
- $row : array<string, mixed>
- $folder : string = ''
Return values
array<string, mixed>listFolder()
public
static listFolder(mixed $link_id, mixed $folder, mixed $context_id) : array<int, array<string, mixed>>
Parameters
- $link_id : mixed
- $folder : mixed
- $context_id : mixed
Return values
array<int, array<string, mixed>>listForHome()
Non-private files an instructor can place on the course home.
public
static listForHome(mixed $context_id) : array<int, array{path: string, name: string, image: bool}>
Folders and the Private tree are omitted. Every row is a file a student can open by its course path.
Parameters
- $context_id : mixed
Return values
array<int, array{path: string, name: string, image: bool}>nameExists()
public
static nameExists(mixed $link_id, mixed $folder, mixed $name, mixed $context_id) : mixed
Parameters
- $link_id : mixed
- $folder : mixed
- $name : mixed
- $context_id : mixed
normalizeFilePath()
public
static normalizeFilePath(mixed $path) : string|null
Parameters
- $path : mixed
Return values
string|nullnormalizeFolder()
public
static normalizeFolder(mixed $raw) : string|false
Parameters
- $raw : mixed
Return values
string|falseparentFolder()
public
static parentFolder(mixed $folder) : string|null
Parameters
- $folder : mixed
Return values
string|nullpathForSha256()
Folder/name for a sha256 in this context, or null.
public
static pathForSha256(mixed $sha256, int $context_id) : string|null
Parameters
- $sha256 : mixed
- $context_id : int
Return values
string|nullpathFromFileRow()
public
static pathFromFileRow(array<string, mixed> $row) : string|null
Parameters
- $row : array<string, mixed>
Return values
string|nullreadExportPayload()
File bytes for Common Cartridge export, or null if the blob cannot be read.
public
static readExportPayload(mixed $sha256, int $context_id) : array{bytes: string, filename: string, content_type: string, path?: string}|null
Parameters
- $sha256 : mixed
- $context_id : int
Return values
array{bytes: string, filename: string, content_type: string, path?: string}|nullreplaceFile()
Replace the bytes of one course file. file_id, folder, and file_name stay.
public
static replaceFile(int $file_id, int $context_id, array<string, mixed> $file) : true|string
The new file's type must match the stored type.
Parameters
- $file_id : int
- $context_id : int
- $file : array<string, mixed>
-
PHP upload descriptor
Return values
true|stringreplacementEndingLabel()
How the replace page should describe the required ending.
public
static replacementEndingLabel(string $name) : string
Parameters
- $name : string
Return values
stringreplacementTypeError()
Null when the upload may replace the stored file. Otherwise an error message naming both types.
public
static replacementTypeError(string $storedType, string $storedName, string $uploadPath, string $clientType, string $uploadName) : string|null
Parameters
- $storedType : string
- $storedName : string
- $uploadPath : string
- $clientType : string
-
Browser-supplied MIME
- $uploadName : string
Return values
string|nullrewriteDownloadHrefsToPaths()
Replace files/download/{sha} in stored HTML with files/{path}.
public
static rewriteDownloadHrefsToPaths(mixed $html, int $context_id) : string
Parameters
- $html : mixed
- $context_id : int
Return values
stringsha256FromDownloadHref()
Extract a SHA-256 from a Tsugi Files download href, or null.
public
static sha256FromDownloadHref(mixed $href) : string|null
Parameters
- $href : mixed
Return values
string|null —Lowercase hex digest
tagFileRow()
public
static tagFileRow(mixed $file_id, mixed $folder, mixed $bytelen, mixed $context_id) : mixed
Parameters
- $file_id : mixed
- $folder : mixed
- $bytelen : mixed
- $context_id : mixed
canonicalMime()
private
static canonicalMime(mixed $type) : string
Parameters
- $type : mixed
Return values
stringexportRowForSha256()
private
static exportRowForSha256(mixed $sha256, int $context_id) : array<string, mixed>|null
Parameters
- $sha256 : mixed
- $context_id : int
Return values
array<string, mixed>|nullfileSuffix()
private
static fileSuffix(string $name) : string
Parameters
- $name : string
Return values
stringreadBlobBytesBySha256()
private
static readBlobBytesBySha256(string $sha, string $storedPath) : string|null
Parameters
- $sha : string
- $storedPath : string
Return values
string|nullsniffMime()
private
static sniffMime(string $path) : string
Parameters
- $path : string
Return values
stringsuffixKey()
private
static suffixKey(string $name) : string
Parameters
- $name : string
Return values
stringsuffixMismatchMessage()
Null when the upload ending may replace the stored name.
private
static suffixMismatchMessage(string $storedName, string $uploadName) : string|null
jpg/jpeg and htm/html are the same ending. Comparison ignores case.
Parameters
- $storedName : string
- $uploadName : string
Return values
string|nullzipContainerReplacement()
private
static zipContainerReplacement(string $stored, string $sniffed, string $client, string $storedName, string $uploadName) : bool
Parameters
- $stored : string
- $sniffed : string
- $client : string
- $storedName : string
- $uploadName : string