MaxtDesign

Developer Guide

Architecture

The plugin uses PHP namespaces (MaxtDesign\PDFViewer) and strict typing (declare(strict_types=1)).

Class Structure

  • Plugin (class-mdpv-plugin.php) — Main plugin class. Orchestrates initialization, hooks, and dependency injection.
  • Renderer (class-mdpv-renderer.php) — Generates HTML output for PDF viewer embeds. Handles preview display and viewer container.
  • Extractor (class-mdpv-extractor.php) — Server-side PDF processing. Preview generation via ImageMagick, metadata extraction, quality presets.
  • Block (class-mdpv-block.php) — Gutenberg block registration and server-side rendering.
  • Settings (class-mdpv-settings.php) — WordPress Settings API integration. Option management with defaults and sanitization.
  • Cache (class-mdpv-cache.php) — Preview metadata caching with configurable TTL.
  • REST_API (class-mdpv-rest-api.php) — REST endpoints for PDF info and processing.
  • Compatibility (class-mdpv-compatibility.php) — Third-party plugin compatibility checks.
  • Admin (admin/class-mdpv-admin.php) — Admin settings page, tabs, and bulk tools.

    • Constants

    MDPV_VERSION          // '1.0.0'
MDPV_PLUGIN_FILE      // Main plugin file path
MDPV_PLUGIN_DIR       // Plugin directory path
MDPV_PLUGIN_URL       // Plugin URL for assets
MDPV_PLUGIN_BASENAME  // Plugin basename for hooks

    Block Attributes

    The Gutenberg block (maxtdesign/pdf-viewer) supports these attributes:

    {
    "pdfId":          { "type": "number", "default": 0 },
    "pdfUrl":         { "type": "string", "default": "" },
    "width":          { "type": "string", "default": "100%" },
    "loadBehavior":   { "type": "string", "default": "click",
                        "enum": ["click", "visible", "immediate"] },
    "showToolbar":    { "type": "boolean", "default": true },
    "showDownload":   { "type": "boolean", "default": true },
    "showPrint":      { "type": "boolean", "default": true },
    "showFullscreen": { "type": "boolean", "default": true }
}

    Supports: align (wide, full), anchor, className, spacing.margin

    Settings Defaults

    Settings::DEFAULTS = [
    'generate_on_upload'    => true,
    'preview_quality'       => 'medium',
    'default_load_behavior' => 'click',
    'default_width'         => '100%',
    'toolbar_download'      => true,
    'toolbar_print'         => true,
    'toolbar_fullscreen'    => true,
    'preload_viewer'        => false,
    'cache_duration'        => 30,  // days
];

    Option stored as: mdpv_settings (single array in wp_options)

    Preview Quality Presets

    Extractor::QUALITY_PRESETS = [
    'low'    => ['resolution' => 72,  'quality' => 70],
    'medium' => ['resolution' => 150, 'quality' => 85],
    'high'   => ['resolution' => 300, 'quality' => 95],
];

    REST API Endpoints

    Namespace: mdpv/v1

    GET /pdf/{id}

    Returns PDF metadata: page count, dimensions, preview URL, file size.

    Permission: upload_files capability.

    POST /pdf/{id}/process

    Triggers preview generation for the specified PDF attachment.

    Permission: upload_files capability.

    Frontend JavaScript

    Loader (`mdpv-loader.js`)

    Intentionally minimal (< 8KB). Handles:

  • Finding viewer containers on the page
  • Managing load behavior triggers (click/visible/immediate)
  • Loading the full PDF.js viewer on demand
  • Error handling and loading state display

    • Configuration injected via wp_localize_script as window.mdpvConfig.

    CSS Classes

    .mdpv-viewer        — Main container
.mdpv-preview       — Preview image wrapper
.mdpv-activate      — Activation button overlay
.mdpv-loading       — Loading indicator
.mdpv-loading-active — Loading state active
.mdpv-active        — Viewer loaded and active
.mdpv-error-container — Error display

    PDF.js Integration

    The plugin bundles PDF.js as a vendor dependency:

  • vendor/pdfjs/pdf.min.mjs — Main library
  • vendor/pdfjs/pdf.worker.min.mjs — Web worker for parsing
  • vendor/pdfjs/cmaps/ — Character maps for CJK fonts

    • PDF.js is loaded on-demand (not on initial page load) via dynamic import.

    Uninstall Behavior

    When the plugin is deleted:

  • Plugin options removed (mdpv_settings)
  • Preview metadata removed from post meta
  • Generated WebP preview files are not deleted (they live in the uploads directory)
  • PDF.js vendor files removed with the plugin
    • FeaturesTroubleshooting