README

Terminal Art for Artisan
A beautiful, expressive terminal UI toolkit for PHP console applications

Full Documentation

Why TART?

Transform boring CLI commands into beautiful, professional applications with styled output, themed blocks, automatic logo generation, and more. Make your terminal applications a joy to use and a work of art!

// New fluent APIs (recommended)
$this->logo()
    ->text('MY APP')
    ->boxed()
    ->color('cyan')
    ->render();

$this->say('Processing data...');
$this->good('✓ Step 1 complete');
$this->success('🎉 Deployment complete!');

// Or use the traditional API (still supported)
$this->displayTextLogo('MY APP', 'box', ['text_color' => 'cyan']);
$this->say('Processing data...');
$this->good('✓ Step 1 complete');
$this->success('🎉 Deployment complete!');

📸 Examples in Action

✨ Features

• 🎨 Rich Formatting - Colored text, backgrounds, and styled blocks
• 📦 Block Messages - Beautiful success, warning, error, and info blocks
• 🏷️ Automatic Logos - Create branded ASCII art logos with one line of code
• 🎭 Theme System - Built-in themes or create your own with fluent APIs
• 📊 Progress Indicators - Build output line-by-line with columns
• 🔄 Progress Bars - Visual progress tracking with percentages (NEW!)
• ⏳ Spinners - Animated loading indicators with 7 styles (NEW!)
• 📝 Lists - Bullet, numbered, nested, and task lists (NEW!)
• 📊 Tables - Beautiful table rendering with auto-width (NEW!)
• 💬 Interactive Input - Text prompts and password input (NEW!)
• 🔧 Framework Agnostic - Works with Laravel, Symfony, or standalone
• ✨ Emoji Support - Full multi-byte UTF-8 character support
• 🧩 Modular - Use only what you need with traits
• ⚡ Fluent APIs - Chainable methods for expressive, Laravel-like syntax
• 🔄 Backward Compatible - Traditional APIs still supported

Installation

composer require igclabs/tart

Verify Installation

After requiring the package, you can confirm that Composer resolved the correct package by inspecting it:

composer show igclabs/tart
# name     : igclabs/tart
# versions : * 1.1.18

Quick Start

Laravel

<?php

namespace App\Console\Commands;

use IGC\Tart\Laravel\StyledCommand;

class DeployCommand extends StyledCommand
{
    protected $signature = 'app:deploy';
    
    public function handle()
    {
        // Beautiful branded logo (fluent API)
        $this->logo()
            ->text('DEPLOYMENT SYSTEM')
            ->boxed()
            ->color('cyan')
            ->render();
        
        $this->br();
        
        // Progress tracking
        $this->openLine('Building application');
        // ... work ...
        $this->appendLine(' ✓', 'green');
        $this->closeLine();
        
        $this->openLine('Running tests');
        // ... work ...
        $this->appendLine(' ✓', 'green');
        $this->closeLine();
        
        // Success finish
        $this->br();
        $this->success('🎉 Deployment Complete!');
        
        return self::SUCCESS;
    }
}

Example Usage

See the complete example in examples/laravel-example.php

Symfony Console

<?php

namespace App\Command;

use IGC\Tart\Symfony\StyledCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

class DeployCommand extends StyledCommand
{
    protected static $defaultName = 'app:deploy';

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $this->header('Deployment (Symfony)');
        $this->say('Shipping bits via Symfony Console!');
        $this->success('Done!');

        return Command::SUCCESS;
    }
}

Need custom defaults outside Laravel? Pass overrides into the constructor:

new DeployCommand('app:deploy', [
    'theme' => [
        'class' => \IGC\Tart\Themes\Theme::class,
        'color' => 'magenta',
        'max_line_width' => 100,
    ],
]);

Theme Configuration

TART ships with a default theme, but you can customize colors, highlight behavior, and layout width. The max_line_width setting is especially useful for matching the width of your terminal and for how blocks, progress bars, and banners wrap long text.

Theme Options

• class - The theme class to use (defaults to IGC\Tart\Themes\DefaultTheme)
• color - Primary color used by blocks and accents (default: blue)
• text_color - Default text color inside themed blocks (default: white)
• highlight_color - Accent/highlight color (default: yellow)
• max_line_width - Maximum line width for formatting (default: 72)
• colors - Palette used for random or multi-color effects (default: ['red', 'green', 'yellow', 'cyan', 'white'])

Example: Custom Theme via Config

new DeployCommand('app:deploy', [
    'theme' => [
        'class' => \IGC\Tart\Themes\Theme::class,
        'color' => 'magenta',
        'text_color' => 'white',
        'highlight_color' => 'yellow',
        'max_line_width' => 100,
        'colors' => ['magenta', 'cyan', 'white'],
    ],
]);

Example: Fluent Theme Updates

$theme = \IGC\Tart\Themes\Theme::make('green')
    ->withTextColor('white')
    ->withHighlightColor('yellow')
    ->withMaxWidth(90)
    ->withColors(['green', 'cyan', 'white']);

Laravel Auto-Discovery & Demo Commands

Laravel 9+ automatically discovers the IGC\Tart\Laravel\TartServiceProvider, which registers several Artisan demo commands. After installing the package you can immediately preview different aspects of the styling toolkit:

Available Demo Commands

# Quick guide to basic features (recommended first)
php artisan tart:demo

# One-line test of all features
php artisan tart:test

# NEW FEATURES demo (lists, tables, progress bars, spinners, input)
php artisan tart:new-features

# Comprehensive showcase of ALL features
php artisan tart:demo-full
php artisan tart:demo-full --theme=success
php artisan tart:demo-full --theme=error

# Fluent APIs showcase
php artisan tart:fluent-demo

# Interactive menu demo (menus, checkbox, radio)
php artisan tart:interactive-demo

Need manual control? Add TART to Composer's dont-discover list and register the provider in config/app.php:

{
    "extra": {
        "laravel": {
            "dont-discover": [
                "igclabs/tart"
            ]
        }
    }
}

// config/app.php
'providers' => [
    // ...
    IGC\Tart\Laravel\TartServiceProvider::class,
],

Publish Configuration

Publish the default configuration to tweak the base theme, logo colors, auto-answer behavior, and demo-command registration:

php artisan vendor:publish --tag=tart-config

config/tart.php lets you point to a custom ThemeInterface implementation, adjust palette/width used by the bundled Theme class, and control register_demo_commands (defaults to false).

📖 Core Features

Basic Output

$this->say('Regular message');
$this->good('✓ Success message');         // Green
$this->bad('✗ Error message');            // Red
$this->state('⚠ Status message');         // Yellow
$this->cool('ℹ Info message');            // Cyan

Block Messages

$this->header('Processing');              // Large header
$this->title('Section Title');            // Title block
$this->success('Operation succeeded!');   // Green block
$this->warning('Check this issue');       // Red block
$this->notice('Important info');          // Cyan block
$this->failure('Operation failed');       // Error block
$this->stat('Completed in 2.5s');        // Stat block
$this->footer('Process', 'Time: 2.5s');  // Footer

Recommended API Usage

TART supports both fluent APIs and the original, traditional methods. The fluent API is the preferred approach going forward because it is more expressive and easier to read. The traditional methods remain supported for backward compatibility.

Preferred (fluent)

$this->logo()
    ->text('MY APP')
    ->boxed()
    ->color('cyan')
    ->render();

$this->success('Deploy complete!');

Legacy (still supported)

$this->displayTextLogo('MY APP', 'box', ['text_color' => 'cyan']);
$this->success('Deploy complete!');

If you're migrating existing code, you can adopt fluent methods incrementally while keeping the original APIs for older commands.

Logo Creation 🎨

// Fluent API (recommended)
$this->logo()
    ->text('MY APP')
    ->render();

$this->logo()
    ->text('DEPLOYMENT')
    ->boxed()
    ->color('green')
    ->render();

$this->logo()
    ->text('BUILD COMPLETE')
    ->banner()
    ->render();

// ASCII art with fluent API
$asciiArt = <<<'ASCII'
  ____  ____   ___  _____  ____
 |  _ \|  _ \ / _ \|  ___/ ___|
 | |_) | |_) | | | | |_  \___ \
 |  __/|  _ <| |_| |  _|  ___) |
 |_|   |_| \_\\___/|_|   |____/
ASCII;

$this->logo()
    ->ascii($asciiArt)
    ->colors(['cyan', 'blue', 'white'])
    ->render();

// Traditional API (still supported)
$this->displayTextLogo('MY APP');
$this->displayTextLogo('DEPLOYMENT', 'box', ['text_color' => 'green']);
$this->displayTextLogo('BUILD COMPLETE', 'banner');
$this->displayAsciiLogo($asciiArt, ['colors' => ['cyan', 'blue', 'white']]);

Line Building & Columns

// Progressive output
$this->openLine('Processing users');
// ... do work ...
$this->appendLine(' ✓ Done', 'green');
$this->closeLine();

// Table-like columns
$this->openLine('User');
$this->addColumn('John Doe', 25, 'white');
$this->addColumn('Active', 15, 'green');
$this->addColumn('Admin', 10, 'cyan');
$this->closeLine();

Layout

$this->br();        // Blank line
$this->br(3);       // 3 blank lines
$this->hr();        // Horizontal rule

🎨 Themes

use IGC\Tart\Themes\{DefaultTheme, SuccessTheme, ErrorTheme, Theme};

// Fluent theme creation (recommended)
$theme = Theme::make('magenta')
    ->withTextColor('white')
    ->withHighlightColor('yellow')
    ->withMaxWidth(80);

$this->setTheme($theme);
$this->header('Success Operations');

// Use built-in theme
$this->setTheme(new SuccessTheme());
$this->header('Success Operations');

// Traditional theme creation (still supported)
$theme = new Theme(
    color: 'magenta',
    textColor: 'white',
    highlightColor: 'yellow',
    maxLineWidth: 80
);
$this->setTheme($theme);

Built-in Themes:

• DefaultTheme - Blue (general use)
• SuccessTheme - Green (success operations)
• ErrorTheme - Red (error handling)

📚 Documentation

• Getting Started - Installation and first steps
• Quick Reference - Complete API reference
• Logo Creation - Logo generation guide
• Examples - Working code examples

💻 Examples

Check out the working examples in the examples/ directory:

Built-in Demo Command

# Auto-registered when the package is installed in Laravel
php artisan tart:demo

Quick Demo Source

# Basic demo showing the same features inside your editor
cat examples/demo-command.php

Comprehensive Demo

# Full showcase of all TART capabilities
cat examples/comprehensive-demo.php

Laravel Integration

# Complete Laravel command example
cat examples/laravel-example.php

Try it yourself:

1. Run php artisan tart:demo to see the built-in showcase
2. Copy any example to your Laravel app/Console/Commands/ directory when you're ready to customize your own command

💡 Use Cases

Application Branding

public function handle()
{
    // Fluent logo creation
    $this->logo()
        ->text('PROFSS PLATFORM')
        ->boxed()
        ->color('cyan')
        ->render();

    // ... application logic ...
}

Progress Tracking

$items = ['Users', 'Posts', 'Comments'];

foreach ($items as $item) {
    $this->openLine("Processing {$item}");
    // ... process ...
    $this->appendLine(' ✓', 'green');
    $this->closeLine();
}

Status Reports

$this->say('System Status:');
$this->good('✓ Database: Connected');
$this->good('✓ Cache: Operational');
$this->bad('✗ API: Connection timeout');
$this->stat('Report generated in 1.2s');

Themed Operations

// Fluent theme creation
$theme = Theme::make('green')
    ->withTextColor('white')
    ->withHighlightColor('yellow');

$this->setTheme($theme);
$this->header('Deployment');
// ... deployment logic ...
$this->logo()
    ->text('SUCCESS')
    ->banner()
    ->color('green')
    ->render();

🏗️ Architecture

TART uses a modular trait-based architecture:

• HasColoredOutput - Basic colored text output
• HasBlocks - Block-style formatted messages
• HasLineBuilding - Build lines incrementally
• HasInteractivity - Interactive prompts

Mix and match traits in your own classes for maximum flexibility.

🧪 Testing

composer install
composer test

Requirements

• PHP 8.0 or higher
• Symfony Console 5.0+ or 6.0+
• Laravel 9.0+ (for Laravel integration)
• mbstring extension (standard in most PHP installations)

📦 What's Included

• ✅ 15+ output methods
• ✅ 7 block message types
• ✅ 3 logo styles (standard, box, banner)
• ✅ Theme system with 3 built-in themes
• ✅ Interactive input (text, password, validation)
• ✅ Progress bars with live updates
• ✅ Spinners with 7 animation styles
• ✅ Lists (bullet, ordered, nested, task)
• ✅ Table rendering with auto-sizing
• ✅ Multi-byte character support (emojis!)
• ✅ 50+ unit and integration tests
• ✅ Complete documentation
• ✅ Working examples

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

📄 License

MIT License - see LICENSE for details.

🙏 Credits

Developed by the IGC team. Extracted from internal tooling and open-sourced for the community.

🔗 Resources

• Getting Started: docs/GETTING-STARTED.md
• Quick Reference: docs/guides/QUICK-REFERENCE.md
• Logo Creation: docs/guides/LOGO-CREATION.md
• Examples: examples/README.md

Make your CLI applications beautiful with Terminal Art! 🎨✨

Get Started • API Reference • Logos • Examples