cffile

Description

Manages interactions with server files. The following sections describe the actions of the cffile tag:

• cffile action = "append"
• cffile action = "copy"
• cffile action = "delete"
• cffile action = "move"
• cffile action = "read"
• cffile action = "readBinary"
• cffile action = "rename"
• cffile action = "upload"
• cffile action = "uploadAll"

• cffile action = "write"

  Note: To execute, this tag must be enabled in the ColdFusion Administrator. For more information, see Configuring and Administering ColdFusion.

  If your ColdFusion applications run on a server used by multiple customers, consider the security of the files that could be uploaded or manipulated by  cffile . For more information, see Configuring and Administering ColdFusion.

Category

File management tags

Syntax

The tag syntax depends on the action attribute value. See the following sections.

See also

cfdirectory

History

ColdFusion 10: Modifications to the attribute accept

ColdFusion 9: uploadAll action

ColdFusion 8: Support for reading and writing  cfimages .

ColdFusion MX 7:

• Added the result attribute, which allows you to specify an alternate variable in which to receive result parameters. Used for action = "upload" action.
• Added the fixnewline attribute for action = "append" and action = "write" actions.
  ColdFusion MX 6.1:
• Changed file path requirements: if you do not specify an absolute file path, the path is relative to the ColdFusion temporary directory, which is returned by the GetTempDirectory function.
• Changed behavior for action="read": if the file starts with a byte order mark (BOM) ColdFusion uses it to determine the character encoding.
• Changed behavior for action="upload" nameConflict="MakeUnique" ColdFusion now makes filenames unique by appending a incrementing number, 1 for the first file, 2 for the second and so on, to the name. In ColdFusion, filenames were made unique by appending an additional "1" for each file, as in 1, 11, 111, and so on.
  ColdFusion MX:
• Changed use of slashes in paths: you can use forward or backward slashes in paths on both UNIX and Windows systems.
• Changed file hierarchy requirements: ColdFusion does not require that you put files and directories that you manipulate with this tag below the root of the web server document directory.
• Changed directory path requirements for the destination attribute: a directory path that you specify in the destination attribute does not require a trailing slash.
• Deprecated the system value of the attributes attribute.
• Deprecated the temporary value of the attributes attribute. In ColdFusion, it is a synonym for normal. It might not work in later releases.
• Changed the action attribute options read, write, append and move: they support a new attribute, charset.
• The archive value of the attributes attribute is obsolete and has no effect.

Provide file content in the tag body

For cffile action = "append" and cffile action = "write", you can provide file content in the tag body. If you provide file content in both the tag body and the output attribute, it results in an error. In the following example, the text provided in the body is written to myfile.txt in the current directory.Now assume that the file does not exist, then a new file myfile.txt is created. If the file exists, it is overwritten.

Similarly, if you use cffile action="append", the tag body content is appended to the contents of the file myfile.txt. To create an empty file, you have to provide at least a blank line in the tag body as shown in the following code:

Modifications to the attribute accept in ColdFusion 10

The attribute accept takes comma-separated list of any or all extensions, MIME type, or list of MIME types as values. Specify the extensions with a . prefix. That is, only .txt is supported and not txt, *.txt, or *.*. However, you can use * as a wildcard to accept all files.

• If you specify filename extension as value, the file is checked, only to ensure if it matches the list of extensions you specified in comma-separated list. If it matches, the file is uploaded.
• If the value is MIME type or list of MIME types and the attribute strict is set to true, then the first few bytes of the file are read to determine the MIME type. If MIME type matches with what you have specified, upload occurs, else results in an error. The default value of strict is true.
• If you specify both filename extensions and MIME types and if strict is set to false, the verification is based on the order in which you have specified the values. For example, if the first value is .txt, then the .txt file is uploaded.
  If strict is set to true, extensions are ignored.

Example: Using the attribute accept to verify the filename extension

upload.cfm

_upload.cfm

In this example, accept is set to .txt and strict is not specified (and therefore is true by default). So, only files with .txt extensions are considered for upload.Even if the file is originally a PDF (sample.pdf) renamed as sample.txt, the file is uploaded (since strict is not set to true).
If you specify strict=true, then if the file is originally a .txt (and not renamed from some other type) the file is uploaded only if the correct MIME type is specified. That is, strict=true requires MIME type to be specified in the  accept  attribute. So, you should explicitly say accept="text/plain" in _upload.cfm.

Example 2: Using MIME type

Modify the Example 1 by specifying accept="application/pdf" in _upload.cfm as follows:

Since strict = true, only files of type PDF are considered for upload. To use a different file, modify the following section of upload.cfm:

Example 3: Using both extension and MIME type

Modify the Example 1 by specifying the following in _upload.cfm:

Only PDF files are uploaded because strict = true. If you set strict as false, then both the files are uploaded.
To use a different file, modify the following snippet of upload.cfm:

Example