PHPackages                             blaspsoft/onym - 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. blaspsoft/onym

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

blaspsoft/onym
==============

Onym is a lightweight Laravel package designed to generate unique, structured, and meaningful filenames effortlessly.

v1.0.1(1y ago)12231.5k—1.3%5[1 PRs](https://github.com/Blaspsoft/onym/pulls)1MITPHPPHP ^8.0|^8.2|^8.3|^8.4CI passing

Since Mar 4Pushed 8mo ago2 watchersCompare

[ Source](https://github.com/Blaspsoft/onym)[ Packagist](https://packagist.org/packages/blaspsoft/onym)[ Docs](https://github.com/blaspsoft/onym)[ RSS](/packages/blaspsoft-onym/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (3)Versions (4)Used By (1)

 [![Onym Icon](./.github/assets/icon.png)](./.github/assets/icon.png)

 [![GitHub Workflow Status (main)](https://github.com/Blaspsoft/onym/actions/workflows/main.yml/badge.svg)](https://github.com/Blaspsoft/blasp/actions/workflows/main.yml) [![Total Downloads](https://camo.githubusercontent.com/17889d1e5d72d90fa18213f2aac88eefd43bb7dd0b9cc1d1220a3cd8e03e081e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f626c617370736f66742f6f6e796d)](https://packagist.org/packages/blaspsoft/onym) [![Latest Version](https://camo.githubusercontent.com/4b6dad5735d81078f4a8a420c9a7b0a2e26ae0b0ab0cdc707790fa9d94acf362/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f626c617370736f66742f6f6e796d)](https://packagist.org/packages/blaspsoft/onym) [![License](https://camo.githubusercontent.com/efe275a5f516d1fb42aea0edfae680c8e2ab7555fdbb97a50fee275aca764514/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f626c617370736f66742f6f6e796d)](https://packagist.org/packages/blaspsoft/onym)

Onym - Flexible Filename Generator
==================================

[](#onym---flexible-filename-generator)

A flexible Laravel package for generating filenames using various strategies and options.

🚀 Features
----------

[](#-features)

- ✅ **Flexible Filename Generation** – Generate filenames dynamically using various strategies.
- 🎲 **Multiple Strategies** – Supports `random`, `uuid`, `timestamp`, `date`, `numbered`, `slug`, and `hash`.
- 🔧 **Customizable Output** – Specify filename, extension, and additional formatting options.
- 🎯 **Laravel-Friendly** – Designed to work seamlessly with Laravel's filesystem and configuration.
- 📂 **Human-Readable & Unique Names** – Ensures filenames are structured, collision-free, and easy to understand.
- ⚙️ **Configurable Defaults** – Define global settings in `config/onym.php` for consistency across your application.
- 🔌 **Extensible & Developer-Friendly** – Easily add custom filename strategies or modify existing ones.

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

[](#installation)

You can install the package via composer:

```
composer require blaspsoft/onym
```

You can publish the config file with:

```
php artisan vendor:publish --tag="onym-config"
```

Usage
-----

[](#usage)

### Available Strategies

[](#available-strategies)

### Random Strategy

[](#random-strategy)

Generates a random string of characters for the filename.

**Options:**

- `length` (int): The length of the random string
    - Default: 16
    - Example: `['length' => 8]` generates "a1b2c3d4.txt"
- `prefix` (string): String to prepend to the filename
    - Default: ''
    - Example: `['prefix' => 'temp_']` generates "temp\_a1b2c3d4.txt"
- `suffix` (string): String to append before the extension
    - Default: ''
    - Example: `['suffix' => '_draft']` generates "a1b2c3d4\_draft.txt"

```
use Blaspsoft\Onym\Facades\Onym;

// Generate an 8-character random filename with prefix and suffix
Onym::make(strategy: 'random', options: [
    'length' => 8,
    'prefix' => 'temp_',
    'suffix' => '_draft'
]);
// Result: "temp_a1b2c3d4_draft.txt"

// You can also use the random method directly
Onym::random(string $extension, ?array $options = [])
```

### UUID Strategy

[](#uuid-strategy)

Generates a UUID v4 (universally unique identifier) for the filename.

**Options:**

- `prefix` (string): String to prepend to the filename
    - Default: ''
    - Example: `['prefix' => 'id_']` generates "id\_123e4567-e89b-12d3-a456-426614174000.txt"
- `suffix` (string): String to append before the extension
    - Default: ''
    - Example: `['suffix' => '_backup']` generates "123e4567-e89b-12d3-a456-426614174000\_backup.txt"

```
use Blaspsoft\Onym\Facades\Onym;

// Generate a UUID filename with prefix and suffix
Onym::make(strategy: 'uuid', options: [
    'prefix' => 'id_',
    'suffix' => '_backup'
]);
// Result: "id_123e4567-e89b-12d3-a456-426614174000_backup.txt"

// You can also use the uuid method directly
Onym::uuid(string $extension, ?array $options = [])
```

### Timestamp Strategy

[](#timestamp-strategy)

Adds a timestamp to the filename using PHP's DateTime formatting.

**Options:**

- `format` (string): PHP DateTime format string
    - Default: 'Y-m-d\_H-i-s'
    - Common formats:
        - `'Y-m-d_H-i-s'` → "2024-03-15\_14-30-00"
        - `'YmdHis'` → "20240315143000"
        - `'U'` → Unix timestamp (e.g., "1710506400")
- `prefix` (string): String to prepend to the filename
    - Default: ''
    - Example: `['prefix' => 'log_']`
- `suffix` (string): String to append before the extension
    - Default: ''
    - Example: `['suffix' => '_archive']`

```
use Blaspsoft\Onym\Facades\Onym;

// Using timestamp with prefix and suffix
Onym::make('document', 'pdf', 'timestamp', [
    'format' => 'Y-m-d_H-i-s',
    'prefix' => 'log_',
    'suffix' => '_archive'
]);
// Result: "log_2024-03-15_14-30-00_document_archive.pdf"

// You can also use the timestamp method directly
Onym::timestamp(string $defaultFilename, string $extension, ?array $options = [])
```

### Date Strategy

[](#date-strategy)

Similar to timestamp but focused on date-only formats.

**Options:**

- `format` (string): PHP DateTime format string
    - Default: 'Y-m-d'
    - Common formats:
        - `'Y-m-d'` → "2024-03-15"
        - `'Ymd'` → "20240315"
        - `'Y/m/d'` → "2024/03/15"
- `prefix` (string): String to prepend to the filename
    - Default: ''
    - Example: `['prefix' => 'dated_']`
- `suffix` (string): String to append before the extension
    - Default: ''
    - Example: `['suffix' => '_version']`

```
use Blaspsoft\Onym\Facades\Onym;

// Using date with prefix and suffix
Onym::make('document', 'pdf', 'date', [
    'format' => 'Y-m-d',
    'prefix' => 'dated_',
    'suffix' => '_version'
]);
// Result: "dated_2024-03-15_document_version.pdf"

// You can also use the date method directly
Onym::date(string $defaultFilename, string $extension, ?array $options = [])
```

### Numbered Strategy

[](#numbered-strategy)

Adds a number to the filename.

**Options:**

- `number` (int): The number to append to the filename
    - Default: 1
    - Example: `['number' => 5]`
- `prefix` (string): String to prepend to the filename
    - Default: ''
    - Example: `['prefix' => 'rev_']`
- `suffix` (string): String to append before the extension
    - Default: ''
    - Example: `['suffix' => '_final']`

```
use Blaspsoft\Onym\Facades\Onym;

// Adding numbers with prefix and suffix
Onym::make('document', 'pdf', 'numbered', [
    'number' => 5,
    'prefix' => 'rev_',
    'suffix' => '_final'
]);
// Result: "rev_document_5_final.pdf"

// You can also use the numbered method directly
Onym::numbered(string $defaultFilename, string $extension, ?array $options = [])
```

### Slug Strategy

[](#slug-strategy)

Converts the filename to a URL-friendly slug.

**Options:**

- `prefix` (string): String to prepend to the filename
    - Default: ''
    - Example: `['prefix' => 'post_']`
- `suffix` (string): String to append before the extension
    - Default: ''
    - Example: `['suffix' => '_draft']`

```
use Blaspsoft\Onym\Facades\Onym;

// Converting strings to slugs with prefix and suffix
Onym::make('My Document Name', 'pdf', 'slug', [
    'prefix' => 'post_',
    'suffix' => '_draft'
]);
// Result: "post_my-document-name_draft.pdf"

// You can also use the slug method directly
Onym::slug(string $defaultFilename, string $extension, ?array $options = [])
```

### Hash Strategy

[](#hash-strategy)

Generates a hash of the filename using various algorithms.

**Options:**

- `algorithm` (string): The hashing algorithm to use
    - Default: 'md5'
    - Available algorithms:
        - 'md5' (32 characters)
        - 'sha1' (40 characters)
        - 'sha256' (64 characters)
        - Any algorithm supported by PHP's `hash()` function
- `prefix` (string): String to prepend to the filename
    - Default: ''
    - Example: `['prefix' => 'hash_']`
- `suffix` (string): String to append before the extension
    - Default: ''
    - Example: `['suffix' => '_checksum']`

```
use Blaspsoft\Onym\Facades\Onym;

// Using hash with prefix and suffix
Onym::make('document', 'pdf', 'hash', [
    'algorithm' => 'md5',
    'prefix' => 'hash_',
    'suffix' => '_checksum'
]);
// Result: "hash_86985e105f79b95d6bc918fb45ec7727_checksum.pdf"

// You can also use the hash method directly
Onym::hash(string $defaultFilename, string $extension, ?array $options = [])
```

Global Configuration
--------------------

[](#global-configuration)

You can set default values for all strategies in your `config/onym.php` file:

```
return [
    // Default filename when none is provided
    'default_filename' => 'file',

    // Default extension when none is provided
    'default_extension' => 'txt',

    // Default strategy when none is specified
    'strategy' => 'random',

    // Default options for all strategies
    'options' => [

        'random' => [
            'length' => 16,
            'prefix' => '',
            'suffix' => '',
        ],

        'timestamp' => [
            'format' => 'Y-m-d_H-i-s',
            'prefix' => '',
            'suffix' => '',
        ],

        'date' => [
            'format' => 'Y-m-d',
            'prefix' => '',
            'suffix' => '',
        ],

        'numbered' => [
            'number' => 1,
            'separator' => '_',
            'prefix' => '',
            'suffix' => '',
        ],

        'hash' => [
            'algorithm' => 'md5',
            'length' => 16,
            'prefix' => '',
            'suffix' => '',
        ],
    ],
];
```

These defaults can be overridden on a per-call basis using the `options` parameter in the `make()` and in all strategy methods.

License
-------

[](#license)

Blasp is open-sourced software licensed under the [MIT license](LICENSE).

###  Health Score

46

—

FairBetter than 93% of packages

Maintenance53

Moderate activity, may be stable

Popularity44

Moderate usage in the ecosystem

Community13

Small or concentrated contributor base

Maturity57

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

Total

2

Last Release

440d ago

### Community

Maintainers

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

---

Top Contributors

[![deemonic](https://avatars.githubusercontent.com/u/25927364?v=4)](https://github.com/deemonic "deemonic (12 commits)")

---

Tags

file-managementfilename-conversionfilenamesgeneratorhashlaravellaravel-frameworklaravel-packagephprandomslugtimestampuuidblaspsoftonym

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/blaspsoft-onym/health.svg)

```
[![Health](https://phpackages.com/badges/blaspsoft-onym/health.svg)](https://phpackages.com/packages/blaspsoft-onym)
```

###  Alternatives

[aws/aws-sdk-php-laravel

A simple Laravel 9/10/11/12/13 service provider for including the AWS SDK for PHP.

1.7k35.6M75](/packages/aws-aws-sdk-php-laravel)[illuminate/filesystem

The Illuminate Filesystem package.

15161.6M2.6k](/packages/illuminate-filesystem)[stechstudio/laravel-zipstream

A fast and simple streaming zip file downloader for Laravel.

4633.7M3](/packages/stechstudio-laravel-zipstream)[spatie/laravel-google-cloud-storage

Google Cloud Storage filesystem driver for Laravel

2408.9M13](/packages/spatie-laravel-google-cloud-storage)[azure-oss/storage-blob-laravel

Azure Storage Blob filesystem driver for Laravel

63582.2k1](/packages/azure-oss-storage-blob-laravel)[spatie/laravel-backup-server

Backup multiple applications

17016.7k1](/packages/spatie-laravel-backup-server)

PHPackages © 2026

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