User Guide Cancel

cffile

 

Description

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

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.

<cfset filename = expandpath('./myfile.txt')>
<cftry>
<cffile action="write" file="#filename#">
some tag body
</cffile>
<cfset content = FileRead(filename)>
<cfoutput>File Length = #Len(content)#</cfoutput>
<cfcatch type="any">
<cfoutput>
#cfcatch.message#
<br>#cfcatch.detail#
<br>
</cfoutput>
</cfcatch>
</cftry>

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:

<!--- Leave a blank line here--->
</cffile>

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

<cfset variables.URL = "http://#cgi.server_name#:#cgi.server_port##
getDirectoryFromPath(cgi.script_name)#_upload.cfm">
<cfhttp method="Post" url="#variables.URL#">
<cfhttpparam type="FILE" name="myfile" file="#expandpath('./sample.txt')#">
</cfhttp>
<cfoutput>#cfhttp.filecontent#</cfoutput>
<cfcatch>
<cfoutput>
#CFCATCH.message#
<br>#CFCATCH.detail#
<br>
</cfoutput>
</cfcatch>
</cftry>

_upload.cfm

<!--- create upload directory --->
<cfif not directoryExists(uploadDirectory)>
<cfdirectory action="create" directory="#uploadDirectory#">
</cfif>
<cftry>
<cffile action="UPLOAD" destination="#uploadDirectory#" filefield="form.myFile"
nameconflict="MAKEUNIQUE" accept=".txt">
<cfcatch>
<cfoutput>
#CFCATCH.message#
<br>#CFCATCH.detail#
<br>
</cfoutput>
</cfcatch>
</cftry>
<!--- read directory --->
<cfdirectory action="LIST" directory="#uploadDirectory#" name="qFileList">
<cfoutput>#qFileList.recordcount#
file(s) uploaded
<br>
</cfoutput>
<!--- delete all the uploaded files--->
<!---
<cfloop query="qFileList">
<cffile action="delete" file="#uploadDirectory#/#Name#">
</cfloop>
--->
<!--- delete directory --->
<!---
<cfdirectory action="delete" directory="#uploadDirectory#">
--->

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:

destination="#uploadDirectory#"
filefield="form.myFile"
nameconflict="MAKEUNIQUE "
accept="application/pdf "
strict=true>

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

<cfhttpparam type="FILE" name="myfile" file="#expandpath('./sample.txt')#">

Example 3: Using both extension and MIME type

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

action="UPLOAD"
destination="#uploadDirectory#"
filefield="form.myFile"
nameconflict="MAKEUNIQUE"
accept=".txt, application/pdf"
strict=true>

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:

<cfhttpparam type="FILE" name="myfile" file="#expandpath('./sample.txt')#">

Example

This is a view-only example. --->
<!---
<cfif IsDefined("form.formsubmit") is "Yes">
<!--- The form has been submitted, now do the action. --->
<cfif form.action is "new">
<!--- Make a new file. --->
<cffile action="Write"
file="#GetTempDirectory()#foobar.txt"
output="#form.the_text#">
</cfif>
<cfif form.action is "read">
<!--- Read existing file. --->
<cffile action="Read"
file="#GetTempDirectory()#foobar.txt"
variable="readText">
</cfif>

<cfif form.action is "add">
<!--- Update existing file. --->
<cffile action="Append"
file="#GetTempDirectory()#foobar.txt"
output="#form.the_text#">
</cfif>

<cfif form.action is "delete">
<!--- Delete existing fil. --->
<cffile action="Delete"
file="#GetTempDirectory()#foobar.txt">
</cfif>
</cfif>
<!--- Set some variables. --->
<cfparam name="fileExists" default="no">
<cfparam name="readText" default="">
<!--- First, check whether canned file exists. --->
<cfif FileExists("#GetTempDirectory()#foobar.txt") is "Yes">
<cfset fileExists="yes">
</cfif>
<!--- Now, make the form that runs the example. --->
<form action="index.cfm" method="POST">
<h4>Type in some text to include in your file:</h4> <p>
<cfif fileExists is "yes">
<p>A file exists (foobar.txt, in <cfoutput>#GetTempDirectory()#</cfoutput>).
You may add to it, read from it, or delete it. </p>
</cfif>
<!--- If reading from a form, let that information display in textarea. --->
<textarea name="the_text" cols="40" rows="5">
<cfif readText is not "">
<cfoutput>#readText#</cfoutput>
</cfif></textarea>
<!--- Select from the actions depending on whether the file exists. --->
<select name="action">
<cfif fileExists is "no">
<option value="new">Make new file
</cfif>
<cfif fileExists is "yes">
<option value="add">Add to existing file
<option value="delete">Delete file
<option value="read">Read existing file
</cfif>
</select>
<input type="Hidden" name="formsubmit" value="yes">
<input type="Submit" name="" value="make my changes">
</form> --->

Get help faster and easier

New user?