PHPackages                             indiehd/filename-sanitizer - 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. [Utility & Helpers](/categories/utility)
4. /
5. indiehd/filename-sanitizer

ActiveLibrary[Utility & Helpers](/categories/utility)

indiehd/filename-sanitizer
==========================

A lightweight library for sanitizing strings to be used as filenames.

v0.1.0(7y ago)9188.8k↓21.6%1[1 issues](https://github.com/indiehd/filename-sanitizer/issues)MITPHPPHP >=7.0.0

Since Feb 7Pushed 5y ago4 watchersCompare

[ Source](https://github.com/indiehd/filename-sanitizer)[ Packagist](https://packagist.org/packages/indiehd/filename-sanitizer)[ RSS](/packages/indiehd-filename-sanitizer/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (3)Versions (3)Used By (0)

Filename Sanitizer
==================

[](#filename-sanitizer)

[![Build Status](https://camo.githubusercontent.com/8b60b8d14735a4cc040b8ae0e89ae1427567757b04a5d94608a0292fb1f5c797/68747470733a2f2f7472617669732d63692e6f72672f696e64696568642f66696c656e616d652d73616e6974697a65722e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/indiehd/filename-sanitizer)[![Coverage Status](https://camo.githubusercontent.com/90db4085aa4ec2f3115b6b07557252c7f5fe00080ea174e243bf61210f6f328b/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f696e64696568642f66696c656e616d652d73616e6974697a65722f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/indiehd/filename-sanitizer?branch=master)[![Latest Stable Version](https://camo.githubusercontent.com/869614b6ebb0848763f7598349073a2c31d2c6c743775e57956f9376145aa29a/68747470733a2f2f706f7365722e707567782e6f72672f696e64696568642f66696c656e616d652d73616e6974697a65722f762f737461626c65)](https://packagist.org/packages/indiehd/filename-sanitizer)[![Total Downloads](https://camo.githubusercontent.com/4d3ea2ae0c6756c0ee53cc2d0878d58f9149339f9127f8882ef3671e7a1f0fc1/68747470733a2f2f706f7365722e707567782e6f72672f696e64696568642f66696c656e616d652d73616e6974697a65722f646f776e6c6f616473)](https://packagist.org/packages/indiehd/filename-sanitizer)[![License](https://camo.githubusercontent.com/9ff5d8386c6f6abd2fa338a9a9222b958cad368da95a9a2f45a116c337ee3c03/68747470733a2f2f706f7365722e707567782e6f72672f696e64696568642f66696c656e616d652d73616e6974697a65722f6c6963656e7365)](https://packagist.org/packages/indiehd/filename-sanitizer)

About
-----

[](#about)

This lightweight library provides a means by which to sanitize strings to be used in filenames.

Web applications commonly prompt users to download files with specific names, and these names should adhere to the target operating system's (and attendant filesystem's) naming conventions, or errors may result.

While it's possible to detect the target operating system via browser metadata, there is no practical means by which to detect the target *filesystem*, which is the ultimate arbiter of which file-naming conventions apply.

Conveniently, most browsers perform string replacements to ensure that downloaded files do not violate the target operating system's conventions, but developers cannot rely on this capability alone, because oftentimes they're tasked with naming files that are packed into an archive of some sort, in which case the browser is of no help in this regard. It is only when the archive is unpacked that filesystem errors may result if care is not taken to prevent them.

Given that the application cannot determine reliably which naming conventions the target filesystem will enforce, it is most practical to avoid characters that violate *any* commonly-used filesystem's conventions. This library aims to provide precisely that capability.

Supported Operating Systems and Filesystems
-------------------------------------------

[](#supported-operating-systems-and-filesystems)

The vast majority of end-user systems are running GNU/Linux, Windows, or MacOS, and for those not running one of the aforementioned operating systems, they're running an OS that supports the same filesystems as one of them. For this reason, it is most practical to sanitize only the characters that these operating systems forbid.

Additional Safeguards
---------------------

[](#additional-safeguards)

There are some characters that while not forbidden at the filesystem level could be "risky" to allow in filenames generated within the application. This is true especially for filenames derived from user input, and even more so when the filenames in question have the potential to be processed elsewhere, particularly in code that is outside of the developer's control (third-party extensions, etc.). Care must be taken when unpacking archives that contain certain filenames, for example.

To avoid some of the risks associated with malicious filenames, this library provides optional methods for stripping risky characters, too, as well as PHP code.

Installation
------------

[](#installation)

Simply require the library in your project using Composer:

```
composer require indiehd/filename-sanitizer

```

Usage Examples
--------------

[](#usage-examples)

```
use IndieHD\FilenameSanitizer\FilenameSanitizer;

// Add illegal characters and a null-byte at the end of the name.

$sanitizer = new FilenameSanitizer('On / Off Again: My Journey to Stardom.jpg' . chr(0));

$sanitizer->stripIllegalFilesystemCharacters();

// The resultant string is free of the offending characters.

var_dump($sanitizer->getFilename());

// Output:
// "On  Off Again My Journey to Stardom.jpg"
```

A couple additional methods are available for further sanitizing the filename. These methods may be chained in any order.

```
$sanitizer = new FilenameSanitizer('`rm -rf /`' . chr(0));

$sanitizer->stripPhp()
    ->stripRiskyCharacters()
    ->stripIllegalFilesystemCharacters();

var_dump($sanitizer->getFilename());

// Output:
// "rm -rf "
```

Limitations
-----------

[](#limitations)

This library makes no effort to validate the length of a given filename because a valid length can be extremely difficult to determine, given the many factors involved, especially when dealing with directory structures within archives.

For example, when a file is packed into an archive, its filename length is largely irrelevant because when the archive is unpacked, the length limit includes the present working directory depth, and the archive itself may include any hierarchy of arbitrary length in addition.

Even in consideration of the above, target filesystem limits may vary depending on the API used to access the filesystem.

The bottom-line is that filename length must be considered in the context of the full filesystem path, which is beyond this library's scope and should be implemented given the specific application's business needs.

Versioning
----------

[](#versioning)

This library makes every effort to observe [Semantic Versioning](https://semver.org/).

Contributing
------------

[](#contributing)

Pull-requests are welcome and should observe the guidelines described in the [indieHD Project Documentation](https://docs.indiehd.com/#/home/PULL-REQ).

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance18

Infrequent updates — may be unmaintained

Popularity40

Moderate usage in the ecosystem

Community10

Small or concentrated contributor base

Maturity46

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

Unknown

Total

1

Last Release

2657d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/545562065314419514e3291df42c32ae0eee8063dab76ceee360a7f897d68747?d=identicon)[indieHD](/maintainers/indieHD)

---

Top Contributors

[![cbj4074](https://avatars.githubusercontent.com/u/1236883?v=4)](https://github.com/cbj4074 "cbj4074 (13 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/indiehd-filename-sanitizer/health.svg)

```
[![Health](https://phpackages.com/badges/indiehd-filename-sanitizer/health.svg)](https://phpackages.com/packages/indiehd-filename-sanitizer)
```

###  Alternatives

[tkaratug/tcmb_currency_converter

TCMB Currenct Converter

221.0k](/packages/tkaratug-tcmb-currency-converter)

PHPackages © 2026

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