storyblok/php-tiptap-extension

Tiptap extension to render Storyblok's RichText field

1.0.1 2025-03-26 16:22 UTC

Requires

• php: >=8.3
• thecodingmachine/safe: ^2.0 || ^3.0
• ueberdosis/tiptap-php: ^1.4

Requires (Dev)

• ergebnis/composer-normalize: ^2.2
• ergebnis/data-provider: ^3.2
• ergebnis/php-cs-fixer-config: ^6.28
• ergebnis/test-util: ^1.5
• phpstan/extension-installer: ^1.0
• phpstan/phpstan: ^1.0
• phpstan/phpstan-webmozart-assert: ^1.0
• phpunit/phpunit: ^9.0
• thecodingmachine/phpstan-safe-rule: ^1.0

MIT

• Edoardo Dusi
• Silas Joisten

README

Storyblok PHP Tiptap Extension

Co-created with SensioLabs, the creators of Symfony.

This library provides Tiptap extensions for Storyblok’s RichText field, enabling seamless integration with the Tiptap for PHP library.

Branch	PHP	Code Coverage
main

Installation

Ensure Composer is installed globally. If not, follow the Composer installation guide.

Install via Composer

Run the following command in your project directory to install the latest stable version:

composer require storyblok/php-tiptap-extension

Usage

This package provides a Storyblok extension for Tiptap for PHP.

Basic Example

You need to create an Editor instance and add the Storyblok extension:

use Tiptap\Editor;
use Storyblok\Tiptap\Extension\Storyblok;

$editor = new Editor([
    'extensions' => [
        new Storyblok(),
    ],
]);

$editor->setContent(['type' => 'doc', 'content' => [['type' => 'paragraph', 'content' => [['type' => 'text', 'text' => 'Hello World']]]]);

echo $editor->getHTML();

Custom Block Rendering

You can customize how Storyblok blocks are rendered using the blokOptions configuration.

Example: Rendering a Custom Heading Block

use Tiptap\Editor;
use Storyblok\Tiptap\Extension\Storyblok;

$editor = new Editor([
    'extensions' => [
        new Storyblok([
            'blokOptions' => [
                'renderer' => function(array $value): string {
                    if ($value['component'] === 'custom_block_heading') {
                        return '<h1 class="red">' . htmlspecialchars($value['text']) . '</h1>';
                    }

                    return '';
                },
            ]
        ]),
    ],
]);

$editor->setContent(['type' => 'doc', 'content' => [['type' => 'paragraph', 'content' => [['type' => 'text', 'text' => 'Hello World']]]]);

echo $editor->getHTML();

Disabling Specific Extensions

You can disable specific Tiptap extensions within Storyblok.

Example: Disabling codeBlock and heading

use Tiptap\Editor;
use Storyblok\Tiptap\Extension\Storyblok;

$editor = new Editor([
    'extensions' => [
        new Storyblok([
            'extensions' => [
                'codeBlock' => false,
                'heading' => false,
            ]
        ]),
    ],
]);

$editor->setContent(['type' => 'doc', 'content' => [['type' => 'paragraph', 'content' => [['type' => 'text', 'text' => 'Hello World']]]]);

echo $editor->getHTML();

For a complete list of enabled extensions by default, check out Storyblok\Tiptap\Extension\Storyblok.

License

This library is licensed under the MIT License. See the full license in the LICENSE file.

Acknowledgments

This library is built upon the Tiptap editor and the official Tiptap for PHP library.

Special thanks to SensioLabs for assisting with the initial implementation of the bundle.

Additional Resources

• Storyblok Documentation
• Tiptap Documentation
• Tiptap for PHP