Download the PHP package ubertech-za/html-to-asciidoc without Composer

HTML to AsciiDoc Converter

⚠️ BETA SOFTWARE NOTICE This package is currently in beta and is being prepared for testing in upcoming projects. Please expect possible breaking changes in future releases. We do not recommend using this package in production environments without thorough testing.

This package converts HTML to AsciiDoc markup, inspired by and architecturally based on The PHP League's html-to-markdown package. Like its inspiration, this library uses a DOM-based approach with pluggable converters to ensure reliable and extensible HTML parsing and conversion. We extend our gratitude to The PHP League for their excellent architectural foundation—if League would like to incorporate this AsciiDoc functionality into their ecosystem, they are most welcome to do so.

Features

• 🏗️ DOM-based parsing - Uses PHP's DOMDocument for reliable HTML parsing
• 🔧 Extensible architecture - Add custom converters for specific elements
• 📝 Complete AsciiDoc support - Headers, emphasis, links, images, lists, tables, code blocks
• ⚙️ Configurable - Customize conversion behavior with options
• 🧪 Well tested - Comprehensive test suite with 100+ assertions
• 🚀 Laravel integration - Optional service provider for Laravel projects
• 📦 Framework agnostic - Works with any PHP project

Installation

Install the package via Composer:

Framework Independence: This package works standalone with any PHP project. Laravel integration is completely optional and only activated when Laravel is detected in your project.

Quick Start

Output:

Usage

Basic Usage

The simplest way to convert HTML to AsciiDoc:

Using the Laravel Wrapper

If you're using the package in a Laravel project, you can use the provided converter wrapper:

Using the Laravel Facade

For even simpler usage in Laravel, you can use the provided facade:

Configuration Options

Customize the conversion behavior with configuration options:

Method Chaining

You can chain methods for fluent configuration:

Supported HTML Elements

Headers

Converts to:

Text Formatting

Converts to:

Links and Images

Converts to:

Lists

Converts to:

Code Blocks

Converts to:

Blockquotes

Converts to:

Tables

Converts to:

Other Elements

• <hr> → ''' (horizontal rule)
• <br> → + (line break) or \n with hard_break option
• <p> → Paragraphs with proper spacing
• <div> → Content blocks with spacing

Configuration Reference

Advanced Usage

Custom Environment

For more control, you can create a custom environment:

Adding Custom Converters

Create custom converters for specific HTML elements:

Configuration-Aware Converters

Converters can access configuration options:

Laravel Integration

Note: Laravel integration is completely optional. The core package works independently without any Laravel dependencies. Laravel features are only available when illuminate/support is installed.

Automatic Registration

If you're using Laravel, the service provider is automatically registered when Laravel is detected. You can publish the configuration:

This will publish a config/html-to-asciidoc.php configuration file where you can set default conversion options.

Facade Registration

Add the facade to your config/app.php file if you want to use it globally:

Then use it anywhere in your application:

Dependency Injection

Use dependency injection in your controllers:

Facade Usage in Controllers

Using the facade in controllers:

Blade Templates

Use the facade in Blade templates:

Available Container Bindings

The service provider registers the following bindings:

• UbertechZa\HtmlToAsciidoc\HtmlToAsciiDocConverter::class - Main converter instance
• UbertechZa\HtmlToAsciidoc\HtmlConverter::class - Core HTML converter
• 'html-to-asciidoc' - Facade accessor binding

All bindings are registered as singletons for optimal performance.

Error Handling

The converter handles malformed HTML gracefully:

Performance Considerations

• DOM Parsing: Uses PHP's native DOMDocument for reliable parsing
• Memory Usage: Processes HTML in memory; consider chunking for very large documents
• Caching: Consider caching converted output for frequently accessed content
• Configuration: Create converter instances once and reuse them

Testing

Run the test suite:

Run tests with coverage:

Run static analysis:

Contributing

Contributions are welcome! Please see our contributing guidelines for details.

1. Fork the repository
2. Create a feature branch
3. Write tests for your changes
4. Ensure all tests pass
5. Submit a pull request

Changelog

Please see CHANGELOG.md for details on recent changes.

Security

If you discover any security-related issues, please email [email protected] instead of using the issue tracker.

Credits

This package is architecturally based on and inspired by The PHP League's html-to-markdown package. We extend our gratitude to The PHP League for their excellent architectural foundation. Like its inspiration, this library uses a DOM-based approach with pluggable converters to ensure reliable and extensible HTML parsing and conversion.

• Original Architecture: The PHP League's html-to-markdown (MIT License)
• AsciiDoc Implementation: Uber Technologies cc
• Contributors: All contributors

Architectural Attribution

This package borrows and adapts the following architectural patterns from thephpleague/html-to-markdown:

• DOM-based HTML parsing approach
• Pluggable converter system for HTML elements
• Environment and configuration management
• Element interface and converter interface patterns

The implementation has been adapted specifically for AsciiDoc output format while maintaining the robust parsing and extensibility patterns established by The PHP League.

License

This package is open-sourced software licensed under the MIT license.

Related Packages

• thephpleague/html-to-markdown - Convert HTML to Markdown
• ubertech-za/tiptap-to-asciidoc - Convert Tiptap JSON to AsciiDoc

Made by Uber Technologies cc