PHPackages                             gearbox-solutions/has-one-file - 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. gearbox-solutions/has-one-file

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

gearbox-solutions/has-one-file
==============================

Adds HasOneFile trait for easy file management for Laravel models

1.2(3mo ago)115791MITPHP

Since Jan 8Pushed 3mo ago2 watchersCompare

[ Source](https://github.com/gearbox-solutions/has-one-file)[ Packagist](https://packagist.org/packages/gearbox-solutions/has-one-file)[ RSS](/packages/gearbox-solutions-has-one-file/feed)WikiDiscussions main Synced today

READMEChangelog (4)Dependencies (8)Versions (5)Used By (0)

HasOneFile
==========

[](#hasonefile)

A HasOneFile trait for easy file management for Laravel models.

Introduction
------------

[](#introduction)

When working with files in Laravel apps, it is common to have a model with a single file associated with it. An example of this might be a "Documents" model, where a record is created for each document uploaded by a user. This package provides a trait that can be added to a model to make it easy to manage files associated with that model.

This provides a few benefits:

- Adds a few helper methods to the model to make it easier to work with files.
- Files are stored in a consistent location
- Files are automatically deleted from storage when the model is deleted as part of a lifecycle hook.

Files are stored in a location based on the model's table name and the model's primary key so that there are no conflicts with other files in the same table.

Example:

- A model with a table name of `documents` and a primary key of `125` will have its file stored in a directory called `documents/125/`.

When saving or deleting a file, the file name is stored in the model and the model is saved to make sure the file name is stored in the database without having to manually save the model. This is done by default, but can be skipped by passing an additional `false` argument to the `storeFile` and `deleteFile` methods.

Here are a few quick examples of how to use the trait:

```
// store a file related to a model
$document->storeFile($file);
// store a file related to a model without immediately saving the model
$document->storeFile($file, false);

// delete a previously stored file from a model
$document->deleteFile();
// delete a previously stored file from a model without immediately saving the model
$document->deleteFile(false);

// check if a file exists for a model
$document->fileExists();

// get the URL for a file from a model
// this can be nice to append for a link to the file
$document->file_url;

// get the contents of a file from a model
$document->getFile();

// get the storage path of a file from a model
$document->getFilePath();

// get the storage directory of a file from a model
$document->getStorageDirectory();

// get the storage disk of a file from a model
$document->getFileStorageDisk();
```

Installation and setup
----------------------

[](#installation-and-setup)

Summary:

[1. Install or copy the package](#1-install-or-copy-the-package)

[2. Add the trait to your model](#2-add-the-trait-to-your-model-to-enable-file-management-for-that-model)

[3. Add a migration to store the file path in the database](#3-add-a-migration-to-store-the-file-path-in-the-database)

### 1. Install or copy the package

[](#1-install-or-copy-the-package)

```
composer require gearbox-solutions/has-one-file
```

Alternatively, this package is really just a single file! You can copy the `HasOneFile.php` file to your project, change the namespace from `GearboxSolutions\HasOneFile\Traits` to your own namespace, and add it to your model.

### 2. Add the trait to your model to enable file management for that model.

[](#2-add-the-trait-to-your-model-to-enable-file-management-for-that-model)

```
use GearboxSolutions\HasOneFile\Traits\HasOneFile;
...
...

class Document extends Model
{
    use HasOneFile;
```

### 3. Add a migration to store the file path in the database.

[](#3-add-a-migration-to-store-the-file-path-in-the-database)

The HasOneFile trait will store the name of the file associated with the model in a column in your database. The default column name used by the trait is `file_path`. You can change this by setting a `protected $fileNameField` property in your model.

Example:

```
Schema::table('documents', function (Blueprint $table) {
    $table->string('file_name')->nullable();
});
```

### Configuring the storage disk

[](#configuring-the-storage-disk)

The default storage disk used by the trait is the default disk configured in your `config/filesystems.php` file. You can override this by setting the `fileStorageDisk` property in your model.

```
class Document extends Model
{
    use HasOneFile;

    protected $fileStorageDisk = 's3';
}
```

### Configuring the file name field

[](#configuring-the-file-name-field)

The default file name field used by the trait is `file_name`. You can override this by setting the `fileNameField` property in your model.

```
class Document extends Model
{
    use HasOneFile;

    protected $fileNameField = 'document_name';
}
```

Testing
-------

[](#testing)

Tests are run using [Testbench](https://github.com/orchestral/testbench) and PHPUnit.

To run the tests, you can use the following command:

```
./vendor/bin/phpunit
```

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance80

Actively maintained with recent releases

Popularity24

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity42

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

Total

4

Last Release

104d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/292ec8da211e962a93e5c89317774dc1c2c485f982e201e2be9dd445434db53b?d=identicon)[Smef](/maintainers/Smef)

---

Top Contributors

[![Smef](https://avatars.githubusercontent.com/u/4460358?v=4)](https://github.com/Smef "Smef (17 commits)")

###  Code Quality

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/gearbox-solutions-has-one-file/health.svg)

```
[![Health](https://phpackages.com/badges/gearbox-solutions-has-one-file/health.svg)](https://phpackages.com/packages/gearbox-solutions-has-one-file)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[larastan/larastan

Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel

6.5k55.4M8.5k](/packages/larastan-larastan)[mike-bronner/laravel-model-caching

Automatic caching for Eloquent models.

2.4k91.9k1](/packages/mike-bronner-laravel-model-caching)[api-platform/laravel

API Platform support for Laravel

58171.8k14](/packages/api-platform-laravel)[pressbooks/pressbooks

Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS.

45444.2k1](/packages/pressbooks-pressbooks)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5022.0k](/packages/simplestats-io-laravel-client)

PHPackages © 2026

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