# File

Manages interactions with server files.

## Component Signature

```
<bx:File action=[string]
file=[string]
mode=[string]
output=[string]
addnewline=[boolean]
attributes=[string]
charset=[string]
source=[string]
destination=[string]
variable=[string]
filefield=[string]
nameconflict=[string]
accept=[string]
result=[string]
fixnewline=[boolean]
cachedwithin=[numeric]
result=[string] />
```

### Attributes

| Atrribute      | Type      | Required | Description                                                                                                | Default |
| -------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------- | ------- |
| `action`       | `string`  | `true`   | The action to take. One of: append, copy, delete, move, read, readbinary, rename, upload, uploadall, write |         |
| `file`         | `string`  | `false`  | The file to act on                                                                                         |         |
| `mode`         | `string`  | `false`  | The mode to open the file in                                                                               |         |
| `output`       | `string`  | `false`  | The output of the action                                                                                   |         |
| `addnewline`   | `boolean` | `false`  | Add a newline to the end of the file                                                                       |         |
| `attributes`   | `string`  | `false`  | Attributes to set on the file                                                                              |         |
| `charset`      | `string`  | `false`  | The character set to use                                                                                   | `utf-8` |
| `source`       | `string`  | `false`  | The source file                                                                                            |         |
| `destination`  | `string`  | `false`  | The destination file                                                                                       |         |
| `variable`     | `string`  | `false`  | The variable to store the result in                                                                        |         |
| `filefield`    | `string`  | `false`  | The file field to use                                                                                      |         |
| `nameconflict` | `string`  | `false`  | What to do if there is a name conflict                                                                     | `error` |
| `accept`       | `string`  | `false`  | The accept header                                                                                          |         |
| `result`       | `string`  | `false`  | The result of the action                                                                                   |         |
| `fixnewline`   | `boolean` | `false`  | Fix newlines                                                                                               | `false` |
| `cachedwithin` | `numeric` | `false`  | The time to cache the file within                                                                          |         |
| `result`       | `string`  | `false`  | The result of the action                                                                                   |         |

## Examples

### Script Syntax - Write

File Write

[Run Example](https://try.boxlang.io/?code=eJxLy8xJDS%2FKLEnVUEitKEjMSwlILMnQUFDS08%2BtdAPK6ZVUlCgpaOooKHmkFqWqFysU5%2BemKiTn55Wk5pUopOUXKeRWKqSBFAJVWXMBAC4DGa0%3D)

```java
fileWrite( expandPath( "./myFile.txt" ), "Here's some content for my file." );

```

### Script Syntax - Append

File Append - There is no fileAppend() so we access the file and use fileWriteLine()

[Run Example](https://try.boxlang.io/?code=eJzLrXTLzElVsFVIA1L%2BBal5GgqpFQWJeSkBiSUZGgpKevq5YBV6JRUlSgqaOgpKiQVAVSlAtjUXSE94UWZJqk9mXqqGAkQlUIlHalGqerFCcX5uqkJearlCcn5eSWpeiR5ck3NOfjFcA0gQAMNXK50%3D)

```java
myFile = fileOpen( expandPath( "./myFile.txt" ), "append" );
fileWriteLine( myFile, "Here's some new content." );
fileClose( myFile );

```

### Script Syntax - Read

File Read

[Run Example](https://try.boxlang.io/?code=eJzLrXTLzElVsFVIA1JBqYkpGgqpFQWJeSkBiSUZGgpKevq5YBV6JRUlSgqaCprWXAC%2FwxAJ)

```java
myFile = fileRead( expandPath( "./myFile.txt" ) );

```

Result: Here's some content for my file. Here's some new content.

### Script Syntax - Read Binary

File Read Binary

```java
myImageBinary = fileReadBinary( expandPath( "./myImage.jpg" ) );

```

### Script Syntax - Rename

File Rename - Since there is no fileRename(), fileMove() works just as well

```java
fileMove( expandPath( "./myFile.txt" ), expandPath( "./myNewFileName.txt" ) );

```

### Script Syntax - Copy

File Copy

```java
fileCopy( expandPath( "./myFile.txt" ), expandPath( "./some/other/path" ) );

```

### Script Syntax - Move

File Move

```java
fileMove( expandPath( "./myFile.txt" ), expandPath( "./some/other/path" ) );

```

### Script Syntax - Delete

File Delete

[Run Example](https://try.boxlang.io/?code=eJxLy8xJdUnNSS1J1VBIrShIzEsJSCzJ0FBQ0tPPrXQDSuqVVJQoKWgqaFpzAQBZxQ39)

```java
fileDelete( expandPath( "./myFile.txt" ) );

```

### Tag Syntax (action=write)

Write the contents of a variable to a file.

```java
<bx:file action="write" file="#expandPath( "./myFile.txt" )#" output="Here's some content for my file.">
```

### Tag Syntax (action=append)

Append content to the end of a file.

```java
<bx:file action="append" file="#expandPath( "./myFile.txt" )#" attributes="normal" output="Here's some new content.">
```

### Tag Syntax (action=read)

Read a file into a variable

```java
<bx:file action="read" file="#expandPath( "./myFile.txt" )#" variable="myFile">
```

### Tag Syntax (action=readBinary)

File Read Binary

```java
<bx:file action="readBinary" file="#expandPath( "./myImage.jpg" )#" variable="myImageBinary">
```

### Tag Syntax (action=rename)

Rename a file

```java
<bx:file action="rename" source="#expandPath( "./myFile.txt" )#" destination="#expandPath( "./myNewFileName.txt" )#" attributes="normal">
```

### Tag Syntax (action=copy)

Copy a file

```java
<bx:file action="copy" source="#expandPath( "./myFile.txt" )#" destination="#expandPath( "./some/other/path" )#">
```

### Tag Syntax (action=move)

Move a file

```java
<bx:file action="move" source="#expandPath( "./myFile.txt" )#" destination="#expandPath( "./some/other/path" )#">
```

### Tag Syntax (action=delete)

Delete a file

```java
<bx:file action="delete" file="#expandPath( "./myFile.txt" )#">
```

### Tag Syntax (action=upload)

Upload the file contained in the myFile field. Always upload to a directory outside of the webroot, validate the file extension, file content and then only if necessary copy it back to the web root.

```java
<bx:file action="upload" destination="#getTempDirectory()#" filefield="form.myFile" nameconflict="makeunique">
```

### Tag Syntax (action=upload) with accept

CF10+ Checks file extensions against a whitelist of allowed file extensions. You must set `strict=false` when specifying a file extension list.

```java
<bx:file action="upload" accept=".png,.jpg" strict="false" destination="#getTempDirectory()#" filefield="form.myFile" nameconflict="makeunique">
```

### Tag Syntax (action=uploadall)

Upload all files in the form scope.

```java
<bx:file action="uploadall" destination="#getTempDirectory()#" nameconflict="makeunique">
```