kodhe / typography

1.1.0 2026-09-29 12:51 UTC

Requires

• php: >=8.1

MIT

Published on Packagist.org on 2026-09-29 18:43 UTC

README

A text → HTML auto-formatting library — a refactored version of the CodeIgniter 3 Typography library (namespace Kodhe\Framework\Typography). It turns blank-line-separated paragraphs into <p> tags, newlines inside <pre> into <br>, fixes spacing after punctuation, abbreviates thousands (1000000 → 1,000,000), etc. The Kodhe version splits internals into Formatters/ and Parsers/ and adds regex caching & HTML tag protection.

Installation

composer require kodhe/typography

Requirements: PHP >= 8.1. No external dependencies.

Quick Start

<?php

declare(strict_types=1);

use Kodhe\Framework\Typography\Typography;

$typo = new Typography();

echo $typo->auto_typography('Hello world! This is the second sentence...');
// <p>Hello world! This is the second sentence&hellip;</p>

Directory Structure

src/
├── Typography.php              # Main class (CI3-compatible API)
├── Contracts/                  # FormatterInterface, ParserInterface
├── Formatters/                 # CharacterFormatter, ParagraphFormatter
├── Parsers/                    # HtmlParser, TextParser
├── Support/                    # HtmlProtect, RegexCache
├── ValueObjects/TypographicConfig.php
├── Factory/
├── helpers/
└── Exceptions/TypographyException.php

Usage

1. Full auto-typography

$str = "First line.\n\nSecond line after a blank paragraph.";
echo $typo->auto_typography($str);
// <p>First line.</p>\n\n<p>Second line after a blank paragraph.</p>

// Reduce excessive newlines (>2 becomes 2):
echo $typo->auto_typography($str, true); // $reduce_linebreaks argument

What auto_typography() does:

• wraps text blocks with <p> ... </p>
• <br /> for newlines inside <pre>
• adds one space after . ! ? : ; when missing
• replaces three dots ... with …
• formats numbers ≥ 1 million with thousands separators (2000000 → 2,000,000)
• tidies double spaces at the start of paragraphs

2. Character fixes only (without creating <p>)

echo $typo->format_characters('Number 1000000 and an ellipsis...');
// Number 1000000 -> unchanged; '...' -> '…' (per the character rules)

3. nl2br that respects <pre>

echo $typo->nl2br_except_pre("line1\nline2");   // line1<br />line2
// but inside <pre> blocks, \n is left as-is

4. Protection of braced quotes {}

$typo->protect_braced_quotes = TRUE;   // default FALSE
echo $typo->protect_braced_quotes($html);
// keeps {...} safe from regex manipulation, then restores it via a callback

5. Configuring which elements are processed/skipped

$typo->initialize([
    // list of tags treated as block elements (regex alternation)
    'block_elements'      => 'address|blockquote|div|h\\d|p|pre|table|ul',
    // tags whose contents must not be reformatted
    'skip_elements'       => 'p|pre|ol|ul|dl|table|h\\d',
    'inline_elements'     => 'a|abbr|b|br|code|em|i|img|span|strong',
    'inner_block_required'=> ['blockquote'],
    'protect_braced_quotes' => true,
]);

print_r($typo->getConfig());  // active config array

API Reference (summary)

Method	Description
__construct(array $config = [])	Creates an instance, optionally calling initialize() right away
initialize(array $config)	Sets the configuration (synced to the legacy public properties)
getConfig(): array	Retrieves the active config
auto_typography($str, $reduce_linebreaks = false)	Full formatting → HTML
format_characters($str)	Character/number fixes only
nl2br_except_pre($str)	nl2br except inside <pre>
protect_braced_quotes($str)	Protects {...} from regex

CodeIgniter 3 Compatibility

Behavior matches CI_Typography; the tuning public properties (block_elements, skip_elements, inline_elements, last_block_element, protect_braced_quotes) remain, so old code runs unchanged apart from the class/namespace name.

Notes

• The output of auto_typography() is not a sanitizer replacement — do not use it to filter untrusted input.
• The modular layer (Formatters/, Parsers/, RegexCache) is internal; the stable API is the Typography class.

Testing

vendor/bin/phpunit --filter Typography