FileDownloadPE: A secure file download snippet for MODx

FileDownloadPE (Pirate Edition) is a secure file downloading snippet for the MODx CMS/F. FileDownloadPE is secure as it hides the actual path to your file. FileDownloadPE keeps track of how many times each file has been downloaded and lets you display that number wherever you want. There are no extra plugins to install with FileDownloadPE, and you can have multiple download links per page. Each "FileDownloadPE" file being served is a MODx document, so you have the full service of Access Control Lists (ACL) meaning you have the ability to restrict downloads to certain groups. FileDownloadPE uses a PHP5 class to ensure data protection and encapsulation. As such, a server running PHP 5.x or greater is required.

FileDownloadPE uses MODx Template Variables (TVs) to specify file name, file path, and MIME type. To get started, download FileDownloadPE.

Installation Updated 2008.06.18 for version 1.1

  1. Step 1:

    Create a new snippet called "FileDownloadPE" and paste the contents of "filedownloadpe.snippet.php" into the Snippet code (php) area. Before you paste you should remove the opening and closing php tags because the text you just copied already has them in it. Click "Save" when you are done.

  2. Step 2:

    Create a new template called "Downloads". In the Template code (html) area, put [ !FileDownloadPE! ]. (If you copy and paste this snippet call, remove the spaces between the square brackets and the exclamation points.)

  3. Step 3: Create three two new template variables: File
    Variable Name:
    File
    Caption:
    File
    Description:
    Path to file
    Input Type:
    File
    Template Access:
    Make sure the "Downloads" template is checked.
    FileMime
    Variable Name:
    FileMime
    Caption:
    FileMime
    Description:
    MIME Type
    Input Type:
    DropDown List Menu
    Input Option Values:
    force-download||application/zip||application/pdf||image/jpg||image/png||text/plain
    Default Value:
    force-download
    Template Access:
    Make sure the "Downloads" template is checked.
    FileName
    Variable Name:
    FileName
    Caption:
    FileName
    Description:
    File Name
    Input Type:
    Text
    Template Access:
    Make sure the "Downloads" template is checked.

    *NOTE: The FileName TV is used to get download counts so make sure it is unique Now uses the document's alias.

Usage

  1. Create a new MODx Document.
  2. Give it a title and alias. * The alias is now used in the database to keep count of the downloads.
  3. Set the "Uses template" drop down menu to "Downloads".
  4. Skip the Document content, and go right to the "Template Variables" section.
    1. Put a unique file name in the FileName TV. * No longer needed. Uses the document alias instead.
    2. Select the correct MIME type from the FileMime drop down TV.
    3. Click "Insert" on the File TV and upload / choose the file to serve.

      *NOTE: You can also manually type in the path of the file relative to the site root.

  5. From the "Page Settings" tab, uncheck "Searchable" and "Cacheable", set the "Content Type" to text/plain, and set the Content Disposition to Attachment.

Parameters

&action (string)
set to count to use this snippet as a download counter.

* Required for providing a download count.

&filename &id (int)
Used with &action to specify the document ID to get counts for.

* Required for providing a download count.

&dberror (string)
The text displayed when an error is encountered while processing the file.

* Optional. Default: "There was an error processing your download request."

&nofile (string)
The error displayed when no file is specified.

* Optional. Default: "No file specified."

&fileNameTV (string)
The name of the MODx TV that holds the file's unique name.

* Optional. Default: "FileName".

&fileMimeTV (string)
The name of the MODx TV that holds the file's MIME type.

* Optional. Default: "FileMime".

&filePathTV (string)
The name of the MODx TV that holds the file's path on the server.

* Optional. Default: "File".

Examples

I created a MODx document (the document ID turned out to be 36) in the fashion described above and set the "FileName" TV to example, the "FileMime" TV to application/zip, and using the "File" TV, I uploaded the file example.zip to my server and chose it as the value for the "File" TV. I gave this document an alias of example.zip. I used the string "example.zip" as the alias so that Windows knows what to use to open it if it is downloaded with IE. On this site, I have the Friendly alias suffix set to blank (I don't think a visitor should EVER have to look at file extension, but that is another blog entry), so if you have a suffix set in your MODx configuration, it could potentially cause problems with a Windows/IE combination unless you manually provide the href in your links instead of letting the MODx parser generate it from the doc ID.

As an example, I duplicated this document (The new document's ID is 37) and gave it an alias of random-name-whatever.zip. As you can see, the URI does not need to match the actual file name. It can be whatever you want. The actual file was uploaded to the root of my site, but you can put your files in any web accessible folder.

Download An example file: Downloaded 1018 times.

Download Same file, different URI: Downloaded 1018 times.

View the source code for this example.

Best Practices

As a best practice for keeping your directory structure clean I suggest creating a MODx document at the root of your site called "Downloads", with an alias of "downloads". This is especially helpful if you use Friendly URLs with Friendly Alias Paths. That way, you directory tree stays clean and your download URLs point to http://yoursite.tld/downloads/FileName. For each file you want to serve, create a new document as a child of this "Downloads" document, configured as described in the Usage section.

Comments for this document are closed.

Archives