PHPackages                             molajo/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. molajo/filesystem

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

molajo/filesystem
=================

Simple, uniform file and directory services API for PHP applications that enables applications to interact with any filesystem for which an adapter has been defined in a common way.

v0.4(12y ago)52941[1 PRs](https://github.com/Molajo/Filesystem/pulls)MITPHPPHP >=5.4

Since May 2Pushed 12y ago5 watchersCompare

[ Source](https://github.com/Molajo/Filesystem)[ Packagist](https://packagist.org/packages/molajo/filesystem)[ Docs](http://github.com/Molajo/Filesystem)[ RSS](/packages/molajo-filesystem/feed)WikiDiscussions master Synced 2w ago

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

======= Filesystem
==================

[](#filesystem)

[![Build Status](https://camo.githubusercontent.com/b2be56a059a83d3233653fdb121f2b574883a73bbcfb566a9c52493e1222ffaf/68747470733a2f2f7472617669732d63692e6f72672f4d6f6c616a6f2f46696c6573797374656d2e706e673f6272616e63683d6d6173746572)](https://travis-ci.org/Molajo/Filesystem)

Simple, uniform file and directory services API for PHP applications for interacting with different filesystems in a common way.

System Requirements
-------------------

[](#system-requirements)

- PHP 5.3, or above
- [PSR-0 compliant Autoloader](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md)
- PHP framework independent

At a glance ...
---------------

[](#at-a-glance-)

This is a quick look at the Filesystem API, more information on each method can be found, below. First, the application connects to a [Filesystem](https://github.com/Molajo/Filesystem#filesystem-adapter-handlers). From that point on, reading, writing, listing, copying, moving, etc., files and folders is the same for the application, regardless of the underlying system. With the exception of the read method, each are designed to provide results for either a file or a folder. Since Exceptions can be thrown, it is recommended methods be used within Try/Catch blocks.

[Filesystem Adapter Interface](https://github.com/Molajo/Standard/blob/master/vendor/Molajo/Filesystem/Api/FilesystemInterface.php)

```
    // Instantiate Handler (example local) and pass it into the Filesystem Adapter

    use Molajo\Filesystem\Handler\Local;
    $handler = new Local();

    use Molajo\Filesystem\Adapter;
    $adapter = new Adapter($handler);

    $true_or_false = $adapter->exists('\file\located\here.txt');

    $metadata = $adapter->getMetadata('\file\located\here.txt');
    echo $metadata->owner;      // See complete list of metadata returned, below

    $contents_of_file = $adapter->read('\file\located\here.txt');

    $list_of_results = $adapter->getList($path, $recursive, $extension_list,
        $include_files, $include_folders, $filename_mask);

    $adapter->write($path, $data, $replace, $append, $truncate);

    $adapter->delete($path, $recursive);

    $adapter->copy($path, $target_directory, $target_name, $replace, $target_handler);

    $adapter->move($path, $target_directory, $target_name, $replace, $target_handler);

    $adapter->rename($path, $new_name);

    $adapter->changeOwner($path, $user_name, $recursive);

    $adapter->changeGroup($path, $group_id, $recursive);

    $adapter->changePermission($path, $permission, $recursive);

    $adapter->touch($path, $modification_time, $access_time, $recursive);
```

What is Filesystem?
-------------------

[](#what-is-filesystem)

**Filesystem** provides a common API for File and Folder operations, including: exists, getMetadata, read, getList, write, delete, copy, move, and rename on, and between, filesystems. In addition, applications can perform basic system administrative tasks like changing the owner, group, permissions, lasted updated, and touch dates for files and folders.

### Class Instantiation

[](#class-instantiation)

After instantiating the adapter class for a specific filesystem, the application can then interact with that filesystem.

The local filesystem is default and does require any input. Other filesystems require specific types of input, as described in the **Filesystem Handlers** section, below.

```
    use Molajo\Filesystem\Handler\Local;
    $handler = new Local();

    use Molajo\Filesystem\Adapter;
    $adapter = new Adapter($handler);
```

### Using the Filesystem Adapter

[](#using-the-filesystem-adapter)

Applications can use $adapter to interact with files and folders as in this example of reading a file.

```
    try {
        $results = $adapter->read('\file\located\here.txt');

    } catch (Exception $e) {
        // deal with the exception
    }
```

Filesystem API
--------------

[](#filesystem-api)

Listed are the various methods available, an example, parameters definitions and how to access the results. It is recommended to use each method in a Try/Catch block since the method could throw an exception.

### Exists

[](#exists)

Verifies if the file or folder defined by $path exists, returns true or false.

```
    try {
        $exists = $adapter->exists($path);
    } catch (Exception $e) {
        // deal with the exception
    }

    if ($exists === true) {
			echo 'The file or folder defined in $path does exist.';
    } else {
			echo 'The file or folder defined in $path does NOT exist.';
    }
```

**Parameters**

- **$path** contains an absolute path for a file or folder

### getMetadata

[](#getmetadata)

Retrieves an object containing metadata for the file or folder defined in $path:

```
    try {
        $metadata = $adapter->getMetadata($path);
    } catch (Exception $e) {
        // deal with the exception
    }

    // View all object properties returned

    // Use a single element
    echo $metadata->name;
```

**Parameters**

- **$path** contains an absolute path for a file or folder

#### Metadata

[](#metadata)

The metadata available for each type of Filesystem can vary. For the Local Filesystem, this is the list of metadata available.

**Metadata about the Filesystem** handler, root, persistence, default\_directory\_permissions, default\_file\_permissions and read\_only.

**Metadata about requested path** (be it a file or folder) path, is\_absolute, absolute\_path, exists, owner, group, create\_date, access\_date, modified\_date, is\_readable, is\_writable, is\_executable, is\_directory, is\_file, is\_link, type, name, parent, extension, file\_name\_without\_extension, size and mime\_type.

### Read

[](#read)

To read a specific file from a filesystem:

```
    try {
        $results = $adapter->read('\file\located\here.txt');
    } catch (Exception $e) {
        // deal with the exception
    }
```

**Parameters**

- **$path** contains an absolute path for a file or folder

### Get List

[](#get-list)

Returns an array of files and folders for a given path, optionally recursively processing all sub-folders, and optionally limiting the results to those file extensions identified.

```
    $path = '\file\located\here.txt';
    $recursive = true;
    $extension_list = 'txt, pdf, doc';
    $include_files = false;
    $include_folders = false;
    $filename_mask = null;

    try {
        $results = $adapter->getList($path, $recursive, $extension_list,
            $include_files, $include_folders, $filename_mask);
    } catch (Exception $e) {
        // deal with the exception
    }
```

**Parameters**

- **$path** contains an absolute path for a file or folder
- **$recursive** true (default) or false indicator of whether or not subfolders should be processed
- **$extension\_list** Comma delimited list of file extensions which qualify
- **$include\_files** True or false value used to exclude or include files in list
- **$include\_folders** True or false value used to exclude or include folders in list

### Write

[](#write)

Writes data to the file identified in the given path, optionally replacing existing data, appending to the data that already exists, or truncating the data in the file, but leaving the empty file in place.

```
    $path = '\file\located\here.txt';
    $data = 'Write this data.';
    $replace = true;
    $append = false;
    $truncate = false;

    try {
        $results = $adapter->write($path, $data, $replace, $append, $truncate);

    } catch (Exception $e) {
        // deal with the exception
    }
```

**Parameters**

- **$path** contains an absolute path for the file
- **$data** Content to be written to the file
- **$replace** True or false value indicating whether or not an existing file should be overwritten
- **$append** True or false value indicating whether or not data should be appended to existing data in table
- **$truncate** True or false value indicating whether or not an existing data in the file should be truncated, leaving an empty file

### Delete

[](#delete)

Deletes the folder and/or files identified in the given path, recursively deleting subfolders and files if so specified.

```
    $path = '\example\of\a\folder';
    $recursive = true;

    try {
        $results = $adapter->delete($path, $recursive);
    } catch (Exception $e) {
        // deal with the exception
    }
```

**Parameters**

- **$path** contains an absolute path for the folder or file
- **$recursive** True or false value indicating if subfolders and files should be deleted, too (only valid for folder). False value for folder with subfolders will throw an exception.

### Copy

[](#copy)

Copies the file(s) and folder(s) from a filesystem to a location on the same or a different filesystem.

When copying a single file, a new filename can be specified using the target\_name field.

```
    $path                   = '\copy\contents\from\this\folder';
    $target_directory       = '\to\this\folder';
    $target_name            = null;
    $replace            	= true;
    $target_handler = 'Backup';

    try {
        $adapter->copy($path, $target_directory, $target_name, $replace, $target_handler);
    } catch (Exception $e) {
        // deal with the exception
    }
```

**Parameters**

- **$path** contains an absolute path for the source folder or file
- **$target\_directory** contains an absolute path for the target folder or file
- **$target\_name** contains a different value for filename when copying a file a new filename is desired
- **$replace** True or false value indicating whether the target file, if exists, should be replaced.
- **$target\_handler** Use if copying to a filesystem other than the current filesystem.

### Move

[](#move)

Moves the file(s) and folder(s) from a filesystem to a location on the same or a different filesystem.

When moving a single file, a new filename can be specified using the target\_name field.

```
    $path                   = '\move\contents\from\this\folder';
    $target_directory       = '\to\this\folder';
    $target_name            = null;
    $replace            	= false;
    $target_handler = 'Archive';

    try {
        $adapter->move($path, $target_directory, $target_name, $replace, $target_handler);
    } catch (Exception $e) {
        // deal with the exception
    }
```

**Parameters**

- **$path** contains an absolute path for the source folder or file
- **$target\_directory** contains an absolute path for the target folder or file
- **$target\_name** contains a different value for filename when copying a file a new filename is desired
- **$replace** True or false value indicating whether the target file, if exists, should be replaced.
- **$target\_handler** Use if copying to a filesystem other than the current filesystem.

### Rename

[](#rename)

Renames the file or folder to the specified value.

```
    $path                   = '\copy\this\folder\old_name.txt';
    $new_name               = 'new_name.txt';

    try {
        $adapter->rename($path, $new_name);
    } catch (Exception $e) {
        // deal with the exception
    }
```

**Parameters**

- **$path** contains an absolute path for the source folder or file
- **$target\_name** contains the new value to use for filename

### Change Owner

[](#change-owner)

Change owner for file or folder identified in path, recursively changing the owner for all subordinate files and folders, if specified

```
    $path        = '\this\folder\';
    $user_name   = 'user';
    $recursive   = true;

    try {
        $adapter->changeOwner($path, $user_name, $recursive);
    } catch (Exception $e) {
        // deal with the exception
    }
```

**Parameters**

- **$path** contains an absolute path for the folder or file
- **$user\_name** system user name
- **$recursive** True or false value indicating if subfolders and files should be deleted, too (only valid for folder). False value for folder with subfolders will throw an exception.

### Change Group

[](#change-group)

Change group for file or folder identified in path, recursively changing the group for all subordinate files and folders, if specified

```
    $path        = '\this\folder\';
    $group_id    = 5;
    $recursive   = true;

    try {
        $adapter->changeGroup($path, $group_id, $recursive);
    } catch (Exception $e) {
        // deal with the exception
    }

```

**Parameters**

- **$path** contains an absolute path for the folder or file
- **$group\_id** numeric system group id
- **$recursive** True or false value indicating if subfolders and files should be deleted, too (only valid for folder). False value for folder with subfolders will throw an exception.

### Change Permission

[](#change-permission)

Change permission for file or folder identified in path, recursively changing the permission for all subordinate files and folders, if specified

```
    $path        = '\this\folder\';
    $permission  = 0755;
    $recursive   = true;

    try {
        $adapter->changePermission($path, $permission, $recursive);
    } catch (Exception $e) {
        // deal with the exception
    }

```

**Parameters**

- **$path** contains an absolute path for the folder or file
- **$permission** system user name
- **$recursive** True or false value indicating if subfolders and files should be deleted, too (only valid for folder). False value for folder with subfolders will throw an exception.

### Touch

[](#touch)

Update the modification time and access time for the directory or file identified in $path.

```
    $path                = '\copy\this\folder\old_name.txt';
    $modification_time   = $modification_time;
    $access_time         = $access_time;
    $recursive           = false;

    try {
        $adapter->touch($path, $modification_time, $access_time, $recursive);
    } catch (Exception $e) {
        // deal with the exception
    }
```

**Parameters**

- **$path** contains an absolute path for the source folder or file
- **$modification\_time** contains a PHP time value to be used as the modification time
- **$access\_time** contains a PHP time value to be used as the access time
- **$recursive** true or false value indicating if the changes should be recursively applied to subfolders and files (only for folder)

Filesystem Handlers
-------------------

[](#filesystem-handlers)

To use a filesystem, the application instantiates the Connection class, passing in a request for a specific filesystem adapter handler. Different types of filesystems require different input to access the environment. For example, some systems require username and password authentication. Startup properties are passed into the filesystem adapter handler using the $options array.

### Local Filesystem Handler

[](#local-filesystem-handler)

- **$options** Associative array of named pair values needed to establish a connection for the adapter handler;
- **$handler** Identifier for the file system. Examples include Local (default), Ftp, Media, Dropbox, etc.;

### FTP Filesystem Handler

[](#ftp-filesystem-handler)

This shows how to backup a file on one filesystem to another filesystem.

```
    $options = array(
        'source_handler' => 'local',
        'source_path'    => '/x/y/example',
        'target_handler' => 'ftp',
        'target_path'    => '/x/y/backup',
        'archive'        => 'zip'
    );

    $adapter = new \Molajo\Filesystem\File($options);
    $data    = $adapter->backup ();
```

**Parameters**

- **$path** contains an absolute path for the source folder or file
- **$target\_name** contains the new value to use for filename

### Media Filesystem Handler

[](#media-filesystem-handler)

Creative Uses of Filesystem
---------------------------

[](#creative-uses-of-filesystem)

### Merged Filesystems

[](#merged-filesystems)

You can use **Filesystem** to easily create a merged filesystem: Just instantiate multiple classes and merge read results.

### Backup

[](#backup)

**Filesystem** supports copying files and folders to another filesystem. Combining this capability with an application cron job is a good way to schedule backups.

### Archive

[](#archive)

**Filesystem** supports moving files and folders to another filesystem, simplifying the process of content archival.

### Upload and Download

[](#upload-and-download)

Install using Composer from Packagist
-------------------------------------

[](#install-using-composer-from-packagist)

### Step 1: Install composer in your project

[](#step-1-install-composer-in-your-project)

```
    curl -s https://getcomposer.org/installer | php
```

### Step 2: Create a **composer.json** file in your project root

[](#step-2-create-a-composerjson-file-in-your-project-root)

```
{
    "require": {
        "Molajo/Filesystem": "1.*"
    }
}
```

### Step 3: Install via composer

[](#step-3-install-via-composer)

```
    php composer.phar install
```

About
=====

[](#about)

Molajo Project has adopted the following:

- [Semantic Versioning](http://semver.org/)
- [PSR-0 Autoloader Interoperability](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md)
- [PSR-1](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md)and [PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)
- \[phpDocumentor2\] ()
- \[phpUnit Testing\] ()
- \[Travis Continuous Improvement\] ()
- \[Packagist\] ()

Submitting pull requests and features
-------------------------------------

[](#submitting-pull-requests-and-features)

Pull requests [GitHub](https://github.com/Molajo/Filesystem/pulls)

Features [GitHub](https://github.com/Molajo/Filesystem/issues)

Author
------

[](#author)

Amy Stephen -  -
See also the list of [contributors](https://github.com/Molajo/Filesystem/contributors) participating in this project.

License
-------

[](#license)

**Molajo Filesystem** is licensed under the MIT License - see the `LICENSE` file for details

Acknowledgements
----------------

[](#acknowledgements)

**W3C File API: Directories and System** [W3C Working Draft 17 April 2012 → ](http://www.w3.org/TR/file-system-api/)specifications were followed, as closely as possible.

More Information
----------------

[](#more-information)

- [Extend](/Filesystem/doc/extend.md)

###  Health Score

27

—

LowBetter than 47% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity17

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~113 days

Total

4

Last Release

4459d ago

PHP version history (3 changes)v0.1PHP >=5.3

v0.2PHP >=5.3.10

v0.3PHP >=5.4

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/95525?v=4)[AmyStephen](/maintainers/AmyStephen)[@AmyStephen](https://github.com/AmyStephen)

---

Top Contributors

[![AmyStephen](https://avatars.githubusercontent.com/u/95525?v=4)](https://github.com/AmyStephen "AmyStephen (170 commits)")

---

Tags

filesystemMolajoCommonApi

### Embed Badge

![Health badge](/badges/molajo-filesystem/health.svg)

```
[![Health](https://phpackages.com/badges/molajo-filesystem/health.svg)](https://phpackages.com/packages/molajo-filesystem)
```

###  Alternatives

[league/flysystem

File storage abstraction for PHP

13.6k665.7M2.4k](/packages/league-flysystem)[league/flysystem-aws-s3-v3

AWS S3 filesystem adapter for Flysystem.

1.7k277.8M959](/packages/league-flysystem-aws-s3-v3)[knplabs/gaufrette

PHP library that provides a filesystem abstraction layer

2.5k40.9M129](/packages/knplabs-gaufrette)[knplabs/knp-gaufrette-bundle

Allows to easily use the Gaufrette library in a Symfony project

72429.6M99](/packages/knplabs-knp-gaufrette-bundle)[league/flysystem-local

Local filesystem adapter for Flysystem.

224254.9M71](/packages/league-flysystem-local)[oneup/flysystem-bundle

Integrates Flysystem filesystem abstraction library to your Symfony project.

64223.5M78](/packages/oneup-flysystem-bundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)