包简介

Interfaces for building PHP classes that lets to easier make web editor integrations in your content management systems

README 文档

README

PHP interfaces and contracts for integrating web editors into content management systems. Defines common interfaces for editor adapters, factories, and metadata to standardize how different editor types (WYSIWYG, source code editors) are implemented and used.

📦 Installation

Install the package via Composer:

composer require imponeer/editor-contracts

🏗️ Architecture Overview

This library follows a clean architecture pattern with the following key components:

Core Interfaces

EditorAdapterInterface - Main contract for renderable editor instances
EditorFactoryInterface - Factory pattern for creating editor instances
EditorInfoInterface - Base contract for editor metadata and capabilities
SourceEditorInfoInterface - Extended contract for source code editors
WYSIWYGEditorInfoInterface - Extended contract for WYSIWYG editors

Exception Handling

IncompatibleEditorException - Thrown when editor configuration validation fails

🚀 Usage Examples

Implementing an Editor Adapter

use Imponeer\Contracts\Editor\Adapter\EditorAdapterInterface;

class MyCustomEditor implements EditorAdapterInterface
{
    public function getAttributes(): array
    {
        return [
            'id' => 'my-editor',
            'class' => 'custom-editor',
            'data-editor' => 'my-custom-editor'
        ];
    }

    public function getStyleURLs(): array
    {
        return [
            'https://cdn.example.com/editor/styles.css',
            '/assets/custom-editor.css'
        ];
    }

    public function getScriptURLs(): array
    {
        return [
            'https://cdn.example.com/editor/editor.min.js'
        ];
    }

    public function getScriptCode(): string
    {
        return 'MyEditor.init("my-editor", {theme: "modern"});';
    }

    public function __toString(): string
    {
        return '<textarea id="my-editor" class="custom-editor"></textarea>';
    }
}

Creating an Editor Factory

use Imponeer\Contracts\Editor\Factory\EditorFactoryInterface;
use Imponeer\Contracts\Editor\Adapter\EditorAdapterInterface;
use Imponeer\Contracts\Editor\Info\EditorInfoInterface;
use Imponeer\Contracts\Editor\Exceptions\IncompatibleEditorException;

class MyEditorFactory implements EditorFactoryInterface
{
    public function getInfo(): EditorInfoInterface
    {
        return new MyEditorInfo();
    }

    public function create(array $config, bool $checkCompatible = false): EditorAdapterInterface
    {
        if ($checkCompatible && !$this->isConfigValid($config)) {
            throw new IncompatibleEditorException('Invalid configuration provided');
        }

        return new MyCustomEditor($config);
    }

    private function isConfigValid(array $config): bool
    {
        // Implement your validation logic
        return isset($config['theme']) && is_string($config['theme']);
    }
}

Implementing Editor Info

use Imponeer\Contracts\Editor\Info\WYSIWYGEditorInfoInterface;

class MyEditorInfo implements WYSIWYGEditorInfoInterface
{
    public function getName(): string
    {
        return 'My Custom WYSIWYG Editor';
    }

    public function isAvailable(): bool
    {
        // Check if editor assets are available
        return file_exists('/path/to/editor/assets');
    }

    public function getVersion(): string
    {
        return '1.0.0';
    }

    public function getLicense(): string
    {
        return 'MIT';
    }
}

Using in Your Application

// Create factory
$factory = new MyEditorFactory();

// Get editor info
$info = $factory->getInfo();
echo "Editor: " . $info->getName() . " v" . $info->getVersion();

// Create editor instance
$config = ['theme' => 'dark', 'toolbar' => 'full'];
$editor = $factory->create($config, true);

// Render in your template
echo '<html><head>';
foreach ($editor->getStyleURLs() as $styleUrl) {
    echo '<link rel="stylesheet" href="' . $styleUrl . '">';
}
echo '</head><body>';

echo $editor; // Renders the editor HTML

foreach ($editor->getScriptURLs() as $scriptUrl) {
    echo '<script src="' . $scriptUrl . '"></script>';
}
echo '<script>' . $editor->getScriptCode() . '</script>';
echo '</body></html>';

🔧 Development

Code Quality Tools

This project uses several tools to maintain code quality:

PHP CodeSniffer (PSR-12 compliance)

composer phpcs

Fix coding standard violations

composer phpcbf

PHPStan static analysis (level max)

composer phpstan

Testing

The project includes GitHub Actions CI/CD pipeline that:

Tests on multiple PHP versions
Validates composer.json
Runs code style checks
Performs static analysis

API Documentation

For detailed API documentation, please visit the Wiki.

🤝 Contributing

We welcome contributions! Here's how you can help:

Getting Started

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Run code quality checks: composer phpcs && composer phpstan
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Guidelines

Follow PSR-12 coding standards
Add PHPDoc comments for all public methods
Ensure PHPStan level max compliance
Write clear commit messages
Update documentation if needed

Reporting Issues

Found a bug or have a suggestion? Please use the issues tab to:

Report bugs with detailed reproduction steps
Suggest new features or improvements
Ask questions about usage

imponeer/editor-contracts 适用场景与选型建议

imponeer/editor-contracts 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 19.46k 次下载、GitHub Stars 达 0，最近一次更新时间为 2021 年 10 月 12 日，在 PHP 生态内属于活跃度较高的组件。

我们在过去多个企业项目中使用过 imponeer/editor-contracts 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 imponeer/editor-contracts 我们能提供哪些服务？

定制开发 / 二次开发

基于 imponeer/editor-contracts 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

imponeer/editor-contracts

包简介