https://github.com/hichemtab-tech/namecrement-php
A smart php utility that generates unique incremental names, preventing naming collisions by automatically appending incremental suffixes.
https://github.com/hichemtab-tech/namecrement-php
incremental php unique unique-name
Last synced: 4 months ago
JSON representation
A smart php utility that generates unique incremental names, preventing naming collisions by automatically appending incremental suffixes.
- Host: GitHub
- URL: https://github.com/hichemtab-tech/namecrement-php
- Owner: HichemTab-tech
- License: mit
- Created: 2025-04-28T18:35:08.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-09-02T23:52:59.000Z (10 months ago)
- Last Synced: 2025-09-03T00:25:22.020Z (10 months ago)
- Topics: incremental, php, unique, unique-name
- Language: PHP
- Homepage:
- Size: 111 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Namecrement (PHP)
[](https://github.com/HichemTab-tech/Namecrement-php/blob/master/LICENSE)
**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](https://github.com/HichemTab-tech/Namecrement)
* Python: [Namecrement-py](https://github.com/HichemTab-tech/Namecrement-py)
## 📦 Installation
```bash
composer require hichemtab-tech/namecrement-php
```
---
## 🚀 Usage
```php
'], '');
// ➔ 'version'
```
### 🛡 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%)"`.
| Format Example | Result |
|-------------------|---------------------|
| `" (%N%)"` | `file (1)` |
| `-%N%` | `file-1` |
| `_` | `file_` |
| `_%N%_` | `file_1_` |
---
## 📚 API
### `namecrement(string $baseName, array $existingNames): string`
| Parameter | Type | Description |
|------------------|---------------|------------------------------------------------------|
| `baseName` | string | Proposed name to start from |
| `existingNames` | string[] | List of already existing names |
| `suffixFormat` | string | Optional format for suffix (optional) |
| `startingNumber` | `int \| null` | The starting number for incrementing (default: null) |
Returns the next available **unique name**.
---
## 🛠 Examples
```php
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](LICENSE).
---
## 🤝 Contributing
Contributions are welcome!
Please check out the [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.