Summary

Properties

Description

This datatype allows the storage and retrieval of a single file. It is capable of handling virtually any file type and is typically used for storing legacy document types such as PDF files, Word documents, spreadsheets, etc. The maximum allowed file size is determined by the "Max file size" class attribute edit parameter and the "upload_max_filesize" directive in the main PHP configuration file ("php.ini"). The following screenshot shows the class attribute edit interface for this datatype.

Class attribute edit interface for the "File" datatype.

Max file size

The "Max file size" parameter makes it possible to set the highest size (in megabytes) that the system will allow. By default, this parameters is zero, which means that eZ publish will not do any size checking when files are uploaded. In the example above, the "Max file size" parameter is set to 16 MB, which means that the object edit interface will not allow the upload of files that are larger than 16 megabytes. However, if the value of the "upload_max_filesize" PHP setting is lower than 16 megabytes, the underlying system will cancel the upload.

Object attribute edit interface

The following screenshot shows the object attribute edit interface when an attribute using this datatype does not contain any file.

Object attribute edit interface for the "File" datatype.

The following screenshot shows the object attribute edit interface when an attribute using this datatype contains a file. The interface reveals the name of the file that was uploaded ("BDScratch.wav"), the MIME type ("audio/wav") and the size (1.15 MB).

Object attribute edit interface for the "File" datatype.

MIME types

The MIME type will be automatically set based on the extension of the uploaded file's name. If the extension is unknown, the default MIME type will be used ("application/octet-stream"). The MIME types can be configured at the end of the "/lib/ezutils/classes/ezmimetype.php" file.

Storage

The uploaded files are stored on the filesystem. The main reason for this is because the filesystem is much faster than the database when it comes to the storage and retrieval of large data chunks. Having the files on the filesystem allows the webserver to serve them directly without the need of going through the database. In addition, this technique makes it easier to use external tools to manipulate/scan/index the contents of the uploaded files and it dramatically decreases the size of the database.

All files uploaded through an attribute that makes use of the file datatype will be stored below "storage/original" within the directory specified by the "VarDir" directive in a configuration override for "site.ini". A new subdirectory will be created for every MIME type. For example, if an executable (.exe) file is uploaded, a directory called "application" will be created; if a text file is uploaded then a directory called "text" will be created, and so on. The uploaded files will be put in the different MIME type directories. Instead of re-using the original filenames, eZ publish will create a hash for every file. The following illustration shows the location of two uploaded files (an .exe and a .txt file) when the var directory is set to "my_site".

Complete directory structure with uploaded files.

The system keeps track of the files using a database table called "ezbinaryfile" consisting of the following fields:

Binary file indexing

eZ publish is capable of indexing the actual contents of uploaded files. This feature makes it possible to use the built-in search engine to search for something that is inside a file; for example the contents of a PDF file or a spreadsheet. By default, the system is only capable of indexing the contents of plain text/ASCII files. However, by making use of external programs, it is capable of indexing the contents of virtually any file type (as long as there is a program that goes through the file and returns keywords/contents as plain text). The external handlers can be set up in a configuration override for the "binaryfile.ini" file.

Raw output

The ".content" of an ezcontentobjectattribute object using this datatype returns an ezbinaryfile object.