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

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

tobento/service-filesystem
==========================

Provides abstraction layers for dealing with directories and files.

2.0(7mo ago)0536↑150%20MITPHPPHP >=8.4

Since Jun 19Pushed 7mo ago1 watchersCompare

[ Source](https://github.com/tobento-ch/service-filesystem)[ Packagist](https://packagist.org/packages/tobento/service-filesystem)[ Docs](https://www.tobento.ch)[ RSS](/packages/tobento-service-filesystem/feed)WikiDiscussions 2.x Synced 1mo ago

READMEChangelog (8)Dependencies (4)Versions (10)Used By (20)

Filesystem Service
==================

[](#filesystem-service)

The Filesystem Service provides abstraction layers for dealing with directories and files.

Table of Contents
-----------------

[](#table-of-contents)

- [Getting started](#getting-started)
    - [Requirements](#requirements)
    - [Highlights](#highlights)
- [Documentation](#documentation)
    - [Files](#files)
        - [File](#file)
        - [Json File](#json-file)
        - [Pdf File](#pdf-file)
    - [Dir](#dir)
    - [File Formats](#file-formats)
- [Credits](#credits)

---

Getting started
===============

[](#getting-started)

Add the latest version of the Filesystem service project running this command.

```
composer require tobento/service-filesystem

```

Requirements
------------

[](#requirements)

- PHP 8.4 or greater

Highlights
----------

[](#highlights)

- Framework-agnostic, will work with any project
- Decoupled design

Documentation
=============

[](#documentation)

Files
-----

[](#files)

Dealing with different files.

### File

[](#file)

#### Check if it is a file:

[](#check-if-it-is-a-file)

```
use Tobento\Service\Filesystem\File;

$file = new File('home/public/src/foo/image.jpg');

var_dump($file->isFile()); // bool(true)

$file = new File('home/public/src/foo');

var_dump($file->isFile()); // bool(false)
```

#### Check for specific file extension:

[](#check-for-specific-file-extension)

```
use Tobento\Service\Filesystem\File;

$file = new File('home/public/src/foo/image.jpg');

var_dump($file->isExtension(['jpeg', 'tiff'])); // bool(true)

var_dump($file->isImage(['jpeg', 'gif'])); // bool(true)

var_dump($file->isHtmlImage()); // bool(true)

// $file->isHtmlImage() is same as:
$file->isImage(['gif', 'jpeg', 'png', 'webp']);
```

#### File information:

[](#file-information)

```
use Tobento\Service\Filesystem\File;

$file = new File('home/public/src/foo/image.jpg');

var_dump($file->getFile()); // string(30) "/home/public/src/foo/image.jpg"

var_dump($file->getDirname()); // string(21) "/home/public/src/foo/"

var_dump($file->getBasename()); // string(9) "image.jpg"

var_dump($file->getFilename()); // string(5) "image"

var_dump($file->getExtension()); // string(3) "jpg"

var_dump($file->getFolderPath()); // string(0) ""

var_dump($file->getDateModified()); // string(22) "09. June 2021 08:52:28"

var_dump($file->getDateModified('F d Y H:i:s.')); // string(22) "June 09 2021 08:52:28."

var_dump($file->getDateUpdated()); // string(22) "09. June 2021 08:52:28"

var_dump($file->getDateUpdated('F d Y H:i:s.')); // string(22) "June 09 2021 08:52:28."

// size in bytes
var_dump($file->getSize()); // int(34221)

// human readable sizes
var_dump($file->size()); // string(8) "33.42 KB"

// image size data
var_dump($file->getImageSize());
// array(7) { [0]=> int(500) [1]=> int(375) [2]=> int(2) [3]=> string(24) "width="500" height="375"" ["bits"]=> int(8) ["channels"]=> int(3) ["mime"]=> string(10) "image/jpeg"

var_dump($file->getImageSize(1)); // int(375)

// get exif data if exist
var_dump($file->getExifData());
// array(7) { ["FileName"]=> string(9) "image.jpg" ["FileDateTime"]=> int(1623403678) ["FileSize"]=> int(34221) ["FileType"]=> int(2) ["MimeType"]=> string(10) "image/jpeg" ["SectionsFound"]=> string(0) "" ["COMPUTED"]=> array(4) { ["html"]=> string(24) "width="500" height="375"" ["Height"]=> int(375) ["Width"]=> int(500) ["IsColor"]=> int(1) } }

// readable and writable
var_dump($file->isReadable()); // bool(true)

var_dump($file->isWritable()); // bool(true)

// mime type
var_dump($file->getMimeType()); // string(10) "image/jpeg"

var_dump($file->getMimeType(1)); // string(5) "image"

var_dump($file->getMimeType(2)); // string(4) "jpeg"
```

#### File name manipulation:

[](#file-name-manipulation)

These methods return always an new instance.

```
use Tobento\Service\Filesystem\File;

$file = new File('home/public/src/foo/image.jpg');

$newFile = $file->withDirname('home/public/src/bar/');

$newFile = $file->withFilename('new-image');

// Defining a folder path might be useful for certain cases.
$newFile = $file->withFolderPath('foo/bar');

// Generating unique filename.
$file = $file->withUniqueFilename();

var_dump($file->getBasename()); // string(18) "image-20317715.jpg"

var_dump($file->isFile()); // bool(false)
```

#### File copy, move, rename and delete operations:

[](#file-copy-move-rename-and-delete-operations)

These methods return a new instance on success, otherwise null, except for delete operation.

```
use Tobento\Service\Filesystem\File;

$file = new File('home/public/src/foo/image.jpg');

$copiedFile = $file->copy('home/public/src/bar/name.jpg');

$movedFile = $file->move('home/public/src/bar/name.jpg');

$renamedFile = $movedFile->rename('new-name');

var_dump($movedFile->delete()); // bool(true)
```

#### Check if file is within a specified directory:

[](#check-if-file-is-within-a-specified-directory)

```
use Tobento\Service\Filesystem\File;

$file = new File('home/public/src/foo/image.jpg');

var_dump($file->isWithinDir('home/public/src'));
// bool(true)

var_dump($file->isWithinDir('home/public/src/foo/'));
// bool(true)

var_dump($file->isWithinDir('home/public/src/bar/'));
// bool(false)
```

#### File responses

[](#file-responses)

```
use Tobento\Service\Filesystem\File;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\StreamFactoryInterface;

$file = new File('home/public/src/foo/image.jpg');

$downloadResponse = $file->downloadResponse($response, $streamFactory);

$fileResponse = $file->fileResponse($response, $streamFactory);
```

### Json File

[](#json-file)

Providing the following additional methods.

```
use Tobento\Service\Filesystem\JsonFile;

$file = new JsonFile('home/public/src/foo/data.json');

var_dump($file->isJson()); // bool(true)

$array = $file->toArray();

$jsonString = $file->getContent();
```

### Pdf File

[](#pdf-file)

Providing the following additional methods.

```
use Tobento\Service\Filesystem\PdfFile;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\StreamFactoryInterface;

$file = new Pdf('home/public/src/foo/data.pdf');

var_dump($file->isPdf()); // bool(true)

// Content example
$file = new PdfFile('document.pdf');

var_dump($file->isPdf()); // bool(false)

// add content, this will return a new instance.
$file = $file->content($pdfEngine->createPdfString('document.pdf'));

$string = $file->getContent();

$fileResponse = $file->fileResponse($response, $streamFactory);
```

Dir
---

[](#dir)

#### Dir information.

[](#dir-information)

```
use Tobento\Service\Filesystem\Dir;

$dir = new Dir();

var_dump($dir->isDir('home/public/src/foo')); // bool(true)

var_dump($dir->isDir('home/public/src/foo/')); // bool(true)

var_dump($dir->isFile('home/public/src/foo/image.jpg')); // bool(true)

var_dump($dir->isWritable(__DIR__.'/src/foo')); // bool(true)

// Check if directory or file exists.
var_dump($dir->has(__DIR__.'/src/foo')); // bool(true)

var_dump($dir->has(__DIR__.'/src/foo/')); // bool(true)

var_dump($dir->has(__DIR__.'/src/foo/image.jpg')); // bool(true)

// Check if a directory is empty.
var_dump($dir->isEmpty(__DIR__.'/src/foo/')); // bool(false)
```

#### Get files from a directory

[](#get-files-from-a-directory)

```
use Tobento\Service\Filesystem\Dir;
use Tobento\Service\Filesystem\File;

$dir = new Dir();

$dir->setFilesToIgnore(['.DS_Store', '*_notes', 'Thumbs.db', 'folder/subdir/image.png']); // use wildcard * for all

$dir->setFilesToIgnoreExtensions(['htaccess', 'txt']);

$files = $dir->getFiles('home/public/media/path/folder/');

// define a folder path, might be useful for certain use cases.
$files = $dir->getFiles('home/public/media/path/folder/', 'path/folder/');

// only get png and jpeg files.
$files = $dir->getFiles('home/public/media/path/folder/', '', ['png', 'jpeg']);

foreach($files as $file)
{
    var_dump($file instanceof File); // bool(true)
}
```

#### Get folders from a directory

[](#get-folders-from-a-directory)

```
use Tobento\Service\Filesystem\Dir;
use Tobento\Service\Filesystem\Folder;

$dir = new Dir();

$dir->setFoldersToIgnore(['img/firm', 'misc/test', '*_notes']); // use wildcard * for all

// get all with subfolders.
$folders = $dir->getFoldersAll('home/public/media/');

// get only first level folders. Note: $dir->setFoldersToIgnore() has no influence.
$folders = $dir->getFolders('home/public/media/');

foreach($folders as $folder)
{
    var_dump($folder instanceof Folder); // bool(true)

    // Get folder information
    $name = $folder->name();
    $dir = $folder->dir();
    $id = $folder->id();
    $parentId = $folder->parentId();
    $level = $folder->level();
    $folderPath = $folder->folderPath();

    // Manipulate, returns a new instance.
    $folder = $folder->withName('-'.$folder->name());
    $folder = $folder->withFolderPath('bar/foo');
}
```

#### Create or rename a directory

[](#create-or-rename-a-directory)

```
use Tobento\Service\Filesystem\Dir;

$dir = new Dir();

var_dump($dir->create('home/public/media/new/', mode: 0755, recursive: true)); // bool(true)

var_dump($dir->rename('home/public/media/old/', 'new')); // bool(true)
```

#### Copy a directory

[](#copy-a-directory)

This will copy subfolders and all files too.

```
use Tobento\Service\Filesystem\Dir;

$dir = new Dir();

$dir->setFilesToIgnore(['subdir/image.png']); // starting from dir set.

$dir->setFilesToIgnoreExtensions(['txt']);

$dir->setFoldersToIgnore(['sub/foo']); // starting from dir set.

var_dump($dir->copy(dir: 'home/public/media/foo/', destination: 'home/public/media/bar/')); // bool(true)
```

#### Delete directories or file

[](#delete-directories-or-file)

```
use Tobento\Service\Filesystem\Dir;

$dir = new Dir();

// Careful: this will delete all subfolders and all files.

var_dump($dir->delete('www/public/media/dir_to_delete/')); // bool(true)

// This method will delete files too.
var_dump($dir->delete('www/public/media/file_to_delete.jpg')); // bool(true)
```

#### A note on ignoring files

[](#a-note-on-ignoring-files)

> ⚠️ **If the given format is not added by the addFormat() method, see File Formats below for detail, files will only be checked by its extension and not by its mime type.**

```
use Tobento\Service\Filesystem\Dir;

$dir = new Dir(withDefaultFormats: false);

// would only check txt files by its extension as withDefaultFormats is set to false.
$dir->setFilesToIgnoreExtensions(['txt']);
```

The formats added by default are:

```
trait FileFormats
{
    protected function addDefaultFormats(): void
    {
        // Add default formats.
        $this->addFormat('html', 'text/html');
        $this->addFormat('html', 'application/xhtml+xml');
        $this->addFormat('txt', 'text/plain');
        $this->addFormat('json', 'application/json');
        $this->addFormat('json', 'application/x-json');
        $this->addFormat('js', 'application/javascript');
        $this->addFormat('js', 'application/x-javascript');
        $this->addFormat('js', 'text/javascript');
        $this->addFormat('css', 'text/css');
        $this->addFormat('php', 'application/x-httpd-php');
        $this->addFormat('php', 'text/x-php');
        $this->addFormat('phtml', 'application/x-httpd-php');
        $this->addFormat('xml', 'text/xml');
        $this->addFormat('xml', 'application/xml');
        $this->addFormat('xml', 'application/x-xml');
        $this->addFormat('rdf', 'application/rdf+xml');
        $this->addFormat('atom', 'application/atom+xml');
        $this->addFormat('rss', 'application/rss+xml');
        $this->addFormat('form', 'application/x-www-form-urlencoded');
        $this->addFormat('pdf', 'application/pdf');
        $this->addFormat('jpg', 'image/jpeg');
        $this->addFormat('jpeg', 'image/jpeg');
        $this->addFormat('jpe', 'image/jpeg');
        $this->addFormat('png', 'image/png');
        $this->addFormat('gif', 'image/gif');
        $this->addFormat('webp', 'image/webp');
        $this->addFormat('tif', 'image/tiff');
        $this->addFormat('svg', 'image/svg+xml');
        $this->addFormat('psd', 'image/vnd.adobe.photoshop');
        $this->addFormat('bmp', 'image/bmp');
        $this->addFormat('ico', 'image/vnd.microsoft.icon');
        $this->addFormat('ai', 'application/postscript');
        $this->addFormat('eps', 'application/postscript');
        $this->addFormat('zip', 'application/zip');
        $this->addFormat('csv', 'text/csv');
        $this->addFormat('csv', 'text/x-csv');
        $this->addFormat('csv', 'text/plain');
        $this->addFormat('csv', 'application/csv');
        $this->addFormat('csv', 'application/x-csv');
        $this->addFormat('csv', 'application/vnd.ms-excel');
    }
}
```

File Formats
------------

[](#file-formats)

The FileFormatsInterface has the following methods:

#### Add a format

[](#add-a-format)

```
use Tobento\Service\Filesystem\Dir;
use Tobento\Service\Filesystem\FileFormatsInterface;

$dir = new Dir();
var_dump($dir instanceof FileFormatsInterface); // bool(true)

$dir->addFormat(format: 'jpeg', mimeType: 'image/jpeg');
$dir->addFormat('jpg', 'image/jpeg');
$dir->addFormat('csv', 'text/csv');
$dir->addFormat('csv', 'text/plain');
```

#### Merge formats

[](#merge-formats)

```
use Tobento\Service\Filesystem\Dir;

$dir = new Dir();
$dir->mergeFormats([
    'jpeg' => ['image/jpeg'],
    'csv' => ['text/x-csv'],
    'gif' => ['image/gif'],
]);
```

#### Get Format

[](#get-format)

```
use Tobento\Service\Filesystem\Dir;

$dir = new Dir(withDefaultFormats: false);

$dir->addFormat('jpeg', 'image/jpeg');
$dir->addFormat('jpg', 'image/jpeg');

// Returns first found format or null if not found any.
var_dump($dir->getFormat(mimeType: 'image/jpeg'));
// string(4) "jpeg"
```

#### Get Formats

[](#get-formats)

```
use Tobento\Service\Filesystem\Dir;

$dir = new Dir(withDefaultFormats: false);

$dir->addFormat('jpeg', 'image/jpeg');
$dir->addFormat('jpg', 'image/jpeg');
$dir->addFormat('csv', 'text/csv');
$dir->addFormat('csv', 'text/plain');

$formats = $dir->getFormats();

/*
Array
(
    [jpeg] => Array
        (
            [0] => image/jpeg
        )

    [jpg] => Array
        (
            [0] => image/jpeg
        )

    [csv] => Array
        (
            [0] => text/csv
            [1] => text/plain
        )

)
*/
```

#### Get Mime Type

[](#get-mime-type)

```
use Tobento\Service\Filesystem\Dir;

$dir = new Dir(withDefaultFormats: false);

$dir->addFormat('jpeg', 'image/jpeg');
$dir->addFormat('jpg', 'image/jpeg');

// Returns first found mime type or null if not found any.
var_dump($dir->getMimeType(format: 'jpg'));
// string(10) "image/jpeg"

// Return part one
var_dump($dir->getMimeType('jpg', part: 1));
string(5) "image"

// Return part two
var_dump($dir->getMimeType('jpg', 2));
string(4) "jpeg"
```

#### Get Mime Types

[](#get-mime-types)

```
use Tobento\Service\Filesystem\Dir;

$dir = new Dir(withDefaultFormats: false);

$dir->addFormat('jpeg', 'image/jpeg');
$dir->addFormat('csv', 'text/csv');

$mimeTypes = $dir->getMimeTypes(formats: ['jpeg', 'csv']);

/*
Array
(
    [0] => image/jpeg
    [1] => text/csv
)
*/

// part one only
$mimeTypes = $dir->getMimeTypes(formats: ['jpeg', 'csv'], part: 1);

/*
Array
(
    [0] => image
    [1] => text
)
*/

// part two only
$mimeTypes = $dir->getMimeTypes(formats: ['jpeg', 'csv'], part: 2);

/*
Array
(
    [0] => jpeg
    [1] => csv
)
*/
```

Credits
=======

[](#credits)

- [Tobias Strub](https://www.tobento.ch)
- [All Contributors](../../contributors)

###  Health Score

46

—

FairBetter than 93% of packages

Maintenance62

Regular maintenance activity

Popularity17

Limited adoption so far

Community20

Small or concentrated contributor base

Maturity75

Established project with proven stability

 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 ~173 days

Recently: every ~259 days

Total

10

Last Release

237d ago

Major Versions

1.x-dev → 2.02025-09-23

PHP version history (2 changes)1.0.0PHP >=8.0

2.0PHP >=8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/055d6a1b5c2384bb179c75ab0b55914231d898fdc4dffeb30770f81200e52206?d=identicon)[TOBENTOch](/maintainers/TOBENTOch)

---

Top Contributors

[![tobento-ch](https://avatars.githubusercontent.com/u/16684832?v=4)](https://github.com/tobento-ch "tobento-ch (28 commits)")

---

Tags

filesystempackagedirectorytobento

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Type Coverage Yes

### Embed Badge

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

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

PHPackages © 2026

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