PHPackages                             jackardios/laravel-file-cache - 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. [Caching](/categories/caching)
4. /
5. jackardios/laravel-file-cache

ActiveLibrary[Caching](/categories/caching)

jackardios/laravel-file-cache
=============================

Fetch and cache files from local filesystem, cloud storage or public webservers in Laravel

v4.0.1(5mo ago)0402MITPHPPHP ^8.1CI failing

Since Oct 28Pushed 2mo agoCompare

[ Source](https://github.com/Jackardios/laravel-file-cache)[ Packagist](https://packagist.org/packages/jackardios/laravel-file-cache)[ RSS](/packages/jackardios-laravel-file-cache/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (6)Dependencies (10)Versions (9)Used By (0)

File Cache
==========

[](#file-cache)

Fetch and cache files from local filesystem, cloud storage or public webservers in Laravel.

The file cache is specifically designed for use in concurrent processing with multiple parallel queue workers.

[![Tests](https://github.com/jackardios/laravel-file-cache/actions/workflows/tests.yml/badge.svg)](https://github.com/jackardios/laravel-file-cache/actions/workflows/tests.yml)

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

[](#requirements)

- PHP ^8.1
- Laravel ^10.0 || ^11.0 || ^12.0

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

[](#installation)

```
composer require jackardios/laravel-file-cache

```

### Laravel

[](#laravel)

The service provider and `FileCache` facade are auto-discovered by Laravel.

### Publishing Configuration

[](#publishing-configuration)

```
php artisan vendor:publish --provider="Jackardios\FileCache\FileCacheServiceProvider" --tag="config"
```

Usage
-----

[](#usage)

Take a look at the [`FileCache`](src/Contracts/FileCache.php) contract to see the public API of the file cache. Example:

```
use FileCache;
use Jackardios\FileCache\GenericFile;

// Implements Jackardios\FileCache\Contracts\File.
$file = new GenericFile('https://example.com/images/image.jpg');

FileCache::get($file, function ($file, $path) {
    // do stuff
});
```

If the file URL specifies another protocol than `http` or `https` (e.g. `mydisk://images/image.jpg`), the file cache looks for the file in the appropriate storage disk configured at `filesystems.disks`. You can not use a local file path as URL (e.g. `/vol/images/image.jpg`). Instead, configure a storage disk with the `local` driver.

### Batch Processing

[](#batch-processing)

Process multiple files at once while maintaining locks to prevent pruning during processing:

```
use FileCache;
use Jackardios\FileCache\GenericFile;

$files = [
    new GenericFile('https://example.com/image1.jpg'),
    new GenericFile('https://example.com/image2.jpg'),
];

FileCache::batch($files, function ($files, $paths) {
    // $paths contains cached file paths in the same order as $files
    foreach ($paths as $path) {
        // process each file
    }
});
```

### One-time Files

[](#one-time-files)

Use `getOnce()` or `batchOnce()` to automatically delete cached files after processing:

```
FileCache::getOnce($file, function ($file, $path) {
    // File will be deleted after callback completes
});
```

### Check File Existence

[](#check-file-existence)

```
$exists = FileCache::exists($file);
```

For remote files, `exists()` uses the HTTP retry settings (`http_retries`, `http_retry_delay`). HTTP response statuses outside 2xx are treated as "not exists" (`false`), including when a custom Guzzle client uses `http_errors=true`. It may throw network/storage exceptions (for example connection errors or unknown disks).

Configuration
-------------

[](#configuration)

The file cache comes with a sensible default configuration. You can override it in the `file-cache` namespace or with environment variables.

### file-cache.max\_file\_size

[](#file-cachemax_file_size)

Default: `-1` (any size) Environment: `FILE_CACHE_MAX_FILE_SIZE`

Maximum allowed size of a cached file in bytes. Set to `-1` to allow any size.

### file-cache.max\_age

[](#file-cachemax_age)

Default: `60`Environment: `FILE_CACHE_MAX_AGE`

Maximum age in minutes of a file in the cache. Older files are pruned.

### file-cache.max\_size

[](#file-cachemax_size)

Default: `1E+9` (1 GB) Environment: `FILE_CACHE_MAX_SIZE`

Maximum size (soft limit) of the file cache in bytes. If the cache exceeds this size, old files are pruned.

### file-cache.path

[](#file-cachepath)

Default: `'storage/framework/cache/files'`

Directory to use for the file cache.

### file-cache.timeout

[](#file-cachetimeout)

Default: `-1` (indefinitely) Environment: `FILE_CACHE_TIMEOUT`

Total connection timeout when reading remote files in seconds. If loading the file takes longer than this, it will fail. Set to `-1` to wait indefinitely.

### file-cache.connect\_timeout

[](#file-cacheconnect_timeout)

Default: `30` (30 seconds) Environment: `FILE_CACHE_CONNECT_TIMEOUT`

Timeout to initiate a connection to load a remote file in seconds. If it takes longer, it will fail. Set to `-1` to wait indefinitely.

### file-cache.read\_timeout

[](#file-cacheread_timeout)

Default: `30` (30 seconds) Environment: `FILE_CACHE_READ_TIMEOUT`

Timeout for reading a stream of a remote file in seconds. If it takes longer, it will fail. Set to `-1` to wait indefinitely.

### file-cache.prune\_interval

[](#file-cacheprune_interval)

Default `'*/5 * * * *'` (every five minutes)

Interval for the scheduled task to prune the file cache.

### file-cache.prune\_timeout

[](#file-cacheprune_timeout)

Default: `300` (5 minutes) Environment: `FILE_CACHE_PRUNE_TIMEOUT`

Timeout for the prune operation in seconds. If pruning takes longer than this, it will stop early. Set to `-1` for no timeout.

### file-cache.mime\_types

[](#file-cachemime_types)

Default: `[]` (allow all types)

Array of allowed MIME types for cached files. Caching of files with other types will fail.

### file-cache.allowed\_hosts

[](#file-cacheallowed_hosts)

Default: `null` (all hosts allowed) Environment: `FILE_CACHE_ALLOWED_HOSTS`

Allowed hosts for remote file fetching. This is a security feature to prevent SSRF (Server-Side Request Forgery) attacks. Set to `null` to allow all hosts, or provide an array of allowed hostnames.

Wildcards (`*`) are supported at the beginning of hostnames:

```
'allowed_hosts' => ['example.com', 'cdn.example.com', '*.trusted-domain.com'],
```

For environment variable, use comma-separated values:

```
FILE_CACHE_ALLOWED_HOSTS=example.com,cdn.example.com,*.trusted-domain.com

```

### file-cache.http\_retries

[](#file-cachehttp_retries)

Default: `0` (no retries) Environment: `FILE_CACHE_HTTP_RETRIES`

Number of retry attempts for failed HTTP requests. Client errors (4xx except 429) are not retried. This applies to both `get()` and `exists()` for remote files.

### file-cache.http\_retry\_delay

[](#file-cachehttp_retry_delay)

Default: `100` (100ms) Environment: `FILE_CACHE_HTTP_RETRY_DELAY`

Delay between HTTP retry attempts in milliseconds.

### file-cache.lifecycle\_lock\_timeout

[](#file-cachelifecycle_lock_timeout)

Default: `30` (seconds) Environment: `FILE_CACHE_LIFECYCLE_LOCK_TIMEOUT`

Timeout to wait for lifecycle lock acquisition in seconds when coordinating `batch()`/`batchOnce()` with `prune()`/`clear()`. Set to `-1` to wait indefinitely.

### file-cache.batch\_chunk\_size

[](#file-cachebatch_chunk_size)

Default: `100`Environment: `FILE_CACHE_BATCH_CHUNK_SIZE`

Maximum number of files to process in a single chunk during `batch()` and `batchOnce()`. Lower values reduce the number of simultaneously opened cached file streams and help avoid file descriptor exhaustion. Set to `-1` for no limit.

### file-cache.lock\_max\_attempts

[](#file-cachelock_max_attempts)

Default: `3`Environment: `FILE_CACHE_LOCK_MAX_ATTEMPTS`

Maximum number of attempts to acquire a lock on a file. Must be at least 1.

### file-cache.lock\_wait\_timeout

[](#file-cachelock_wait_timeout)

Default: `-1` (indefinitely) Environment: `FILE_CACHE_LOCK_WAIT_TIMEOUT`

Timeout to wait for a lock on a file to be released in seconds. Set to `-1` to wait indefinitely.

Clearing
--------

[](#clearing)

The file cache is cleared when you call `php artisan cache:clear`.

Testing
-------

[](#testing)

The `FileCache` facade provides a fake for easy testing. The fake does not actually fetch and store any files, but only executes the callback function with a faked file path.

```
use FileCache;
use Jackardios\FileCache\GenericFile;

FileCache::fake();
$file = new GenericFile('https://example.com/image.jpg');
$path = FileCache::get($file, function ($file, $path) {
    return $path;
});

$this->assertFalse($this->app['files']->exists($path));
```

Exceptions
----------

[](#exceptions)

The following exceptions may be thrown:

- `FileIsTooLargeException` - File exceeds configured `max_file_size`
- `FileLockedException` - File is locked when `throwOnLock` is `true`
- `HostNotAllowedException` - Host is not in the `allowed_hosts` whitelist
- `MimeTypeIsNotAllowedException` - MIME type is not in the `mime_types` whitelist
- `SourceResourceIsInvalidException` - Could not establish a valid stream resource
- `SourceResourceTimedOutException` - Stream read operation timed out
- `FailedToRetrieveFileException` - General file retrieval failure after all retries
- `InvalidConfigurationException` - Invalid configuration values

License
-------

[](#license)

MIT

###  Health Score

43

—

FairBetter than 91% of packages

Maintenance80

Actively maintained with recent releases

Popularity13

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 55.7% 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 ~190 days

Recently: every ~66 days

Total

7

Last Release

154d ago

Major Versions

v1.0.0 → v2.0.02024-01-30

v2.0.1 → v3.0.32025-03-28

v3.0.3 → v4.x-dev2025-12-10

PHP version history (2 changes)v1.0.0PHP ^8.0

v4.x-devPHP ^8.1

### Community

Maintainers

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

---

Top Contributors

[![mzur](https://avatars.githubusercontent.com/u/2457311?v=4)](https://github.com/mzur "mzur (64 commits)")[![Jackardios](https://avatars.githubusercontent.com/u/24757335?v=4)](https://github.com/Jackardios "Jackardios (51 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/jackardios-laravel-file-cache/health.svg)

```
[![Health](https://phpackages.com/badges/jackardios-laravel-file-cache/health.svg)](https://phpackages.com/packages/jackardios-laravel-file-cache)
```

###  Alternatives

[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)[spatie/laravel-backup

A Laravel package to backup your application

6.0k21.8M191](/packages/spatie-laravel-backup)[laravel-zero/framework

The Laravel Zero Framework.

3371.4M369](/packages/laravel-zero-framework)[laravel/dusk

Laravel Dusk provides simple end-to-end testing and browser automation.

1.9k36.7M259](/packages/laravel-dusk)[spatie/laravel-responsecache

Speed up a Laravel application by caching the entire response

2.8k8.2M51](/packages/spatie-laravel-responsecache)[tightenco/jigsaw

Simple static sites with Laravel's Blade.

2.2k438.5k29](/packages/tightenco-jigsaw)

PHPackages © 2026

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