README

A simple PHP library that solves the headache of fitting names on cards and badges. If you've ever struggled with names that are too long for credit cards, ID badges, or passport printing, this is your solution.

Why This Library?

We've all seen ID cards with awkwardly truncated names or ridiculously small fonts trying to fit long names. This library fixes that problem with intelligent name formatting for fixed-width spaces.

It's especially useful for:

Card printing (credit, debit, ID, membership)
Name badges and tags
Passports and government IDs
Any system with character limits for names

Key Features

Smart formatting that preserves readability
Handles both English and Arabic names with different strategies
Adjustable character limits to match your exact requirements
UTF-8 support for international names
No external dependencies besides PHP's mbstring

Installation

Just run:

composer require omar-haris/card-name-fit

Basic Usage

use CardNameFit\NameFormatter;

// Create a formatter with 20-character limit
$formatter = new NameFormatter(20);

// Format some names
echo $formatter->format('John William Smith');             // "John William Smith"
echo $formatter->format('John William Alexander Smith');   // "John William Smith"

// Works with Arabic names too
echo $formatter->format('محمد عبد الرحمن العبد الله');     // "محمد عبد الرحمن"

Formatting Strategies

For English Names

The library offers two approaches:

1. GREEDY (default)

Keeps full middle names when possible, drops them when needed. People generally prefer seeing their complete names rather than initials.

// With 20 character limit
$formatter = new NameFormatter(20, NameFormatter::ENGLISH_GREEDY);

echo $formatter->format('John Smith');                   // "John Smith"
echo $formatter->format('John William Smith');           // "John William Smith"
echo $formatter->format('John William Alexander Smith'); // "John William Smith" 
                                                         // (drops "Alexander")

2. DENSE

Ensures every name part appears, at least as an initial. Better when all name components must be represented.

// With 20 character limit
$formatter = new NameFormatter(20, NameFormatter::ENGLISH_DENSE);

echo $formatter->format('John William Alexander Smith'); // "John W. A. Smith"
                                                         // (includes all parts)

For Arabic Names

Arabic names use a simple left-to-right approach, preserving whole words since initials don't make sense in Arabic.

$formatter = new NameFormatter(25);

echo $formatter->format('محمد عبد الرحمن العبد الله'); // "محمد عبد الرحمن"

Edge Cases Handled

Very Long Names

The library handles unusually long names gracefully:

$formatter = new NameFormatter(20);

// Long last name
echo $formatter->format('John Wolfeschlegelsteinhausenbergerdorff');
// "John Wolfeschlegelst"

Whitespace Cleanup

No need to worry about extra spaces or inconsistent formatting:

$formatter = new NameFormatter(20);
echo $formatter->format('  John   William   Smith  '); // "John William Smith"

Configuration

/**
 * @param int    $maxLength   Maximum allowed characters (≥ 1)
 * @param string $englishMode Strategy: ENGLISH_GREEDY or ENGLISH_DENSE
 * @param string $encoding    Character encoding (default: UTF-8)
 */
public function __construct(
    int    $maxLength   = 35,
    string $englishMode = self::ENGLISH_GREEDY,
    string $encoding    = 'UTF-8'
)

Security & Compliance

This library only formats text - it doesn't store or transmit any personal data. It's designed with:

GDPR considerations (no data retention)
PCI DSS compatibility (no cardholder data storage)

Requirements

PHP 8.3+
mbstring extension

License

MIT License. See the LICENSE file.

Credits

Omar Haris

omar-haris / card-name-fit

Maintainers

Details