ferdy/employeeidgenerator

Lightweight PHP library specifically engineered to help developers generate employee ID formats that are automatic, unique, and consistent.

1.0.0 2026-01-28 07:18 UTC

MIT

• Ferdy Setia

README

Lightweight PHP library specifically engineered to help developers generate employee ID formats that are automatic, unique, and consistent.

How to Install This Library in a PHP Project (Via Composer – Recommended)

This library is available on Packagist, so you can install it using Composer, the dependency manager for PHP.

https://packagist.org/packages/ferdy/employeeidgenerator

1. Make Sure Composer Is Installed

If Composer is not yet installed on your system, install it first. After installation, you can verify it using this command in your terminal:

composer --version

2. Navigate to Your Project Directory

Open a terminal/command prompt, then move to the root folder of your PHP project:

cd path/ke/proyek-kamu

3. Add the Library Using Composer

Run the following command to install the package:

composer require ferdy/employeeidgenerator

This command will:

1. Add the package to the composer.json file,
2. Download the library code into the vendor/ folder,
3. Create or update the composer.lock file,
4. Set up autoloading so the library classes can be used.

4. Include the Autoload File in Your PHP Code

After installation is complete, make sure your main PHP script includes the autoload file:

<?php
require __DIR__ . '/vendor/autoload.php';

This file will automatically load all classes from installed libraries.

How to Install This Library in a PHP Project (Via GitHub – Alternative)

This is the standard way to install a library directly from GitHub without using Packagist. You can still use Composer to keep dependency management organized.

1. Add to composer.json

Open the composer.json file in your project, then add the repositories section like this:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/ferdysetia/Employee-ID-Generator.git"
        }
    ],
    "require": {
        "ferdy/Employee-ID-Generator": "dev-main"
    }
}

2. Run the Composer Command in Terminal

composer update

This command will:

1. Download the code from GitHub based on the configuration.
2. Add the package into vendor/.
3. Generate autoload files so the library classes can be used directly.

3. Use It in Your PHP Code

Then in your PHP file, simply include the autoload file:

<?php
require __DIR__ . '/vendor/autoload.php';

After that, you can create instances of the library classes according to the available namespace.

Feature Description and Explanation

This class is used to generate employee IDs with a customizable format based on year, month, sequence number, and department code.

Namespace:

Ferdy\EmployeeIDGenerator

Main Method:

EmployeeIDGenerator::generate()

This method is static, so it can be called without creating an object.

Method Parameters

The generate() method has the following parameters:

$year (int)
Full year, example: 2026

$month (int)
Month as a number 1–12

$sequence (int)
Employee sequence number for that period. Must be greater than 0.

$department (?string)
Department code, for example: HR, IT, FIN.
Required if department position is activated via options.

$options (array)
Options to configure the ID format.

Available Format Options

1. year_format Controls the year format.

'YYYY' → example: 2026
'YY'   → example: 26
Default: 'YYYY'

1. separator Character used to separate ID parts.

''  (no separator)
'-'
'/'
Default: no separator

1. dept_position Position of the department code in the ID.

'none'         → no department
'front'        → at the beginning
'after_month'  → after the month
Default: 'none'

1. seq_length Number of digits for the sequence number (padded with leading zeros if needed). Default: 3

Validations Performed

The method will throw an error (InvalidArgumentException) if:

1. The month is less than 1 or greater than 12
2. The sequence number is less than 1
3. Department position is set to anything other than 'none' but the $department parameter is empty

Usage Examples

The basic ID format is always: YEAR + MONTH + SEQUENCE

Most standard example:

$id = EmployeeIDGenerator::generate(2026, 5, 12);
echo $id;

Result: 202605012

Meaning:

1. 2026 = year
2. 05 = month (always 2 digits)
3. 012 = sequence number (default 3 digits, padded with zeros)

What You Can Configure

You can change 4 things through the options parameter.

1. Year Format

'year_format' => 'YY' // becomes 2 digits

Example:

$id = EmployeeIDGenerator::generate(2026, 5, 7, null, [
    'year_format' => 'YY'
]);

Result: 2605007

2. Separator

'separator' => '-'

Example:

$id = EmployeeIDGenerator::generate(2026, 5, 7, null, [
    'separator' => '-'
]);

Result: 2026-05-007

3. Add Department Code

A. Department at the Front

Example:

$id = EmployeeIDGenerator::generate(2026, 11, 25, 'HR', [
    'dept_position' => 'front',
    'separator' => '-'
]);

Result: HR-2026-11-025

B. Department After Month

Example:

$id = EmployeeIDGenerator::generate(2026, 1, 3, 'IT', [
    'dept_position' => 'after_month',
    'separator' => '/'
]);

Result: 2026/01/IT/003

4. Sequence Number Length

'seq_length' => 5

Example:

$id = EmployeeIDGenerator::generate(2026, 1, 3, 'IT', [
    'dept_position' => 'after_month',
    'seq_length' => 5,
    'separator' => '/'
]);

Result: 2026/01/IT/00003

How to Use in a Project

1. Include Composer Autoload

require __DIR__ . '/vendor/autoload.php';

2. Import the Class

use Ferdy\EmployeeIDGenerator\EmployeeIDGenerator;

3. Use It When Creating a New Employee

$year  = date('Y');
$month = date('n');
$nextSeq = 28; // misalnya dari database

$employeeId = EmployeeIDGenerator::generate($year, $month, $nextSeq, 'FIN', [
    'dept_position' => 'front',
    'separator' => '-',
    'seq_length' => 4
]);

echo $employeeId;

Example result: FIN-2026-01-0028

In Short

You only need to fill in:

generate(year, month, sequence_number, optional_department_code, format_options)