Upgrade from 1.0 to 2.0

• Breaking Changes
  • Tag & render method (High Impact)
  • Node & mark name changes (High Impact)
  • Mutator node and mark methods removed (Low Impact)
• Deprecated
  • Tag Mutators

Bard Mutator 2 integrates with the new tiptap-php library in Statamic 3.4, which works differently from the previous version. As Bard Mutator provides low-level access to the Tiptap rendering process it also works differently now. There are two high-impact breaking changes, and a core feature has been deprecated and replaced with a new version.

#Breaking Changes

#Tag & render method (High Impact)

The {{ bmu }} tag and Mutator::render() method have been removed in favour of binding Bard Mutator's Editor class. This allows all advanced features to just work without the need to use a custom tag and within API responses. If you were using these you should bind the new class, remove those calls and just output your Bard values in the usual Statamic way.

#Node & mark name changes (High Impact)

Some node and mark names have changed in Tiptap 2. The table below lists the affected names, which you’ll need to update if you’re using them:

#Mutator node and mark methods removed (Low Impact)

The previously deprecated Mutator:node() and Mutator:mark() methods have been removed. You can use Mutator:tag() instead, but see the notes below.

#Deprecated

#Tag Mutators

Tag rendering isn’t the same in Tiptap PHP. Bard Mutator 2 includes a compatibility layer that maintains support for tag mutators, but these are deprecated and may be removed in a future version.

HTML mutators replace tag mutators. They work in a similar way but the data format is different. Below is an example of a tag mutator converted to an HTML mutator.

Mutator::tag('heading', function ($tag) {
    $tag[0]['attrs']['class'] = 'heading';
    return $tag;
});
Mutator::tag('heading', function ($tag) {
    $tag[0]['attrs']['class'] = 'heading';
    return $tag;
});

Mutator::html('heading', function ($value) {
    $value[1]['class'] = 'heading';
    return $value;
});
Mutator::html('heading', function ($value) {
    $value[1]['class'] = 'heading';
    return $value;
});