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

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

unrulynatives/onym
==================

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

v1.0.1(1y ago)03MITPHPPHP ^8.0|^8.2|^8.3|^8.4

Since Mar 4Pushed 1mo agoCompare

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

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

 [![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

37

—

LowBetter than 81% of packages

Maintenance67

Regular maintenance activity

Popularity3

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 85.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 ~0 days

Total

2

Last Release

507d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/6769986?v=4)[Peter](/maintainers/UnrulyNatives)[@UnrulyNatives](https://github.com/UnrulyNatives)

---

Top Contributors

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

---

Tags

blaspsoftonym

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[illuminate/filesystem

The Illuminate Filesystem package.

15265.2M3.3k](/packages/illuminate-filesystem)[blaspsoft/onym

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

12241.1k1](/packages/blaspsoft-onym)

PHPackages © 2026

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