Highlighter#withGutter() should be a real "wither"

[Kocal]

Hi,

First let me thank you and every contributors for this package. I first went with Shiki.js for code-highlighting in the browser, but I found that was not so much performant for my needs, too much JavaScript was loaded, and I suspect it badly impacted the page interactivity. To me, a server-based solution is so much better because I can use HTTP cache for more optimisation! :)

---

I've just found Highlighter#withGutter() is in fact not a real "wither" , even if its name starts with with.

"Wither" methods are special methods that clones the object, mutate it, and returns the cloned object, this way the original object stays untouched. We can find many exemples in the PHP ecosystem:

• doctrine/orm: https://github.com/doctrine/dbal/blob/4.0.x/src/Query/Expression/CompositeExpression.php#L60-L67
• symfony/var-dumper: https://github.com/symfony/var-dumper/blob/7.0/Cloner/Data.php#L171-L212
• symfony/web-link: https://github.com/symfony/web-link/blob/7.0/Link.php#L184-L222
• thephpleague/flysystem: https://github.com/thephpleague/flysystem/blob/3.x/src/Config.php#L33-L56
• etc...

So we have two solutions:

1. Either make it a real wither, the object is cloned, modified, and returned
2. Either we rename the method to enableGutter, or something else that will says to users "this will not returns a new object".

In both cases, to not introduce breaking changes, we can trigger a deprecation that will be removed in the next major version (like Symfony does).

WDYT?

[brendt]

Agree on with being confusing. I'm already working on a v2 branch, so I'll include it in there :)

[brendt]

Prepared in v2: #93

[Kocal]

Perfect, thanks :)