PHPackages                             wpjscc/filesystem - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. wpjscc/filesystem

ActiveLibrary[File & Storage](/categories/file-storage)

wpjscc/filesystem
=================

Asynchronous filesystem abstraction.

0.2.0(6mo ago)01645MITPHPPHP >=8.0.0

Since Nov 10Pushed 6mo agoCompare

[ Source](https://github.com/wpjscc/filesystem)[ Packagist](https://packagist.org/packages/wpjscc/filesystem)[ RSS](/packages/wpjscc-filesystem/feed)WikiDiscussions 0.2.x Synced 1mo ago

READMEChangelog (1)Dependencies (10)Versions (2)Used By (5)

Filesystem Component
====================

[](#filesystem-component)

[![CI status](https://github.com/reactphp/filesystem/workflows/CI/badge.svg)](https://github.com/reactphp/filesystem/actions)

[ReactPHP](https://reactphp.org/)'s filesystem component that enables non-blocking filesystem operations.

> **Development version:** This branch contains the code for the upcoming 0.2 release which will be the way forward for this package.
>
> See [installation instructions](#install) for more details.

**Table of Contents**

- [Quickstart example](#quickstart-example)
- [Usage](#usage)
    - [Factory](#factory)
        - [create()](#create)
    - [Filesystem implementations](#filesystem-implementations)
        - [Eio](#eio)
        - [Uv](#uv)
    - [AdapterInterface](#adapterinterface)
        - [detect()](#detect)
        - [directory()](#directory)
        - [file()](#file)
    - [NodeInterface](#nodeinterface)
        - [path()](#path)
        - [name()](#name)
        - [stat()](#stat)
    - [DirectoryInterface](#directoryinterface)
        - [ls](#ls)
    - [FileInterface](#fileinterface)
        - [getContents()](#getcontents)
        - [putContents()](#putcontents)
    - [NotExistInterface](#notexistinterface)
        - [createDirectory()](#createdirectory)
        - [createFile()](#createfile)
- [Install](#install)
- [Tests](#tests)
- [License](#license)

Quickstart example
------------------

[](#quickstart-example)

Here is a program that lists everything in the current directory.

```
use React\Filesystem\Factory;
use React\Filesystem\Node\DirectoryInterface;
use React\Filesystem\Node\NodeInterface;

Factory::create()->detect(__DIR__)->then(function (DirectoryInterface $directory) {
    return $directory->ls();
})->then(static function ($nodes) {
    foreach ($nodes as $node) {
        assert($node instanceof NodeInterface);
        echo $node->name(), ': ', get_class($node), PHP_EOL;
    }
    echo '----------------------------', PHP_EOL, 'Done listing directory', PHP_EOL;
}, function (Throwable $throwable) {
    echo $throwable;
});
```

See also the [examples](examples).

Usage
-----

[](#usage)

See [`Factory::create()`](#create).

### Factory

[](#factory)

The `Factory` class exists as a convenient way to pick the best available [filesystem implementation](#filesystem-implementations).

#### create()

[](#create)

The `create(): AdapterInterface` method can be used to create a new filesystem instance:

```
$filesystem = \React\Filesystem\Factory::create();
```

This method always returns an instance implementing [`adapterinterface`](#adapterinterface), the actual [Filesystem implementations](#filesystem-implementations) is an implementation detail.

This method can be called at any time. However, certain scheduling mechanisms are used that will make the event loop busier with every new instance of a filesystem adapter. To prevent that it is preferred you create it once and inject it where required.

### Filesystem implementations

[](#filesystem-implementations)

In addition to the [`FilesystemInterface`](#filesysteminterface), there are a number of filesystem implementations provided.

All the filesystems support these features:

- Stating a node
- Listing directory contents
- Reading/write from/to files

For most consumers of this package, the underlying filesystem implementation is an implementation detail. You should use the [`Factory`](#factory) to automatically create a new instance.

The factory will determine the most performant filesystem for your environment. Any extension based filesystem are preferred before falling back to less performant filesystems. When no extensions are detected it will fall back to an internal fallback filesystem that uses blocking system calls. As such it is highly recommended to install one of the extensions that unlocks more performant filesystem operations.

Advanced! If you explicitly need a certain filesystem implementation, you can manually instantiate one of the following classes. Note that you may have to install the required PHP extensions for the respective event loop implementation first or they will throw a `BadMethodCallException` on creation.

#### Eio

[](#eio)

An `ext-eio` based filesystem.

This filesystem uses the [`eio` PECL extension](https://pecl.php.net/package/eio), that provides an interface to `libeio` library.

This filesystem is known to work with PHP 7+.

#### Uv

[](#uv)

An `ext-uv` based filesystem.

This filesystem uses the [`uv` PECL extension](https://pecl.php.net/package/uv), that provides an interface to `libuv` library.

This filesystem is known to work with PHP 7+.

### AdapterInterface

[](#adapterinterface)

#### detect()

[](#detect)

The `detect(string $path): PromiseInterface` is the preferred way to get an object representing a node on the filesystem.

When calling this method it will attempt to detect what kind of node the path is you've given it, and return an object implementing [`NodeInterface`](#nodeinterface). If nothing exists at the given path, a [`NotExistInterface`](#notexistinterface) object will be returned which you can use to create a file or directory.

#### directory()

[](#directory)

The `directory(string $path): DirectoryInterface` creates an object representing a directory at the specified path.

Keep in mind that unlike the `detect` method the `directory` method cannot guarantee the path you pass is actually a directory on the filesystem and may result in unexpected behavior.

#### file()

[](#file)

The `file(string $path): DirectoryInterface` creates an object representing a file at the specified path.

Keep in mind that unlike the `detect` method the `file` method cannot guarantee the path you pass is actually a file on the filesystem and may result in unexpected behavior.

### NodeInterface

[](#nodeinterface)

The `NodeInterface` is at the core of all other node interfaces such as `FileInterface` or `DirectoryInterface`. It provides basic methods that are useful for all types of nodes.

#### path()

[](#path)

The `path(): string` method returns the path part of the node's location. So if the full path is `/path/to/file.ext` this method returns `/path/to/`.

#### name()

[](#name)

The `name(): string` method returns the name part of the node's location. So if the full path is `/path/to/file.ext` this method returns `file.ext`.

#### stat()

[](#stat)

The `stat(): PromiseInterface