README

Onym - Flexible Filename Generator

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

🚀 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

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

Available Strategies

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

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

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

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

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

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

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

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

Blasp is open-sourced software licensed under the MIT license.

blaspsoft / onym

Maintainers

Details

README

Onym - Flexible Filename Generator

🚀 Features

Installation

Usage

Available Strategies

Random Strategy

UUID Strategy

Timestamp Strategy

Date Strategy

Numbered Strategy

Slug Strategy

Hash Strategy

Global Configuration

License