<cffile>

Handles all common interactions with files.

The attributes you use with cffile depend on the value of the action attribute.

For example, if the action = "write", use the attributes associated with writing a text file.

This tag may have a body.

This tag is also supported within <cfscript>


		<cffile
    storeAcl=object
    action=info|move|rename|copy|delete|read|readBinary|write|append|upload|uploadAll|touch
    serverPassword=string
    source=string
    attributes=string
    destination=string
    mode=string
    fileField=string
    charset=string
    nameConflict=string
    accept=string
    strict=boolean
    createPath=boolean
    file=string
    variable=string
    output=any
    cachedWithin=object
    addNewLine=boolean
    fixNewLine=boolean
    result=string
    allowedExtensions=any
    blockedExtensions=any
><!--- body --->[</cffile>]

Attribute	Description
action _{string, required}	edit Type of file manipulation that the tag performs. info FileInfo() move FileMove() rename copy FileCopy() delete FileDelete() read FileRead() readbinary FileReadBinary() write FileWrite() append FileAppend() upload FileUpload() uploadall FileUploadAll() touch FileTouch() Note: action upload return the status of the upload operation as a struct after the file upload
serverPassword _{string, optional}	edit allow you to access filesystem, also when access is denied for your context

Attribute

Description

action

_{string, required}

edit

Type of file manipulation that the tag performs.

info FileInfo()
move FileMove()
rename
copy FileCopy()
delete FileDelete()
read FileRead()
readbinary FileReadBinary()
write FileWrite()
append FileAppend()
upload FileUpload()
uploadall FileUploadAll()
touch FileTouch()

Note: action upload return the status of the upload operation as a struct after the file upload

serverPassword

_{string, optional}

edit

allow you to access filesystem, also when access is denied for your context

Read File

action="read" - Read text content from a file

Attribute	Description
file _{string, optional}	edit Absolute pathname of file on web server.
variable _{string, optional}	edit Name of variable to contain contents of text file.
charset _{string, optional}	edit Character set name for the file contents.
cachedWithin _{object, optional}	edit possible values are: String "request": If original content was created within the current request, cached content data is used. a timespan (created with function CreateTimeSpan): If original content date falls within the time span, cached content data is used. To use cached data, the tag must be called with the exact same arguments. Only used by action "read" and "readbinary" Introduced: 5.0.0.0

Read Binary File

action="readBinary" - Read binary content from a file

Attribute

Description

file

_{string, optional}

edit

Absolute pathname of file on web server.

variable

_{string, optional}

edit

Name of variable to contain contents of text file.

cachedWithin

_{object, optional}

edit

possible values are:

String "request": If original content was created within the current request, cached content data is used.
a timespan (created with function CreateTimeSpan): If original content date falls within the time span, cached content data is used.

To use cached data, the tag must be called with the exact same arguments.

Only used by action "read" and "readbinary"

Introduced: 5.0.0.0

Write File

action="write" - Write text content to a file

Attribute	Description
file _{string, optional}	edit Absolute pathname of file on web server.
output _{any, optional}	edit Content of the file to be created.
charset _{string, optional}	edit Character set name for the file contents.
addNewLine _{boolean, optional}	edit Yes: appends newline character to text written to file
fixNewLine _{boolean, optional}	edit true: changes embedded line-ending characters in string variables to operating-system specific line endings false: (default) do not change embedded line-ending characters in string variables.
createPath _{boolean, optional}	edit for action "append", "touch" and "write": if set to false (default), expects all parent directories to exist, true will generate necessary directories
mode _{string, optional}	edit Applies only to Solaris and HP-UX. Permissions. Octal values of UNIX chmod command. Assigned to owner, group, and other, respectively.
attributes _{string, optional}	edit One attribute (Windows) or a comma-delimited list of attributes (other platforms) to set on the file. If omitted, the file's attributes are maintained.
storeAcl _{object, optional}	edit Access Control List (ACL) to use for new files. Can be a either a string (`"authenticated-read"`, `"private"`, `"public-read"`, or `"public-read-write"`), or an array of structs where each struct represents a permission or grant. Example: `[{email="xxx@yyy.com", permission="full_control"}, {group="all", permission="read"}]` Defaults to the value specified in the application's `this.s3.acl`, which is `"public"` if unspecified. _{Alias: acl}

Append to File

action="append" - Append content to existing file

Attribute	Description
file _{string, optional}	edit Absolute pathname of file on web server.
output _{any, optional}	edit Content of the file to be created.
charset _{string, optional}	edit Character set name for the file contents.
addNewLine _{boolean, optional}	edit Yes: appends newline character to text written to file
fixNewLine _{boolean, optional}	edit true: changes embedded line-ending characters in string variables to operating-system specific line endings false: (default) do not change embedded line-ending characters in string variables.
createPath _{boolean, optional}	edit for action "append", "touch" and "write": if set to false (default), expects all parent directories to exist, true will generate necessary directories
mode _{string, optional}	edit Applies only to Solaris and HP-UX. Permissions. Octal values of UNIX chmod command. Assigned to owner, group, and other, respectively.
attributes _{string, optional}	edit One attribute (Windows) or a comma-delimited list of attributes (other platforms) to set on the file. If omitted, the file's attributes are maintained.
storeAcl _{object, optional}	edit Access Control List (ACL) to use for new files. Can be a either a string (`"authenticated-read"`, `"private"`, `"public-read"`, or `"public-read-write"`), or an array of structs where each struct represents a permission or grant. Example: `[{email="xxx@yyy.com", permission="full_control"}, {group="all", permission="read"}]` Defaults to the value specified in the application's `this.s3.acl`, which is `"public"` if unspecified. _{Alias: acl}

Upload File

action="upload" - Handle file uploads from forms

Attribute	Description
destination _{string, optional}	edit Absolute pathname of directory or file on web server.
fileField _{string, optional}	edit Name of form field used to select the file.
nameConflict _{string, optional}	edit Action to take if filename is the same as that of a file in the directory. skip error overwrite makeunique forceunique
accept _{string, optional}	edit list of supported extensions or/and mimetypes.
strict _{boolean, optional}	edit for action "upload" and "uploadAll": if set to true (default), only mimetypes are supported.
result _{string, optional}	edit Name of the result value (default:cffile)
allowedExtensions _{any, optional}	edit String list or string array of extensions allowed, this overwrites any other setting including the attribute [blockedExtensions] and settings done for example in the Application.cfc. _{Alias: allowextension, allowedextension} Introduced: 5.3.8.107
blockedExtensions _{any, optional}	edit String list or string array of extensions blocked, this overwrites any setting done for example in the Application.cfc. _{Alias: blockextension, blockedextension} Introduced: 5.3.8.107
attributes _{string, optional}	edit One attribute (Windows) or a comma-delimited list of attributes (other platforms) to set on the file. If omitted, the file's attributes are maintained.
storeAcl _{object, optional}	edit Access Control List (ACL) to use for new files. Can be a either a string (`"authenticated-read"`, `"private"`, `"public-read"`, or `"public-read-write"`), or an array of structs where each struct represents a permission or grant. Example: `[{email="xxx@yyy.com", permission="full_control"}, {group="all", permission="read"}]` Defaults to the value specified in the application's `this.s3.acl`, which is `"public"` if unspecified. _{Alias: acl}

Upload All Files

action="uploadAll" - Handle multiple file uploads from forms

Attribute	Description
destination _{string, optional}	edit Absolute pathname of directory or file on web server.
nameConflict _{string, optional}	edit Action to take if filename is the same as that of a file in the directory. skip error overwrite makeunique forceunique
accept _{string, optional}	edit list of supported extensions or/and mimetypes.
strict _{boolean, optional}	edit for action "upload" and "uploadAll": if set to true (default), only mimetypes are supported.
result _{string, optional}	edit Name of the result value (default:cffile)
allowedExtensions _{any, optional}	edit String list or string array of extensions allowed, this overwrites any other setting including the attribute [blockedExtensions] and settings done for example in the Application.cfc. _{Alias: allowextension, allowedextension} Introduced: 5.3.8.107
blockedExtensions _{any, optional}	edit String list or string array of extensions blocked, this overwrites any setting done for example in the Application.cfc. _{Alias: blockextension, blockedextension} Introduced: 5.3.8.107
attributes _{string, optional}	edit One attribute (Windows) or a comma-delimited list of attributes (other platforms) to set on the file. If omitted, the file's attributes are maintained.
storeAcl _{object, optional}	edit Access Control List (ACL) to use for new files. Can be a either a string (`"authenticated-read"`, `"private"`, `"public-read"`, or `"public-read-write"`), or an array of structs where each struct represents a permission or grant. Example: `[{email="xxx@yyy.com", permission="full_control"}, {group="all", permission="read"}]` Defaults to the value specified in the application's `this.s3.acl`, which is `"public"` if unspecified. _{Alias: acl}

Copy File

action="copy" - Copy file to new location

Attribute	Description
source _{string, optional}	edit Absolute pathname of file on web server. On Windows, use backward slashes; on UNIX, use forward slashes.
destination _{string, optional}	edit Absolute pathname of directory or file on web server.
mode _{string, optional}	edit Applies only to Solaris and HP-UX. Permissions. Octal values of UNIX chmod command. Assigned to owner, group, and other, respectively.
attributes _{string, optional}	edit One attribute (Windows) or a comma-delimited list of attributes (other platforms) to set on the file. If omitted, the file's attributes are maintained.
storeAcl _{object, optional}	edit Access Control List (ACL) to use for new files. Can be a either a string (`"authenticated-read"`, `"private"`, `"public-read"`, or `"public-read-write"`), or an array of structs where each struct represents a permission or grant. Example: `[{email="xxx@yyy.com", permission="full_control"}, {group="all", permission="read"}]` Defaults to the value specified in the application's `this.s3.acl`, which is `"public"` if unspecified. _{Alias: acl}

Move/Rename File

action="move" (alias "rename") - Move or rename a file

Attribute	Description
source _{string, optional}	edit Absolute pathname of file on web server. On Windows, use backward slashes; on UNIX, use forward slashes.
destination _{string, optional}	edit Absolute pathname of directory or file on web server.
mode _{string, optional}	edit Applies only to Solaris and HP-UX. Permissions. Octal values of UNIX chmod command. Assigned to owner, group, and other, respectively.
attributes _{string, optional}	edit One attribute (Windows) or a comma-delimited list of attributes (other platforms) to set on the file. If omitted, the file's attributes are maintained.
storeAcl _{object, optional}	edit Access Control List (ACL) to use for new files. Can be a either a string (`"authenticated-read"`, `"private"`, `"public-read"`, or `"public-read-write"`), or an array of structs where each struct represents a permission or grant. Example: `[{email="xxx@yyy.com", permission="full_control"}, {group="all", permission="read"}]` Defaults to the value specified in the application's `this.s3.acl`, which is `"public"` if unspecified. _{Alias: acl}

Delete File

action="delete" - Delete a file

Attribute Description

file

_{string, optional}

edit

Absolute pathname of file on web server.

storeAcl

_{object, optional}

edit

Access Control List (ACL) to use for new files. Can be a either a string ("authenticated-read", "private", "public-read", or "public-read-write"), or an array of structs where each struct represents a permission or grant.

Example: [{email="xxx@yyy.com", permission="full_control"}, {group="all", permission="read"}]

Defaults to the value specified in the application's this.s3.acl, which is "public" if unspecified.

_{Alias:
acl}

Get File Info

action="info" - Retrieve file metadata

Attribute	Description
file _{string, optional}	edit Absolute pathname of file on web server.
variable _{string, optional}	edit Name of variable to contain contents of text file.

Touch File

action="touch" - Create empty file or update timestamp

Attribute Description

file

_{string, optional}

edit

Absolute pathname of file on web server.

createPath

_{boolean, optional}

edit

for action "append", "touch" and "write":

if set to false (default), expects all parent directories to exist, true will generate necessary directories

storeAcl

_{object, optional}

edit

Example: [{email="xxx@yyy.com", permission="full_control"}, {group="all", permission="read"}]

Defaults to the value specified in the application's this.s3.acl, which is "public" if unspecified.

_{Alias:
acl}

Examples

edit

File Upload

<cffile action="upload" destination="destination-directory" fileField="form.fileData" nameconflict="overwrite">

File Write

<cffile action="write" file="#expandPath("./myFile.txt")#" output="Content that you need to write.">

File Read

<cffile action="read" file="#expandpath("./myfile.pdf")#" variable="myfile">

File Rename

<cffile action="rename" source="#expandPath("./myFile.pdf")#" destination="#expandPath("./myNewFileName.pdf")#" attributes="normal">

File Info

<cffile action="info" file="#expandPath("./myFile.txt")#" variable="fileInfo">

File Move

<cffile action="move" source="#expandpath("./myfile.pdf")#" destination="#expandpath("./some/moveditems/")#">

File Copy

<cffile action="copy" source="#expandpath("./myfile.pdf")#" destination="#expandpath("./some/copypath/")#">

File Delete

<cffile action="delete" file="#expandpath("./some/moveditems/")#">

File ReadBinary

<cffile action="readBinary" file="#expandPath("./myFile.txt")#" variable="fileData">

File Append

<cffile action="append" file="#expandPath("./myFile.txt")#" output="Content to append">

File Touch

<cffile action="touch" file="#expandPath("./myFile.txt")#" createpath=true>

Script Examples

File Info

result = fileInfo(getTempFile(getTempDirectory(),"demo"));

File Upload

result = fileupload(getTempDirectory(),"form.fileData"," ","makeunique");

File Write

filewrite(file="#expandPath("./myFile.txt")#" data="Content that you need to write.");

File Read

result = fileread(file="#expandPath("./myFile.txt")#");

File ReadBinary

binaryContent = fileReadBinary(expandPath('./image.jpg'));

File Append

fileAppend("path/to/file", "new content to append")

File Rename

filemove(source="#expandPath("./myFile.txt")#",destination="#expandPath("./myNewFileName.txt")#");

File Move

filemove(source="#expandPath("./myFile.txt")#",destination="#expandPath("./myNewFileName.txt")#");

File Copy

filecopy(source="#expandPath("./myNewFileName.txt")#",destination="#expandPath("./some/moved/")#");

File Delete

filedelete(source="#expandPath("./myFile.txt")#");

File Touch

fileTouch( file="#expandPath("./myFile.txt")#",createPath=true );

Related System Properties / Environment Variables

LUCEE_FILEUPLOAD_ALLOW_MIMETYPE_DETECTION - Boolean value that enables using Tika to detect the mime type for unknown file uploads
Type: boolean, Default: true, Introduced: 7.0.0.312
LUCEE_RESOURCE_CHARSET - Default character set for reading from/writing to various resources (files)
Type: string, Default: system charset
LUCEE_TAG_POPULATE_LOCALSCOPE - Controls whether tags like cflock and cfquery populate their default result variables to local scope when inside a function. When `true`, variables go to local scope. When `false`, restores pre LDEV-5416 behavior where variables go to variables scope
Type: boolean, Default: true, Introduced: 7.0.1.13
LUCEE_UPLOAD_BLOCKLIST - Default block list for the tag cffile action=`upload`. A comma-separated list of extensions that are allowed when uploading files via forms
Type: string

<cffile>

Read File

Read Binary File

Write File

Append to File

Upload File

Upload All Files

Copy File

Move/Rename File

Delete File

Get File Info

Touch File

Examples

File Upload

File Write

File Read

File Rename

File Info

File Move

File Copy

File Delete

File ReadBinary

File Append

File Touch

Script Examples

File Info

File Upload

File Write

File Read

File ReadBinary

File Append

File Rename

File Move

File Copy

File Delete

File Touch

Related System Properties / Environment Variables

See also