README

Smart unique name generator for PHP
Automatically generates a unique name by incrementing it if needed — just like "file" → "file (1)" → "file (2)" and so on.

✨ Features

• Generate unique names based on existing ones
• Smart gap detection (fills missing indexes first)
• Lightweight, dependency-free
• Perfect for filenames, labels, IDs, and more

📦 Also Available

• JavaScript: Namecrement
• Python: Namecrement-py

📦 Installation

composer require hichemtab-tech/namecrement-php

🚀 Usage

<?php

use HichemTabTech\Namecrement\Namecrement;

$existing = ['file', 'file (1)', 'file (2)'];
$newName = Namecrement::namecrement('file', $existing);

echo $newName; 
// Outputs: "file (3)"

🧠 Advanced Usage

You can customize the suffix format using the %N% placeholder to define how the number is added:

Namecrement::namecrement('file', ['file', 'file -1-', 'file -2-'], ' -%N%-');
// ➔ 'file -3-'

Namecrement::namecrement('version', ['version', 'version<v1>'], '<v%N%>');
// ➔ 'version<v2>'

🛡 Suffix Format Rules

• The suffixFormat must include %N%, or an InvalidArgumentException will be thrown.
• %N% will be replaced by the next available number.
• Default format is " (%N%)".

📚 API

namecrement(string $baseName, array $existingNames): string

Returns the next available unique name.

🛠 Examples

Namecrement::namecrement('report', ['report', 'report (1)']);
// ➔ 'report (2)'

Namecrement::namecrement('image', ['photo', 'image', 'image (1)', 'image (2)']);
// ➔ 'image (3)'

Namecrement::namecrement('new', []);
// ➔ 'new'
Namecrement::namecrement('file', ['file', 'file (1)', 'file (2)'], ' -%N%-');
// ➔ 'file -1-'

Namecrement::namecrement('file', [], startingNumber: 5);
// → 'file (5)'

📄 License

This project is open-source and available under the MIT license.

🤝 Contributing

Contributions are welcome!
Please check out the CONTRIBUTING.md for guidelines.