README

A powerful and flexible PHP library for generating ASCII art from text with multiple fonts, styles, and formatting options.

Features

🎨 6 Built-in Fonts: block, small, mini, big, shadow, double
🖼️ Border Support: Customizable borders with different characters
📐 Alignment Options: Left, center, right alignment
🔤 Spacing Control: Adjust character and line spacing
📏 Size Control: Set fixed width and height
🎯 Fluent Interface: Chain methods for easy configuration
🚀 Zero Dependencies: Pure PHP implementation
📦 PSR-4 Compatible: Modern PHP package structure

Installation

composer require abderrahimghazali/ascii-art-generator

Requirements:

PHP 7.4+

Quick Start

use AsciiArtGenerator\AsciiArt;

// Simple text
echo AsciiArt::text('HELLO')->render();

// With different font
echo AsciiArt::text('WORLD')->font('big')->render();

// Banner with border
echo AsciiArt::banner('WELCOME', ['border' => true]);

Basic Usage

Simple Text Generation

use AsciiArtGenerator\AsciiArt;

$art = AsciiArt::text('PHP')
    ->font('block')
    ->render();

echo $art;

Output:

████  █   █ ████ 
█   █ █   █ █   █
████  █████ ████ 
█     █   █ █    
█     █   █ █

Available Fonts

// Block font (default) - 5x7 characters
AsciiArt::text('HELLO')->font('block');

// Small font - 3x5 characters  
AsciiArt::text('HELLO')->font('small');

// Mini font - 1x3 characters
AsciiArt::text('HELLO')->font('mini');

// Big font - 7x9 characters
AsciiArt::text('HELLO')->font('big');

// Shadow font - block with shadow effect
AsciiArt::text('HELLO')->font('shadow');

// Double line font - using box drawing characters
AsciiArt::text('HELLO')->font('double');

Advanced Features

Banners with Borders

// Simple banner
echo AsciiArt::banner('SUCCESS');

// Custom border
echo AsciiArt::banner('ERROR', [
    'border' => true,
    'borderChar' => '#',
    'padding' => 3,
    'alignment' => 'center'
]);

Output:

#######################
#                     #
#                     #
#                     #
#       ERROR         #
#                     #
#                     #
#                     #
#######################

Alignment and Spacing

// Center aligned with custom width
AsciiArt::text('TITLE')
    ->font('block')
    ->width(50)
    ->align('center')
    ->render();

// Custom character spacing
AsciiArt::text('SPACED')
    ->spacing(3)
    ->render();

// Custom padding
AsciiArt::text('PADDED')
    ->padding(2)
    ->border()
    ->render();

Fluent Interface

$art = AsciiArt::text('AWESOME')
    ->font('big')
    ->align('center')
    ->width(60)
    ->spacing(2)
    ->border(true, '=')
    ->padding(3)
    ->render();

echo $art;

Method Reference

Static Factory Methods

`AsciiArt::text(string $text): self`

Create ASCII art from text.

`AsciiArt::banner(string $text, array $options = []): self`

Create a banner with optional border.

Options:

border (bool): Add border (default: true)
borderChar (string): Border character (default: '*')
padding (int): Padding around text (default: 2)
alignment (string): Text alignment (default: 'center')

Configuration Methods

`font(string $font): self`

Set the font style.

Available fonts: block, small, mini, big, shadow, double

`border(bool $enabled = true, string $char = '*'): self`

Add border around the text.

`align(string $alignment): self`

Set text alignment: left, center, right

`width(int $width): self`

Set fixed width for alignment.

`spacing(int $spacing): self`

Set character spacing (0 = no spacing).

`padding(int $padding): self`

Set padding around text when using borders.

Output Methods

`render(): string`

Generate and return the ASCII art as a string.

`__toString(): string`

Automatic string conversion (calls render()).

Utility Methods

`AsciiArt::getAvailableFonts(): array`

Get list of available font names.

Real-World Examples

CLI Application Header

function showAppHeader() {
    echo AsciiArt::banner('MyApp v2.1', [
        'border' => true,
        'borderChar' => '=',
        'padding' => 2,
        'alignment' => 'center'
    ]);
}

Success/Error Messages

function showSuccess($message) {
    return AsciiArt::text('SUCCESS')
        ->font('small')
        ->align('center')
        ->width(40)
        ->border(true, '+')
        ->render() . "\n" . $message;
}

function showError($message) {
    return AsciiArt::text('ERROR')
        ->font('block')
        ->align('center')
        ->width(30)
        ->border(true, '!')
        ->render() . "\n" . $message;
}

Logo Generation

function generateLogo($companyName) {
    return AsciiArt::text($companyName)
        ->font('big')
        ->align('center')
        ->width(80)
        ->spacing(1)
        ->render();
}

echo generateLogo('ACME CORP');

Multi-line Text

$multiLine = "HELLO\nWORLD";
echo AsciiArt::text($multiLine)
    ->font('block')
    ->align('center')
    ->width(30)
    ->border()
    ->render();

Loading Screens

function showLoading($step, $total) {
    $percentage = round(($step / $total) * 100);
    
    echo AsciiArt::banner("LOADING {$percentage}%", [
        'border' => true,
        'borderChar' => '#',
        'alignment' => 'center'
    ]);
}

Font Previews

Block Font (Default)

 ███  █     ███   ███ █   █
█   █ █    █   █ █    █  █ 
█████ █    █   █ █    ███  
█   █ █    █   █ █    █  █ 
█   █ ████  ███   ███ █   █

Small Font

██  █   ███ ██ █ █
█ █ █  █   █   ██ 
███ █  █   █   ███
█ █ █  █   █   █ █
█ █ ███ ███ ██ █ █

Shadow Font

 ███▓ █     ███▓  ███▓█   ██
█   ██ █    █   ██    ██  ██ 
██████ █    █   ██    ██████ 
█   ██ █    █   ██    ██  ██ 
█   ██ █████ ███▓ ███▓█   ██

Error Handling

try {
    $art = AsciiArt::text('TEST')
        ->font('invalid-font')
        ->render();
} catch (\InvalidArgumentException $e) {
    echo "Error: " . $e->getMessage();
}

Performance Considerations

Font Size: Larger fonts generate more output and take longer to render
Text Length: Very long text will increase processing time
Memory Usage: Large ASCII art outputs consume more memory
Caching: Consider caching generated ASCII art for frequently used text

Extending Fonts

You can extend the class to add custom fonts:

class CustomAsciiArt extends AsciiArt 
{
    protected function getCustomFont() {
        return [
            'A' => [
                '▄▀█',
                '█▀█'
            ],
            // ... more characters
        ];
    }
}

License

MIT License. See LICENSE file for details.

Contributing

Pull requests welcome! Please ensure tests pass:

composer test

abderrahimghazali / ascii-art-generator

Maintainers

Details