Serving files

There are a lot of ways that files of various types can be served in Moodle and various API to help do it correctly. This page aims to link together all the various ways in one place with the pros and cons and best practice of each way.

Factors to consider

Security

If your files must only be visible to people with certain roles then that is a clear indication that it should use the pluginfile API.

Performance and caching

One of the driving reasons for this page is making sure that any public files which can be cached are done so in the correct way so that they can be offloaded to a CDN like Cloudflare or Cloudfront or reverse proxy such as Varnish or nginx.

Maintenance

Some ways of serving files have a lower maintenance cost than others so it is better to use the best practice way of doing things below.

Ways of serving files

Javascript files

For all javascript files whether files you have written yourself or 3rd party bundle libraries see: Javascript Modules

CSS files

Themes overview#CSS

Font files

Themes overview#Adding custom fonts

Icons / pix inside a theme

Themes overview#Making use of images

Images in a plugin

TBA

File API and pluginfile.php

For any files which have been uploaded into the Moodle File API and need to be served see File API#Serving files to users

Note that this API can also be used for files which are not in the File API, such as files on disk, or files which are generated on demand.

Data format API

If you need to generate a structured file on demand such as a CSV or Excel it is generally best to use the Data formats API. The Data format API can also be used in conjunction with the pluginfile API.

RSS and Calendar export

There are dedicated API's for serving RSS API and Calendar API data.

Custom download.php endpoint

It is easy and temping to implement your own custom script which downloads or serves a file. In the majority of cases the same functionality could be done via the pluginfile.php API so you can remove a lot of boilerlate and get a lot of functionality for free by avoiding this approach.

File with a .well-known or preset url structure

Often to implement some sort of protocol which another service with interact with, the url you serve on must have a specific location. For example:

/.well-known/password-change

Moodle currently does not yet have any proper generic routing framework to accept 'clean urls' and divert them to the appropriate plugin for handling.

Direct from Apache / nginx

This is only included for completeness and in general you should almost never serve files of any type directly from your web server. As a rule of thumb you should be able to comment out the native file serving directives in your nginx config and everything should still work because all files are served through php rather than directly. This may seem like it would be worse for performance in some cases, but it is actually better as Moodle is designed to sit behind a reverse proxy caching server or a CDN like Cloudflare, Cloudfront etc.