From 099fe0249816f30cffbc8cb51e499337306c4708 Mon Sep 17 00:00:00 2001 From: Tom Jaeger Date: Thu, 5 Jun 2025 15:33:59 -0400 Subject: [PATCH 1/5] added new docs for working with mimes --- docs/development/services/mime.md | 208 ++++++++++++++++++++++++++++++ 1 file changed, 208 insertions(+) create mode 100644 docs/development/services/mime.md diff --git a/docs/development/services/mime.md b/docs/development/services/mime.md new file mode 100644 index 000000000..f0adad73a --- /dev/null +++ b/docs/development/services/mime.md @@ -0,0 +1,208 @@ +lang: php + + + +# MimeType Service + +[TOC] + +The `MimeType` service in ExpressionEngine provides a robust way to detect and validate MIME types of files and data buffers. This service is essential for ensuring that uploaded files are of the expected type and safe for processing. It includes functionality to manage a whitelist of allowed MIME types, detect MIME types from files or buffers, and perform specific checks like determining if a file is an image. + +## Overview + +The `MimeType` class allows developers to: +- Detect MIME types of files and data buffers. +- Validate MIME types against a configurable whitelist. +- Check if a file is an image or safe for upload. +- Extend the whitelist with custom MIME types. + +This service is particularly useful for handling file uploads securely and ensuring compliance with content policies by restricting file types. + +## Usage Examples + +Here are some common use cases for the `MimeType` service: + +### Detecting MIME Type of a File + +To determine the MIME type of a file at a given path: + + $mime = ee('MimeType')->ofFile($path); + echo $mime; // Outputs something like 'image/jpeg' or 'application/pdf' + +### Detecting MIME Type of a Data Buffer + +To determine the MIME type of raw data: + + $data = file_get_contents($path); + $mime = ee('MimeType')->ofBuffer($data); + echo $mime; // Outputs the MIME type based on the buffer content + +### Guessing MIME Type for Octet Stream + +When a file is detected as a generic `application/octet-stream`, you can attempt to guess a more specific type: + + $opening = file_get_contents($path, false, null, 0, 50); + $mime = ee('MimeType')->guessOctetStream($opening); + echo $mime; // Might output 'image/webp' or 'application/pdf' if identifiable + +### Checking if a MIME Type Matches a Specific Kind + +To check if a MIME type belongs to a specific category or kind: + + $filePath = '/path/to/file'; + $allowed_type = 'image'; + if (ee('MimeType')->isOfKind(ee('MimeType')->ofFile($filePath), $allowed_type)) { + echo 'This file is of the allowed type.'; + } + +### Validating if a File is Safe for Upload + +To ensure a file's MIME type is in the whitelist and safe for upload: + + $path = '/path/to/uploaded/file'; + if (ee('MimeType')->fileIsSafeForUpload($path)) { + echo 'This file is safe to upload.'; + } else { + echo 'This file type is not allowed.'; + } + +### Checking if a MIME Type is Safe for Upload + +To check a specific MIME type against the whitelist: + + $mime = 'image/png'; + $safeForUpload = ee('MimeType')->isSafeForUpload($mime) ? $mime : false; + if ($safeForUpload) { + echo 'This MIME type is safe for upload.'; + } + +### Checking if a File is an Image + +To determine if a file is an image based on its MIME type and content: + + $path = '/path/to/file'; + if (ee('MimeType')->fileIsImage($path)) { + echo 'This file is an image.'; + } + +## MimeType Methods + +**class `ExpressionEngine\Library\Mime\MimeType`** + +[TOC=3] + +### `addMimeType($mime, $kind = null)` + +Adds a single MIME type to the whitelist. + +| Parameter | Type | Description | +| --------- | -------- | ------------------------------------- | +| \$mime | `String` | The MIME type to add | +| \$kind | `String` | Optional category or kind of MIME type| +| Returns | `Void` | | + +### `addMimeTypes(array $mimes, $kind = null)` + +Adds multiple MIME types to the whitelist. + +| Parameter | Type | Description | +| --------- | -------- | ------------------------------------- | +| \$mimes | `Array` | An array of MIME types to add | +| \$kind | `String` | Optional category or kind of MIME type| +| Returns | `Void` | | + +### `getWhitelist()` + +Returns the current whitelist of MIME types. + +| Parameter | Type | Description | +| --------- | ------- | ------------------------------------- | +| Returns | `Array` | An array of whitelisted MIME types | + +### `isOfKind($mime, $mimeTypeKind)` + +Checks if a MIME type belongs to a specific kind or category. + +| Parameter | Type | Description | +| --------------- | -------- | ------------------------------------- | +| \$mime | `String` | The MIME type to check | +| \$mimeTypeKind | `String` | The kind or category to check against | +| Returns | `Boolean`| TRUE if it matches the kind, FALSE otherwise | + +### `ofFile($path)` + +Determines the MIME type of a file. + +| Parameter | Type | Description | +| --------- | -------- | ------------------------------------- | +| \$path | `String` | The full path to the file | +| Returns | `String` | The MIME type of the file | + +### `ofBuffer($buffer)` + +Determines the MIME type of a data buffer. + +| Parameter | Type | Description | +| --------- | -------- | ------------------------------------- | +| \$buffer | `String` | The data buffer to check | +| Returns | `String` | The MIME type of the buffer | + +### `guessOctetStream($contents)` + +Attempts to guess a more specific MIME type for data identified as `application/octet-stream`. + +| Parameter | Type | Description | +| ----------- | -------- | ------------------------------------- | +| \$contents | `String` | The content to analyze | +| Returns | `String` | The guessed MIME type | + +### `fileIsImage($path)` + +Determines if a file is an image. + +| Parameter | Type | Description | +| --------- | -------- | ------------------------------------- | +| \$path | `String` | The full path to the file | +| Returns | `Boolean`| TRUE if it is an image, FALSE otherwise | + +### `isImage($mime)` + +Checks if a MIME type is recognized as an image type. + +| Parameter | Type | Description | +| --------- | -------- | ------------------------------------- | +| \$mime | `String` | The MIME type to check | +| Returns | `Boolean`| TRUE if it is an image type, FALSE otherwise | + +### `fileIsSafeForUpload($path)` + +Checks if a file's MIME type is safe for upload based on the whitelist. + +| Parameter | Type | Description | +| --------- | -------- | ------------------------------------- | +| \$path | `String` | The full path to the file | +| Returns | `Boolean`| TRUE if safe for upload, FALSE otherwise | + +### `isSafeForUpload($mime)` + +Checks if a specific MIME type is safe for upload based on the whitelist. + +| Parameter | Type | Description | +| --------- | -------- | ------------------------------------- | +| \$mime | `String` | The MIME type to check | +| Returns | `Boolean`| TRUE if safe for upload, FALSE otherwise | + +### `whitelistMimesFromConfig()` + +Loads MIME types from configuration files into the whitelist, including any additional MIME types specified in the configuration. + +| Parameter | Type | Description | +| --------- | ------- | ------------------------------------- | +| Returns | `Void` | | From 4b1653cf0ea8523486dd4c8e98c3fbf0d40760d6 Mon Sep 17 00:00:00 2001 From: Tom Jaeger Date: Thu, 5 Jun 2025 15:44:06 -0400 Subject: [PATCH 2/5] added nav link to mimes --- docs/toc_sections/_advanced_usage_toc.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/toc_sections/_advanced_usage_toc.yml b/docs/toc_sections/_advanced_usage_toc.yml index a4bae53f1..312ae2b11 100644 --- a/docs/toc_sections/_advanced_usage_toc.yml +++ b/docs/toc_sections/_advanced_usage_toc.yml @@ -338,6 +338,8 @@ href: development/services/encrypt.md - name: Event Service href: development/services/event.md + - name: MimeType Service + href: development/services/mime.md - name: CP/FilePicker Service href: development/services/filepicker.md - name: CP/Filter Service @@ -608,6 +610,7 @@ - name: XML Helper href: development/legacy/helpers/xml-helper.md + - name: Legacy API Library href: development/legacy/api/index.md items: From a350b6a769080f6ac8d9785ce9ac56f330e286b8 Mon Sep 17 00:00:00 2001 From: Tom Jaeger Date: Thu, 5 Jun 2025 15:45:54 -0400 Subject: [PATCH 3/5] removed blank line --- docs/toc_sections/_advanced_usage_toc.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/toc_sections/_advanced_usage_toc.yml b/docs/toc_sections/_advanced_usage_toc.yml index 312ae2b11..b20f45120 100644 --- a/docs/toc_sections/_advanced_usage_toc.yml +++ b/docs/toc_sections/_advanced_usage_toc.yml @@ -610,7 +610,6 @@ - name: XML Helper href: development/legacy/helpers/xml-helper.md - - name: Legacy API Library href: development/legacy/api/index.md items: From 0a4a93695a63308ded994482936312943da77a7e Mon Sep 17 00:00:00 2001 From: Tom Jaeger Date: Thu, 5 Jun 2025 15:48:11 -0400 Subject: [PATCH 4/5] small changes --- docs/development/services/mime.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/development/services/mime.md b/docs/development/services/mime.md index f0adad73a..3a9924839 100644 --- a/docs/development/services/mime.md +++ b/docs/development/services/mime.md @@ -1,5 +1,6 @@ +--- lang: php - +---