public/AllinSSL

Fork 0

mirror of https://gitee.com/mirrors/AllinSSL.git synced 2026-03-08 07:41:10 +08:00

Files

cai 367c1a1096 【调整】增加部署雨云

2026-01-13 17:47:39 +08:00

7.1 KiB

Raw Blame History

Design Document

Overview

The Vite HTML to PHP Template plugin is a post-build transformation tool that converts standard HTML files into PHP template format. The plugin integrates with Vite's build lifecycle, executing after the build process completes to perform secondary transformations on generated HTML files. It uses HTML parsing to extract specific content sections and reorganizes them into a structured PHP template format compatible with template engines like ThinkPHP.

Architecture

Plugin Architecture

The plugin follows Vite's plugin architecture pattern and implements the following hooks:

closeBundle: Executes after the build is complete and all files are written
buildEnd: Fallback hook for error handling and cleanup

Core Components

vite-plugin-html-to-php-template/
├── src/
│   ├── index.ts              # Main plugin entry point
│   ├── parser.ts             # HTML parsing and content extraction
│   ├── template-generator.ts # PHP template generation
│   ├── file-processor.ts     # File system operations
│   └── types.ts              # TypeScript type definitions
├── package.json
├── tsconfig.json
└── README.md

Components and Interfaces

Plugin Interface

interface PluginOptions {
  // Input directory containing HTML files (default: 'dist')
  inputDir?: string;
  
  // Output directory for PHP templates (default: same as inputDir)
  outputDir?: string;
  
  // Glob pattern for HTML files to process (default: '**/*.html')
  include?: string | string[];
  
  // Glob pattern for files to exclude (default: [])
  exclude?: string | string[];
  
  // Template configuration
  template?: {
    extend?: string;           // Default: 'main/newMain'
    blocks?: BlockConfig;      // Block name mappings
    footer?: string;           // Default: 'footer2'
  };
  
  // Processing options
  preserveOriginal?: boolean;  // Keep original HTML files (default: false)
  encoding?: string;          // File encoding (default: 'utf-8')
}

interface BlockConfig {
  title?: string;      // Default: 'title'
  keywords?: string;   // Default: 'keywords'
  description?: string; // Default: 'description'
  csslink?: string;    // Default: 'csslink'
  main?: string;       // Default: 'main'
  script?: string;     // Default: 'script'
}

HTML Parser Interface

interface ParsedContent {
  title: string;
  keywords: string;
  description: string;
  stylesheets: string[];
  scripts: string[];
  bodyContent: string;
}

interface ParserOptions {
  preserveComments?: boolean;
  minifyContent?: boolean;
}

Template Generator Interface

interface TemplateConfig {
  extend: string;
  blocks: BlockConfig;
  footer: string;
}

interface GeneratedTemplate {
  content: string;
  blocks: {
    [key: string]: string;
  };
}

Data Models

HTML Content Extraction Model

The parser extracts content using the following mapping:

Title: <title> element text content
Keywords: <meta name="keywords" content="..."> attribute value
Description: <meta name="description" content="..."> attribute value
Stylesheets: All <link rel="stylesheet" ...> elements (complete tags)
Scripts: All <script> elements with type="text/javascript" or type="module" (complete tags)
Body Content: Complete innerHTML of <body> element

PHP Template Structure Model

<!-- 引入公共 -->
{extend name="main/newMain"/}
<!-- 标题 -->
{block name="title"}[TITLE_CONTENT]{/block}
<!-- 关键字 -->
{block name="keywords"}[KEYWORDS_CONTENT]{/block}
<!-- 描述 -->
{block name="description"}[DESCRIPTION_CONTENT]{/block}
<!-- 自定义css -->
{block name="csslink"}
[STYLESHEET_LINKS]
{/block}
<!-- 主体内容 -->
{block name="main"}
[BODY_CONTENT]
{/block}
<!-- 自定义js -->
{block name="script"}
[SCRIPT_TAGS]
{/block}

<!-- 底部 -->
{block name="footer2"}{/block}

Error Handling

Error Categories

File System Errors
- File not found
- Permission denied
- Disk space issues
HTML Parsing Errors
- Malformed HTML
- Missing required elements
- Encoding issues
Template Generation Errors
- Invalid template configuration
- Content encoding issues

Error Handling Strategy

class PluginError extends Error {
  constructor(
    message: string,
    public code: string,
    public file?: string,
    public cause?: Error
  ) {
    super(message);
    this.name = 'ViteHtmlToPhpPluginError';
  }
}

// Error codes
enum ErrorCodes {
  FILE_NOT_FOUND = 'FILE_NOT_FOUND',
  PARSE_ERROR = 'PARSE_ERROR',
  TEMPLATE_ERROR = 'TEMPLATE_ERROR',
  CONFIG_ERROR = 'CONFIG_ERROR'
}

Recovery Mechanisms

Graceful Degradation: Continue processing other files when one fails
Detailed Logging: Provide file paths and line numbers in error messages
Validation: Validate configuration and input files before processing
Rollback: Option to preserve original files during processing

Testing Strategy

Unit Tests

HTML Parser Tests
- Test extraction of each content type
- Test handling of missing elements
- Test malformed HTML scenarios
- Test different HTML structures
Template Generator Tests
- Test PHP template generation
- Test custom block configurations
- Test content escaping and encoding
- Test template structure validation
File Processor Tests
- Test file reading/writing operations
- Test glob pattern matching
- Test directory creation
- Test error handling

Integration Tests

Plugin Integration
- Test with Vite build process
- Test with different Vite configurations
- Test with various HTML structures
- Test error scenarios in build context
End-to-End Tests
- Test complete HTML to PHP conversion
- Test with real-world HTML files
- Test configuration variations
- Test performance with large files

Test Data

Create test fixtures with:

Simple HTML files
Complex HTML with multiple scripts/styles
Malformed HTML files
HTML files with missing elements
HTML files with special characters
Large HTML files for performance testing

Implementation Considerations

Performance

Streaming: Use streaming for large files
Parallel Processing: Process multiple files concurrently
Memory Management: Avoid loading entire files into memory when possible
Caching: Cache parsed templates for repeated builds

Security

Path Traversal: Validate file paths to prevent directory traversal
Content Sanitization: Ensure extracted content doesn't contain malicious code
File Permissions: Respect file system permissions

Compatibility

Node.js Versions: Support Node.js 16+
Vite Versions: Support Vite 4+ and 5+
HTML Standards: Support HTML5 and XHTML
Encoding: Support UTF-8 and other common encodings

Extensibility

Plugin Hooks: Allow custom processing hooks
Template Customization: Support custom template formats
Content Processors: Allow custom content transformation functions
Output Formats: Support different template engine formats

7.1 KiB Raw Blame History