Caution: This documentation is for eZ Publish legacy, from version 3.x to 6.x.
For 5.x documentation covering Platform see eZ Documentation Center, for difference between legacy and Platform see 5.x Architecture overview.

File

Summary

Stores any type of file.

Properties

NameInternal nameSearchableInformation collector
File ezbinaryfile Yes. No.

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.

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.

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.

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.

Complete directory structure with uploaded files.

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

Field

Description

content_object_attribute_id

The identification of the content object attribute.

download_count

The number of times the file has been downloaded.

filename

The name of the file on the filesystem (for example "5fd39fbaf751369965a4108715d5dea9.txt").

mime_type

The MIME type of the file (for example "text/plain").

original_filename

The original name of the uploaded file (for example "readme.txt").

version

The version of the object that the file belongs to.

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.

Balazs Halasy (21/02/2005 2:35 pm)

Balazs Halasy (06/06/2005 11:55 am)


Comments

  • Fatal errors with a non-required file attribute used in the name pattern

    If you encounter fatal errors when storing an object with a non-required file attribute which is being used in the object's name pattern, then take a look at this bug: http://ez.no/community/bugs/fatal...in_naming_pattern_but_has_no_content.

    It has been fixed in eZ publish 3.7.3, 3.6.5, 3.5.8 and 3.8.0alpha1.