Skip to content

Commit 920324b

Browse files
TomJaegerTomJaeger
authored
Merge pull request #1001 from ExpressionEngine/add-mimes-service-docs
added new docs for working with mimes service / library
2 parents 22ddc34 + 099fe02 commit 920324b

File tree

1 file changed

+208
-0
lines changed

1 file changed

+208
-0
lines changed

‎docs/development/services/mime.md

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
lang: php
2+
3+
<!--
4+
This source file is part of the open source project
5+
ExpressionEngine User Guide (https://github.com/ExpressionEngine/ExpressionEngine-User-Guide)
6+
7+
@link https://expressionengine.com/
8+
@copyright Copyright (c) 2003-2025, Packet Tide, LLC (https://packettide.com)
9+
@license https://expressionengine.com/license Licensed under Apache License, Version 2.0
10+
-->
11+
12+
# MimeType Service
13+
14+
[TOC]
15+
16+
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.
17+
18+
## Overview
19+
20+
The `MimeType` class allows developers to:
21+
- Detect MIME types of files and data buffers.
22+
- Validate MIME types against a configurable whitelist.
23+
- Check if a file is an image or safe for upload.
24+
- Extend the whitelist with custom MIME types.
25+
26+
This service is particularly useful for handling file uploads securely and ensuring compliance with content policies by restricting file types.
27+
28+
## Usage Examples
29+
30+
Here are some common use cases for the `MimeType` service:
31+
32+
### Detecting MIME Type of a File
33+
34+
To determine the MIME type of a file at a given path:
35+
36+
$mime = ee('MimeType')->ofFile($path);
37+
echo $mime; // Outputs something like 'image/jpeg' or 'application/pdf'
38+
39+
### Detecting MIME Type of a Data Buffer
40+
41+
To determine the MIME type of raw data:
42+
43+
$data = file_get_contents($path);
44+
$mime = ee('MimeType')->ofBuffer($data);
45+
echo $mime; // Outputs the MIME type based on the buffer content
46+
47+
### Guessing MIME Type for Octet Stream
48+
49+
When a file is detected as a generic `application/octet-stream`, you can attempt to guess a more specific type:
50+
51+
$opening = file_get_contents($path, false, null, 0, 50);
52+
$mime = ee('MimeType')->guessOctetStream($opening);
53+
echo $mime; // Might output 'image/webp' or 'application/pdf' if identifiable
54+
55+
### Checking if a MIME Type Matches a Specific Kind
56+
57+
To check if a MIME type belongs to a specific category or kind:
58+
59+
$filePath = '/path/to/file';
60+
$allowed_type = 'image';
61+
if (ee('MimeType')->isOfKind(ee('MimeType')->ofFile($filePath), $allowed_type)) {
62+
echo 'This file is of the allowed type.';
63+
}
64+
65+
### Validating if a File is Safe for Upload
66+
67+
To ensure a file's MIME type is in the whitelist and safe for upload:
68+
69+
$path = '/path/to/uploaded/file';
70+
if (ee('MimeType')->fileIsSafeForUpload($path)) {
71+
echo 'This file is safe to upload.';
72+
} else {
73+
echo 'This file type is not allowed.';
74+
}
75+
76+
### Checking if a MIME Type is Safe for Upload
77+
78+
To check a specific MIME type against the whitelist:
79+
80+
$mime = 'image/png';
81+
$safeForUpload = ee('MimeType')->isSafeForUpload($mime) ? $mime : false;
82+
if ($safeForUpload) {
83+
echo 'This MIME type is safe for upload.';
84+
}
85+
86+
### Checking if a File is an Image
87+
88+
To determine if a file is an image based on its MIME type and content:
89+
90+
$path = '/path/to/file';
91+
if (ee('MimeType')->fileIsImage($path)) {
92+
echo 'This file is an image.';
93+
}
94+
95+
## MimeType Methods
96+
97+
**class `ExpressionEngine\Library\Mime\MimeType`**
98+
99+
[TOC=3]
100+
101+
### `addMimeType($mime, $kind = null)`
102+
103+
Adds a single MIME type to the whitelist.
104+
105+
| Parameter | Type | Description |
106+
| --------- | -------- | ------------------------------------- |
107+
| \$mime | `String` | The MIME type to add |
108+
| \$kind | `String` | Optional category or kind of MIME type|
109+
| Returns | `Void` | |
110+
111+
### `addMimeTypes(array $mimes, $kind = null)`
112+
113+
Adds multiple MIME types to the whitelist.
114+
115+
| Parameter | Type | Description |
116+
| --------- | -------- | ------------------------------------- |
117+
| \$mimes | `Array` | An array of MIME types to add |
118+
| \$kind | `String` | Optional category or kind of MIME type|
119+
| Returns | `Void` | |
120+
121+
### `getWhitelist()`
122+
123+
Returns the current whitelist of MIME types.
124+
125+
| Parameter | Type | Description |
126+
| --------- | ------- | ------------------------------------- |
127+
| Returns | `Array` | An array of whitelisted MIME types |
128+
129+
### `isOfKind($mime, $mimeTypeKind)`
130+
131+
Checks if a MIME type belongs to a specific kind or category.
132+
133+
| Parameter | Type | Description |
134+
| --------------- | -------- | ------------------------------------- |
135+
| \$mime | `String` | The MIME type to check |
136+
| \$mimeTypeKind | `String` | The kind or category to check against |
137+
| Returns | `Boolean`| TRUE if it matches the kind, FALSE otherwise |
138+
139+
### `ofFile($path)`
140+
141+
Determines the MIME type of a file.
142+
143+
| Parameter | Type | Description |
144+
| --------- | -------- | ------------------------------------- |
145+
| \$path | `String` | The full path to the file |
146+
| Returns | `String` | The MIME type of the file |
147+
148+
### `ofBuffer($buffer)`
149+
150+
Determines the MIME type of a data buffer.
151+
152+
| Parameter | Type | Description |
153+
| --------- | -------- | ------------------------------------- |
154+
| \$buffer | `String` | The data buffer to check |
155+
| Returns | `String` | The MIME type of the buffer |
156+
157+
### `guessOctetStream($contents)`
158+
159+
Attempts to guess a more specific MIME type for data identified as `application/octet-stream`.
160+
161+
| Parameter | Type | Description |
162+
| ----------- | -------- | ------------------------------------- |
163+
| \$contents | `String` | The content to analyze |
164+
| Returns | `String` | The guessed MIME type |
165+
166+
### `fileIsImage($path)`
167+
168+
Determines if a file is an image.
169+
170+
| Parameter | Type | Description |
171+
| --------- | -------- | ------------------------------------- |
172+
| \$path | `String` | The full path to the file |
173+
| Returns | `Boolean`| TRUE if it is an image, FALSE otherwise |
174+
175+
### `isImage($mime)`
176+
177+
Checks if a MIME type is recognized as an image type.
178+
179+
| Parameter | Type | Description |
180+
| --------- | -------- | ------------------------------------- |
181+
| \$mime | `String` | The MIME type to check |
182+
| Returns | `Boolean`| TRUE if it is an image type, FALSE otherwise |
183+
184+
### `fileIsSafeForUpload($path)`
185+
186+
Checks if a file's MIME type is safe for upload based on the whitelist.
187+
188+
| Parameter | Type | Description |
189+
| --------- | -------- | ------------------------------------- |
190+
| \$path | `String` | The full path to the file |
191+
| Returns | `Boolean`| TRUE if safe for upload, FALSE otherwise |
192+
193+
### `isSafeForUpload($mime)`
194+
195+
Checks if a specific MIME type is safe for upload based on the whitelist.
196+
197+
| Parameter | Type | Description |
198+
| --------- | -------- | ------------------------------------- |
199+
| \$mime | `String` | The MIME type to check |
200+
| Returns | `Boolean`| TRUE if safe for upload, FALSE otherwise |
201+
202+
### `whitelistMimesFromConfig()`
203+
204+
Loads MIME types from configuration files into the whitelist, including any additional MIME types specified in the configuration.
205+
206+
| Parameter | Type | Description |
207+
| --------- | ------- | ------------------------------------- |
208+
| Returns | `Void` | |

0 commit comments

Comments
 (0)