README

A modern PHP library for creating ePub 3 ebooks. Zero dependencies, full ePub 3.0.1 compliance, ePub 2 NCX fallback, accessibility metadata, SVG and MathML support.

Requirements

• PHP 8.2+
• ext-zip
• ext-dom
• ext-libxml

Installation

composer require andileco/php-epub

Quick Start

use PhpEpub\Epub;
use PhpEpub\Metadata;
use PhpEpub\Chapter;
use PhpEpub\Resource;
use PhpEpub\Semantic;

$epub = Epub::create()
    ->metadata(
        Metadata::create('My Book')
            ->authors(['Jane Doe'])
            ->isbn('978-1234567890')
            ->publisher('Example Press')
    )
    ->stylesheet(Resource::fromFile('styles.css'))
    ->chapter(
        Chapter::create('Introduction', '<h1>Introduction</h1><p>Welcome.</p>')
            ->semantic(Semantic::INTRODUCTION)
    )
    ->chapter(
        Chapter::create('Chapter 1', '<h1>Getting Started</h1><p>Content here...</p>')
            ->semantic(Semantic::CHAPTER)
            ->subChapter(
                Chapter::create('Prerequisites', '<h2>Prerequisites</h2><p>You need...</p>')
            )
    )
    ->save('my-book.epub');

Features

Fluent Builder API

All builder methods return new instances (immutable), so you can chain them:

$epub = Epub::create()
    ->metadata($meta)
    ->stylesheet($css)
    ->chapter($ch1)
    ->chapter($ch2);

ePub 3 Semantic Types

Tag chapters with semantic meaning from the EPUB 3 Structural Semantics Vocabulary:

->chapter(Chapter::create('Preface', $html)->semantic(Semantic::PREFACE))
->chapter(Chapter::create('Chapter 1', $html)->semantic(Semantic::CHAPTER))
->chapter(Chapter::create('Glossary', $html)->semantic(Semantic::GLOSSARY))

This adds epub:type attributes to the XHTML and generates a landmarks navigation.

Nested Chapters

Create hierarchical table of contents:

->chapter(
    Chapter::create('Part One', '<p>Intro to part one.</p>')
        ->subChapter(Chapter::create('Section 1.1', '<p>Details.</p>'))
        ->subChapter(Chapter::create('Section 1.2', '<p>More details.</p>'))
)

SVG Support

SVG is an ePub 3 core media type. Include inline SVG for charts, diagrams, and illustrations:

$html = '<p>Here is a chart:</p>
<svg xmlns="http://www.w3.org/2000/svg" width="200" height="200">
  <circle cx="100" cy="100" r="80" fill="steelblue"/>
</svg>';

->chapter(Chapter::create('Data Visualization', $html))

The library automatically detects SVG content and sets the required properties="svg" in the OPF manifest.

MathML Support

Include mathematical equations using MathML:

$html = '<p>The quadratic formula:</p>
<math xmlns="http://www.w3.org/1998/Math/MathML">
  <mi>x</mi><mo>=</mo>
  <mfrac>
    <mrow><mo>-</mo><mi>b</mi><mo>±</mo><msqrt><mrow><msup><mi>b</mi><mn>2</mn></msup><mo>-</mo><mn>4</mn><mi>a</mi><mi>c</mi></mrow></msqrt></mrow>
    <mrow><mn>2</mn><mi>a</mi></mrow>
  </mfrac>
</math>';

->chapter(Chapter::create('Equations', $html))

Fixed Layout

Create pixel-perfect pages for comics, cookbooks, data dashboards, and children's books:

// Entire book as fixed layout
Epub::create()
    ->metadata(
        Metadata::create('My Cookbook')
            ->fixedLayout(1024, 768)  // width, height in CSS pixels
    )
    ->chapter(Chapter::create('Recipe 1', $htmlWithAbsolutePositioning))
    ->save('cookbook.epub');

Presets are available for common dimensions:

use PhpEpub\Viewport;

Viewport::tablet()          // 1024 × 768
Viewport::tabletPortrait()  // 768 × 1024
Viewport::letter()          // 816 × 1056
Viewport::a4()              // 794 × 1123

For full control over spread and orientation:

use PhpEpub\Layout;
use PhpEpub\Spread;
use PhpEpub\Viewport;

Metadata::create('My Comic')
    ->layout(Layout::PRE_PAGINATED)
    ->viewport(Viewport::tablet())
    ->spread(Spread::LANDSCAPE)   // Two-page spread in landscape
    ->orientation('landscape')     // Prefer landscape reading

Mixed Layout

Combine reflowable and fixed-layout pages in a single book. Useful for a reflowable book with occasional full-page charts or illustrations:

Epub::create()
    ->metadata(Metadata::create('Annual Report'))  // Reflowable by default
    ->chapter(Chapter::create('Introduction', '<p>Text content...</p>'))
    ->chapter(
        Chapter::create('Q4 Dashboard', $svgChartHtml)
            ->layout(Layout::PRE_PAGINATED)
            ->viewport(new Viewport(1024, 768))
    )
    ->chapter(Chapter::create('Conclusion', '<p>More text...</p>'))
    ->save('report.epub');

Accessibility

Include EPUB Accessibility and schema.org metadata:

Metadata::create('My Book')
    ->accessibility(
        accessMode: ['textual', 'visual'],
        accessModeSufficient: ['textual'],
        features: ['structuralNavigation', 'tableOfContents', 'alternativeText'],
        summary: 'This book includes structured headings and alt text for all images.',
        hazards: ['none'],
        conformsTo: 'http://www.idpf.org/epub/a11y/accessibility-20170105.html#wcag-aa',
    )

Resources

Embed images, fonts, and other files:

// From file
->resource(Resource::fromFile('/path/to/image.jpg', 'images/photo.jpg'))

// From string
->resource(Resource::fromString($svgData, 'images/chart.svg'))

Cover Image

->coverImage(Resource::fromFile('/path/to/cover.jpg'))

Output Options

// Save to file
$epub->save('/path/to/book.epub');

// Get raw binary data
$data = $epub->build();

// Write to stream
$epub->writeTo($stream);

Architecture

The library is organized into a public API and internal implementation:

• Public: Epub, Metadata, Chapter, Resource, Semantic, Accessibility
• Internal: Packager, OpfBuilder, NavBuilder, NcxBuilder, XhtmlBuilder, ContainerBuilder, MimeTypes

Internal classes handle the ePub specification details (OPF manifest, ZIP packaging, XHTML wrapping) and should not be used directly.

License

MIT