PHPackages                             tourze/psr15-static-file-request-handler - 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. tourze/psr15-static-file-request-handler

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

tourze/psr15-static-file-request-handler
========================================

PSR-15 Static File Request Handler

0.0.1(1y ago)09MITPHPPHP ^8.1CI passing

Since Apr 24Pushed 6mo ago1 watchersCompare

[ Source](https://github.com/tourze/psr15-static-file-request-handler)[ Packagist](https://packagist.org/packages/tourze/psr15-static-file-request-handler)[ RSS](/packages/tourze-psr15-static-file-request-handler/feed)WikiDiscussions master Synced 1mo ago

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

PSR-15 Static File Request Handler
==================================

[](#psr-15-static-file-request-handler)

[English](README.md) | [中文](README.zh-CN.md)

[![Latest Version](https://camo.githubusercontent.com/c527d5d46c1639830b44bb5f51d700c188904f456b2f391ab683cf0a1ec3f57a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f746f75727a652f70737231352d7374617469632d66696c652d726571756573742d68616e646c65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tourze/psr15-static-file-request-handler)[![PHP Version](https://camo.githubusercontent.com/a81f094f1ddfb066c8ed787abe9999cf4c7f21fb0956aa4e21a17b033d7dbf9b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f746f75727a652f70737231352d7374617469632d66696c652d726571756573742d68616e646c65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tourze/psr15-static-file-request-handler)[![License](https://camo.githubusercontent.com/9cabe2ba98d8dae13890170e2af1a57b405edde1abbf24541c034b40cb256e8c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f746f75727a652f7068702d6d6f6e6f7265706f2e7376673f7374796c653d666c61742d737175617265)](LICENSE)[![Build Status](https://camo.githubusercontent.com/22c5dacb2383e626edb7998b1a492a846b05193de6d038eab2e96ee9d75dd0be/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f746f75727a652f70737231352d7374617469632d66696c652d726571756573742d68616e646c65722f6d61737465722e7376673f7374796c653d666c61742d737175617265)](https://travis-ci.org/tourze/psr15-static-file-request-handler)[![Quality Score](https://camo.githubusercontent.com/320fe6d4b21a8f5ded2b212c456bf66f0af3136481d8415e48746451270fd3fc/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f746f75727a652f70737231352d7374617469632d66696c652d726571756573742d68616e646c65722e7376673f7374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/tourze/psr15-static-file-request-handler)[![Total Downloads](https://camo.githubusercontent.com/fbcb7df32bdc3c6c3cb42a32bd3c1ec1889ca5d2552ae9fc0ddb4e0f78fab59a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f746f75727a652f70737231352d7374617469632d66696c652d726571756573742d68616e646c65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tourze/psr15-static-file-request-handler)

A PSR-15 compatible request handler for serving static files efficiently in PHP applications. Supports cache headers, range requests, directory index, and MIME type detection.

Features
--------

[](#features)

- PSR-15 compatible static file request handler
- Supports directory index (index.html, index.htm)
- MIME type auto-detection using league/mime-type-detection
- HTTP cache support (ETag, Last-Modified, 304 Not Modified)
- Range requests (partial content, 206)
- Prevents serving PHP files for security
- Easy integration with any PSR-15 middleware stack

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

[](#installation)

**Install via Composer:**

```
composer require tourze/psr15-static-file-request-handler
```

Dependencies
------------

[](#dependencies)

**Requirements:**

- PHP >= 8.1
- Composer

**Dependencies:**

- `psr/http-message` - PSR-7 HTTP message interfaces
- `psr/http-server-handler` - PSR-15 HTTP handlers
- `league/mime-type-detection` - MIME type detection
- `nyholm/psr7` - PSR-7 implementation
- `symfony/filesystem` - File system operations

Quick Start
-----------

[](#quick-start)

```
use Tourze\PSR15StaticFileRequestHandler\StaticFileRequestHandler;
use Nyholm\Psr7\ServerRequest;

$publicPath = __DIR__ . '/public';
$handler = new StaticFileRequestHandler($publicPath);
$request = new ServerRequest('GET', '/test.txt');
$response = $handler->handle($request);

// Output response body
echo $response->getBody();
```

### Example: Handling Range Requests

[](#example-handling-range-requests)

```
$request = $request->withHeader('Range', 'bytes=0-4');
$response = $handler->handle($request);
// Will return partial content (206) with specified range
```

Documentation
-------------

[](#documentation)

### Public API

[](#public-api)

- **Constructor:** `StaticFileRequestHandler::__construct(string $publicPath, ?Filesystem $filesystem = null)`
- **Handler method:** `handle(ServerRequestInterface $request): ResponseInterface`

### Response Codes

[](#response-codes)

- **200 OK:** File found and served successfully
- **206 Partial Content:** Range request served successfully
- **304 Not Modified:** File not modified (cache hit)
- **404 Not Found:** File does not exist
- **416 Range Not Satisfiable:** Invalid range request
- **500 Internal Server Error:** File read error

### Configuration

[](#configuration)

- `publicPath`: The root directory for static files
- Optionally pass a Symfony Filesystem instance

Advanced Usage
--------------

[](#advanced-usage)

### Custom Filesystem Integration

[](#custom-filesystem-integration)

```
use Symfony\Component\Filesystem\Filesystem;

$filesystem = new Filesystem();
$handler = new StaticFileRequestHandler($publicPath, $filesystem);
```

### Middleware Integration

[](#middleware-integration)

```
use Slim\App;

$app = new App();
$app->add(function ($request, $handler) {
    $staticHandler = new StaticFileRequestHandler(__DIR__ . '/public');
    return $staticHandler->handle($request);
});
```

### Cache Headers

[](#cache-headers)

The handler automatically sets cache headers:

- `ETag` for cache validation
- `Last-Modified` for conditional requests
- `Cache-Control: public, max-age=86400` for browser caching

### Range Request Support

[](#range-request-support)

Supports HTTP range requests for:

- Large file downloads
- Video streaming
- Progressive loading

### Directory Index

[](#directory-index)

Automatically serves index files:

- `index.html` (preferred)
- `index.htm` (fallback)

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

[](#contributing)

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/fooBar`)
3. Commit your changes (`git commit -am 'Add some fooBar'`)
4. Push to the branch (`git push origin feature/fooBar`)
5. Create a new Pull Request

**Coding Style:** PSR-12

**Testing:**

```
composer install
vendor/bin/phpunit
```

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for details.

Changelog
---------

[](#changelog)

See [Releases](https://packagist.org/packages/tourze/psr15-static-file-request-handler#releases) for version history and upgrade notes.

###  Health Score

28

—

LowBetter than 54% of packages

Maintenance63

Regular maintenance activity

Popularity4

Limited adoption so far

Community4

Small or concentrated contributor base

Maturity35

Early-stage or recently created project

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

380d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e354fdb316da535dfa8ba2e9193a473c403b6bc6fb9170778d1dc50e304c6e9d?d=identicon)[tourze](/maintainers/tourze)

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tourze-psr15-static-file-request-handler/health.svg)

```
[![Health](https://phpackages.com/badges/tourze-psr15-static-file-request-handler/health.svg)](https://phpackages.com/packages/tourze-psr15-static-file-request-handler)
```

###  Alternatives

[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[bref/bref

Bref is a framework to write and deploy serverless PHP applications on AWS Lambda.

3.4k9.6M55](/packages/bref-bref)[aimeos/aimeos-base

Aimeos base layer for abstracting from host environments

2.1k134.0k1](/packages/aimeos-aimeos-base)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.2M386](/packages/shopware-core)[jaxon-php/jaxon-core

Jaxon is an open source PHP library for easily creating Ajax web applications

73142.3k25](/packages/jaxon-php-jaxon-core)[tempest/framework

The PHP framework that gets out of your way.

2.1k23.1k9](/packages/tempest-framework)

PHPackages © 2026

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