Saving Content on the Server from your Module
Earlier we mentioned the html/content folder where Mercury stores user-contributed files. Under this is a folder called mercury-modules and under that a module can set up its own folder to store files. The forums module would upload files into the html/content/mercury-modules/forums. To make this easy to access in your code Mercury provides a global definition MODULE_CONTENT_PATH.
You can build an upload destination path like this:
$uploadpath = MODULE_CONTENT_PATH . 'yourmodulename/' . $yourVariablesHere;
Mercury doesn't provide the actual upload mechanism but you can use this syntax to help decide where to store your files. You are not required to store your files using this convention but this is how the core modules store content and it's a fine way to do it unless you have a specific reason to do otherwise.
A Core Mercury Function You Might Want
If you want to store all of your uploaded content in a single folder (or store all of your folders of content) in one spot then you can certainly do that. If you want to have a structured hierarchy of folders that keep folder contents smaller then you could use the following function (or roll your own):
$folderstructure = m("core", "threeDigitDirectory", $PrimaryKey);
Pass a value into this function and it will create a directory path based on the last three digits of that value. For a $PrimaryKey value of 7 this function will return 0/0/7/. The first three folders are a breakdown of the last three digits of the $PrimaryKey. Passing in 583473 would yield 4/7/3/.
Put Them Together
Putting these two concepts together we can specify a full path that consists of the module storage folder and the structured folder path:
$pathbit = m("core", "threeDigitDirectory", $PrimaryKey);
$path = CONTENT_PATH . "yourmodulename/" . $pathbit . $PrimaryKey. "/";
Based on what we said above, and with a $PrimaryKey of 12345, this would result in $path being equal to html/content/mercury-modules/yourmodulename/3/4/5/12345/. You can then store any files that pertain to this $PrimaryKey in this folder with confidence.