README

A PHP library for escaping content to be safely embedded in Markdown without breaking rendering. Supports multiple Markdown dialects and provides context-aware escaping for different use cases.

Features

• Multiple Dialect Support: CommonMark and GitHub Flavored Markdown (GFM)
• Context-Aware Escaping: Different escaping strategies for URLs, inline code, code blocks, and general content
• Templating System: Built-in templating engine with PHP short tags for generating complex Markdown documents
• SOLID Design: Built with clean architecture and design patterns for easy extension
• PHP 7.2+ Compatible: Works with PHP 7.2 and all newer versions
• Fully Tested: Comprehensive unit and feature tests
• Zero Dependencies: No runtime dependencies beyond PHP itself
• High Test Coverage: 98%+ code coverage with comprehensive unit and integration tests

Installation

Install via Composer:

composer require schlessera/markdown-escape

Quick Start

use Markdown\Escape\MarkdownEscape;

// Create an escaper instance (defaults to CommonMark)
$escape = new MarkdownEscape();

// Or use factory methods for specific dialects
$escape = MarkdownEscape::commonMark();
$escape = MarkdownEscape::gfm();

// Escape general content
$escaped = $escape->escapeContent('This is *bold* and _italic_ text');
// Output: This is \*bold\* and \_italic\_ text

// Escape URLs
$escaped = $escape->escapeUrl('https://example.com/path with spaces/(parentheses)');
// Output: https://example.com/path%20with%20spaces/%28parentheses%29

// Escape inline code
$escaped = $escape->escapeInlineCode('Use `backticks` for code');
// Output: ``Use `backticks` for code``

// Escape code blocks
$code = "function test() {\n    return true;\n}";
$escaped = $escape->escapeCodeBlock($code, ['use_fences' => true, 'language' => 'php']);
// Output: ```php
//         function test() {
//             return true;
//         }
//         ```

Templating System

Generate complex Markdown documents using the built-in templating system:

use Markdown\Escape\MarkdownTemplate;

// Create template instance
$template = MarkdownTemplate::gfm();

// Use built-in templates
$result = $template->render('table', [
    'headers' => ['Name', 'Status', 'Progress'],
    'rows' => [
        ['Feature **A**', 'Complete', '100%'],
        ['Feature *B*', 'In Progress', '75%']
    ]
]);

// Custom templates with automatic escaping
$result = $template->renderString('
# <?= $md->escapeContent($title) ?>

Published by <?= $md->escapeContent($author) ?> on <?= date("Y-m-d") ?>

<?php foreach ($sections as $section): ?>
## <?= $md->escapeContent($section["title"]) ?>

<?= $md->escapeContent($section["content"]) ?>
<?php endforeach; ?>
', [
    'title' => 'My **Important** Document',
    'author' => 'John [Admin] Doe',
    'sections' => [
        ['title' => 'Introduction', 'content' => 'Content with *markdown* syntax...']
    ]
]);

Documentation

• User Guide - Comprehensive guide to using the library
• Templating Guide - Complete guide to the templating system
• Architecture - Understanding the library's design
• Examples - Working examples demonstrating various features
• Code Coverage - Testing and coverage information

Requirements

• PHP 7.2 or higher
• Composer for dependency management

Development

Running Tests

composer test              # Run all tests
composer test:unit         # Run unit tests only
composer test:integration  # Run integration tests only
composer test:performance  # Run performance tests

Code Coverage

composer test:coverage     # Generate HTML coverage report and text summary
composer test:coverage:clover  # Generate Clover XML report
composer coverage:badge    # Generate coverage badge

# View coverage report
open coverage/html/index.html  # macOS
xdg-open coverage/html/index.html  # Linux
start coverage/html/index.html  # Windows

Code Style

composer cs       # Check code style
composer cs-fix   # Fix code style issues

Static Analysis

composer phpstan

PHP Compatibility Check

composer phpcompat  # Checks PHP 7.2+ compatibility

Full Check

composer check    # Runs all checks (CS, PHPStan, PHP compatibility, and tests)

License

This library is released under the MIT License. See LICENSE file for details.

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

Support

If you discover any security related issues, please email alain.schlesser@gmail.com instead of using the issue tracker.