# Filesystem

> Runs native filesystem calls and turns the PHP warning of a failed call into a RuntimeException.

[API reference](/docs/api/index.md) › [Scaffold](/docs/extensions/scaffold/reference/index.md) › Filesystem

| final class | `PHPForge\Scaffold\Filesystem` |
| --- | --- |
| Source | [`src/Filesystem.php`](https://github.com/php-forge/scaffold/blob/main/src/Filesystem.php#L34) |

Runs native filesystem calls and turns the PHP warning of a failed call into a [`RuntimeException`](https://www.php.net/manual/en/class.runtimeexception.php).

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| [`copy()`](#method-copy) static | Copies a file, overwriting the destination. | `Filesystem` |
| [`copyPermissions()`](#method-copyPermissions) static | Copies the permission bits of a file, masked by the current `umask`, onto another file. | `Filesystem` |
| [`hash()`](#method-hash) static | Returns the hexadecimal SHA-256 hash of a file. | `Filesystem` |
| [`isEmptyDirectory()`](#method-isEmptyDirectory) static | Returns whether a directory holds no entry. | `Filesystem` |
| [`mkdir()`](#method-mkdir) static | Creates a directory and its missing parents. | `Filesystem` |
| [`read()`](#method-read) static | Returns the content of a file. | `Filesystem` |
| [`readLink()`](#method-readLink) static | Returns the target of a symbolic link. | `Filesystem` |
| [`remove()`](#method-remove) static | Deletes a file. | `Filesystem` |
| [`removeDirectory()`](#method-removeDirectory) static | Removes an empty directory. | `Filesystem` |
| [`write()`](#method-write) static | Writes content to a file, creating or truncating it. | `Filesystem` |
| [`writeAtomic()`](#method-writeAtomic) static | Writes content to a temporary file next to `$path` and renames it over `$path`, removing the temporary file when the rename fails. | `Filesystem` |

## Method details

### copy() <span id="method-copy"></span>

```php
public static function copy(string $source, string $destination, string $failure): void
```

Copies a file, overwriting the destination.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$source` | `string` | Absolute path to the source file. |
| `$destination` | `string` | Absolute path to the destination file. |
| `$failure` | `string` | Message of the exception thrown on failure, before the PHP warning. |

**Throws**

- [`RuntimeException`](https://www.php.net/manual/en/class.runtimeexception.php): when the file cannot be copied.

### copyPermissions() <span id="method-copyPermissions"></span>

```php
public static function copyPermissions(string $source, string $destination, string $failure): void
```

Copies the permission bits of a file, masked by the current `umask`, onto another file.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$source` | `string` | Absolute path to the file whose permissions are copied. |
| `$destination` | `string` | Absolute path to the file that receives the permissions. |
| `$failure` | `string` | Message of the exception thrown on failure, before the PHP warning. |

**Throws**

- [`RuntimeException`](https://www.php.net/manual/en/class.runtimeexception.php): when the permissions cannot be read or set.

### hash() <span id="method-hash"></span>

```php
public static function hash(string $path, string $failure): string
```

Returns the hexadecimal SHA-256 hash of a file.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$path` | `string` | Absolute path to the file. |
| `$failure` | `string` | Message of the exception thrown on failure, before the PHP warning. |

**Returns**

`string`: Hexadecimal SHA-256 hash of the file content.

**Throws**

- [`RuntimeException`](https://www.php.net/manual/en/class.runtimeexception.php): when the file cannot be read.

### isEmptyDirectory() <span id="method-isEmptyDirectory"></span>

```php
public static function isEmptyDirectory(string $directory, string $failure): bool
```

Returns whether a directory holds no entry.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$directory` | `string` | Absolute path to the directory. |
| `$failure` | `string` | Message of the exception thrown on failure, before the PHP warning. |

**Returns**

`bool`: `true` when the directory has no entry besides `.` and `..`, `false` otherwise.

**Throws**

- [`RuntimeException`](https://www.php.net/manual/en/class.runtimeexception.php): when the directory cannot be read.

### mkdir() <span id="method-mkdir"></span>

```php
public static function mkdir(string $directory, string $failure): void
```

Creates a directory and its missing parents.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$directory` | `string` | Absolute path to the directory. |
| `$failure` | `string` | Message of the exception thrown on failure, before the PHP warning. |

**Throws**

- [`RuntimeException`](https://www.php.net/manual/en/class.runtimeexception.php): when the directory cannot be created.

### read() <span id="method-read"></span>

```php
public static function read(string $path, string $failure): string
```

Returns the content of a file.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$path` | `string` | Absolute path to the file. |
| `$failure` | `string` | Message of the exception thrown on failure, before the PHP warning. |

**Returns**

`string`: Content of the file.

**Throws**

- [`RuntimeException`](https://www.php.net/manual/en/class.runtimeexception.php): when the file cannot be read.

### readLink() <span id="method-readLink"></span>

```php
public static function readLink(string $path, string $failure): string
```

Returns the target of a symbolic link.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$path` | `string` | Absolute path to the symbolic link. |
| `$failure` | `string` | Message of the exception thrown on failure, before the PHP warning. |

**Returns**

`string`: Target of the link, as stored in the link.

**Throws**

- [`RuntimeException`](https://www.php.net/manual/en/class.runtimeexception.php): when the link cannot be read.

### remove() <span id="method-remove"></span>

```php
public static function remove(string $path, string $failure): void
```

Deletes a file.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$path` | `string` | Absolute path to the file. |
| `$failure` | `string` | Message of the exception thrown on failure, before the PHP warning. |

**Throws**

- [`RuntimeException`](https://www.php.net/manual/en/class.runtimeexception.php): when the file cannot be deleted.

### removeDirectory() <span id="method-removeDirectory"></span>

```php
public static function removeDirectory(string $directory, string $failure): void
```

Removes an empty directory.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$directory` | `string` | Absolute path to the directory. |
| `$failure` | `string` | Message of the exception thrown on failure, before the PHP warning. |

**Throws**

- [`RuntimeException`](https://www.php.net/manual/en/class.runtimeexception.php): when the directory cannot be removed.

### write() <span id="method-write"></span>

```php
public static function write(string $path, string $content, string $failure): void
```

Writes content to a file, creating or truncating it.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$path` | `string` | Absolute path to the file. |
| `$content` | `string` | Content to write. |
| `$failure` | `string` | Message of the exception thrown on failure, before the PHP warning. |

**Throws**

- [`RuntimeException`](https://www.php.net/manual/en/class.runtimeexception.php): when the file cannot be written.

### writeAtomic() <span id="method-writeAtomic"></span>

```php
public static function writeAtomic(string $path, string $content, string $failure): void
```

Writes content to a temporary file next to `$path` and renames it over `$path`, removing the temporary file
when the rename fails.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$path` | `string` | Absolute path to the file. |
| `$content` | `string` | Content to write. |
| `$failure` | `string` | Message of the exception thrown on failure, before the PHP warning. |

**Throws**

- [`RuntimeException`](https://www.php.net/manual/en/class.runtimeexception.php): when the temporary file cannot be written, renamed or removed.