MediaService

Registered as service('media'). Handles file validation, image conversion, and storage for uploaded media files.

upload(object $file, int $uploadedBy): array|false

Validates, processes, and stores an uploaded file. Returns a metadata array on success, false on failure.

$file   = $this->request->getFile('media');
$result = service('media')->upload($file, auth()->id());

if ($result === false) {
    return redirect()->back()->with('error', 'Upload failed');
}

// Insert into media table
model('MediaModel')->insert($result);

Parameters

Validation Rules

• Allowed MIME types: image/jpeg, image/png, image/gif, image/webp, image/svg+xml, application/pdf, video/mp4
• Maximum file size: 10 MB (configurable in app/Config/Media.php)
• File names are sanitised and made unique (appends timestamp hash)

Image Processing

For JPEG and PNG uploads, MediaService automatically converts the image to WebP format using PHP's GD extension. The original file is discarded. SVG, GIF, PDF, and video files are stored as-is.

Return Array

[
    'filename'    => 'my-photo-1700000000ab12.webp',
    'path'        => 'uploads/2026/04/',
    'full_path'   => 'writable/uploads/2026/04/my-photo-1700000000ab12.webp',
    'url'         => 'https://example.com/uploads/2026/04/my-photo-1700000000ab12.webp',
    'mime_type'   => 'image/webp',
    'size'        => 45231,
    'alt_text'    => '',
    'title'       => 'my-photo',
    'uploaded_by' => 1,
]

The full_path is the filesystem path inside writable/uploads/. The url is the public URL via the uploads route.

Storage Location

Files are stored in writable/uploads/{year}/{month}/. The directory is created automatically if it does not exist. writable/ must be writeable by the web server process.

Usage in Admin Controllers

public function store(): ResponseInterface
{
    $file   = $this->request->getFile('file');
    $result = service('media')->upload($file, auth()->id());

    if (! $result) {
        return $this->response->setJSON(['success' => false, 'error' => 'Upload failed']);
    }

    $id = model('MediaModel')->insert($result);
    ActivityLogger::log('media.uploaded', 'media', $id, $result['filename']);

    return $this->response->setJSON(['success' => true, 'media' => $result]);
}