Налаштовувані референсні номери для ваших моделей за допомогою Referenceable

У багатьох веб-додатках створення унікальних номерів для моделей є поширеною вимогою. Це може бути корисно для електронних платформ, які потребують номерів замовлень, систем рахунків, що вимагають референсних номерів, або будь-якого іншого додатку, де необхідно відслідковувати ідентифікатори. Управління генерацією референсних номерів може швидко стати складним процесом.

Referenceable — це пакет Laravel, створений Мохамедом Саїдом, який допомагає вирішити цю задачу, забезпечуючи можливість генерувати налаштовані референсні номери моделей з гнучкими форматами та широкими можливостями налаштування.

# Основні можливості

• Різноманітні стратегії генерації: Випадкова, послідовна та заснована на шаблонах генерація референсів.
• Висока налаштовуваність: Розширені можливості налаштування префіксів, суфіксів, роздільників та інших параметрів.
• Система шаблонів: Використовуйте заповнювачі, такі як {YEAR}, {MONTH}, {SEQ}, {RANDOM} для складних форматів.
• Послідовне нумерування: Автоматичні послідовності з можливістю скидання (щоденно, щомісяця, щорічно).
• Валідація та перевірка: Вбудована перевірка референсів та контроль унікальності.
• Обробка зіткнень: Автоматичне виявлення та вирішення конфліктів.
• Підтримка мульти-користувачів: Генерація референсів з урахуванням орендарів.
• Команди Artisan: Потужні CLI-інструменти для управління та обслуговування.
• Оптимізація продуктивності: Кешування, пакетна обробка та операції з базою даних.

# Приклад

Припустимо, у нас є система, що дозволяє користувачам подавати запити на статусні листи в університеті. Ми можемо створити міграцію, що міститиме стовпець для зберігання нашого референсного номера:

Schema::create('status_letters', function (Blueprint $table) {
    $table->id();
    $table->string('reference_number')->unique()->index();
    // інші стовпці для наших статусних листів...
    $table->timestamps();
});

Далі створимо модель та вкажемо, як ми хочемо генерувати наші референсні номери:

use MohamedSaid\Referenceable\Traits\HasReference;

class StatusLetter extends Model
{
    use HasReference;

    protected $referenceColumn = 'reference_number';
    protected $referenceStrategy = 'template';
    protected $referenceTemplate = [
        'format' => '{PREFIX}-{YEAR}{MONTH}{SEQ}',
        'sequence_length' => 4,
    ];
    protected $referencePrefix = 'STL';
    // Генерує: STL-2025090001, STL-2025090002...
}

Замість стратегії template можна також використовувати стратегію random:

protected $referenceStrategy = 'random';
protected $referencePrefix = 'STL';
protected $referenceLength = 6;
protected $referenceCase = 'upper';

// Генерує: STL-A12BC3

Або використати стратегію sequential:

protected $referenceStrategy = 'sequential';
protected $referencePrefix = 'STL';
protected $referenceSequential = [
    'start' => 1000,
    'min_digits' => 4,
    'reset_frequency' => 'monthly', // ніколи, щоденно, щомісяця, щорічно
];

// Генерує: STL-001000, STL-001001, STL-001002...

Налаштування референсів також можна виконувати глобально у config/referenceable.php, без прив'язки до кожної моделі.

Referenceable пропонує численні методи та області видимості моделей. Ось кілька з них:

// Ручна генерація без збереження
$reference = $statusLetter->generateReference();

// Перевірка наявності референсу в моделі
if ($statusLetter->hasReference()) {
    echo "Номер референсу: " . $statusLetter->reference;
}

// Знайти елемент за його референсним номером
$statusLetter = StatusLetter::findByReference('STL-2025090001');

// Знайти референси, що починаються з префікса
$lettersThisMonth = StatusLetter::referenceStartsWith('STL-202509')->get();

Забудьте про плутанину з генерацією референсних номерів у Laravel — пакет Referenceable надає професійні номери замовлень, ідентифікатори рахунків та коди відстеження всього за кілька рядків налаштувань.

Спробуйте цей пакет, встановивши його через Composer та виконавши команду установки:

composer require eg-mohamed/referenceable
php artisan referenceable:install

Дізнайтеся більше про цей пакет і перегляньте вихідний код на GitHub.