README

A simple and fast PHP library for converting Markdown to HTML.

⚠️ Development Status

This library is in early development (v0.x.x). The API may change between minor versions until v1.0.0.

Installation

composer require vlotysh/markdown-parser

Quick Start

<?php

use Vlotysh\MarkdownParser\MarkdownParser;

$parser = new MarkdownParser();
$html = $parser->parse('# Hello World');

echo $html; // <h1>Hello World</h1>

Supported Elements

Headers

# H1
## H2
### H3
#### H4
##### H5
###### H6

Alternative H1
==============

Alternative H2
--------------

Text Formatting

**bold text**
*italic*
~~strikethrough~~ (GFM mode only)
`inline code`

Lists

- Unordered list
- Item 2
- Item 3

1. Ordered list
2. Item 2
3. Item 3

Links and Images

[Link text](https://example.com)
![Alt text](https://example.com/image.jpg)

Automatic links: https://example.com

Blockquotes

> This is a quote
> Multi-line quote

Code Blocks

```php
<?php
echo "Hello World";
?>
```

    // Or with 4 spaces
    echo "Hello World";

Tables

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

Horizontal Rules

---
***
___

Configuration

$parser = new MarkdownParser([
    'breaks' => false,    // Line breaks as <br>
    'gfm' => true,        // GitHub Flavored Markdown
    'tables' => true,     // Table support
    'sanitize' => true,   // HTML sanitization
]);

Options

breaks (bool, default: false) - Converts line breaks to <br> tags
gfm (bool, default: true) - Enables GitHub Flavored Markdown support (strikethrough)
tables (bool, default: true) - Enables table support
sanitize (bool, default: true) - Removes potentially dangerous HTML tags

Usage Examples

Basic Usage

use Vlotysh\MarkdownParser\MarkdownParser;

$parser = new MarkdownParser();

$markdown = '
# My Blog

This is an **important** post about *development*.

## Code

```php
echo "Hello World";

List

PHP
JavaScript
Python ';

echo $parser->parse($markdown);


### With Custom Settings

```php
$parser = new MarkdownParser([
    'breaks' => true,
    'sanitize' => false
]);

$html = $parser->parse($markdown);

Framework Integration

Laravel

// In service provider
$this->app->singleton(MarkdownParser::class, function () {
    return new MarkdownParser([
        'gfm' => true,
        'tables' => true
    ]);
});

// In controller
public function show(MarkdownParser $parser, Post $post)
{
    $html = $parser->parse($post->content);
    return view('post.show', compact('html'));
}

Symfony

// services.yaml
services:
    Vlotysh\MarkdownParser\MarkdownParser:
        arguments:
            $options:
                gfm: true
                tables: true

// In controller
public function show(MarkdownParser $parser, Post $post): Response
{
    $html = $parser->parse($post->getContent());
    return $this->render('post/show.html.twig', ['html' => $html]);
}

Testing

# Run tests
composer test

# Tests with coverage
composer test-coverage

# Static analysis
composer phpstan

# Code style check
composer cs-check

# Fix code style
composer cs-fix

Performance

The library is optimized for speed and minimal memory usage:

Single-pass parsing
No recursive calls
Minimal regular expression usage
Lazy parser initialization

Approximate performance:

1000 lines of markdown ≈ 5ms
10000 lines of markdown ≈ 50ms

Security

By default, the library sanitizes potentially dangerous HTML tags:

<script>
<style>
<iframe>
<object>
<embed>
<form>

To disable sanitization:

$parser = new MarkdownParser(['sanitize' => false]);

Extending Functionality

Creating Custom Parser

use Vlotysh\MarkdownParser\Parsers\BlockParserInterface;

class CustomParser implements BlockParserInterface
{
    public function parse(string $line, array $lines, int $index): ?array
    {
        if (preg_match('/^custom: (.+)$/', $line, $matches)) {
            return [
                'block' => [
                    'type' => 'custom',
                    'content' => $matches[1]
                ],
                'nextIndex' => $index
            ];
        }
        
        return null;
    }
}

Requirements

PHP 8.2 or higher
Composer

License

MIT License. See LICENSE file for details.

Development

Project Structure

src/
├── MarkdownParser.php          # Main class
├── Parsers/
│   ├── ParserInterface.php     # Interfaces
│   ├── HeaderParser.php        # Header parser
│   ├── CodeBlockParser.php     # Code block parser
│   ├── ListParser.php          # List parser
│   └── TableParser.php         # Table parser
tests/
├── MarkdownParserTest.php      # Main tests
example/
├── usage.php                   # Usage example

Contributing

Fork the project
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Roadmap

Footnotes support
Definition lists support
Math expressions support
Plugin architecture
Result caching
Advanced sanitization

Comparison with Other Libraries

Feature	Our Library	Parsedown	CommonMark
Size	~50KB	~100KB	~500KB
Speed	Fast	Medium	Slow
PHP 8	✅	❌	✅
Configuration	✅	Limited	✅
Tables	✅	✅	Via extensions

Support

📧 Email: lotysh.vm@gmail.com
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

vlotysh / markdown-parser

Maintainers

Details