README

Kiwa Hyphenizer

Perfect hyphenation for your Website. This library integrates the Hyphenizer into your Kiwa website.

If you don't run your website with Kiwa, you can integrate the Hyphenizer SDK for PHP by your own.

Please note: The Hyphenizer API requires you to have a valid API token.

Installation

This library is made for the use with Composer. Add it to your project by running $ composer require kiwa/hyphenizer.

Usage

Basic setup and usage of the Kiwa Hyphenizer library

The Kiwa Hyphenizer library offers a smooth way to extract and hyphenate long words automatically. It implements the Hyphenizer SDK for PHP and allows to update the extracted words.

To use this library in your project, wrap your texts with the AutoHyphenation class. This will add soft hyphens to all words, that are long enough to be hyphenated:

<?php

use Kiwa\Hyphenizer\AutoHyphenation;

echo new AutoHyphenation('Wir suchen nach Bodenseefelchen.');

Inside, the class extracts all words having more than 12 characters, and searches for a previously defined hyphenation. You can change this value when initialising the class.

The hyphenations themselves are stored inside a JSON file using a pipe, for example

{
    "Bodenseefelchen": "Bodensee|felchen"
}

whereas the pipe is getting replaced afterwards by the defined hyphenation character. This is a soft hyphen per default. You can change the hyphenation character when initialising the class.

The JSON file is getting stored under /hyphenation/words-hyphenated.json.

The list of extracted words will grow over time. You can add hyphenations by yourself, by modifying the JSON file, but it's also possibly to do this via script:

<?php

use Kiwa\Hyphenizer\HyphenationLibraryFactory;

HyphenationLibraryFactory::create()->setHyphenationWords([
    'Bodenseefelchen' => 'Bodensee|felchen',
]);

This is the manual approach. The approach that you’ll really enjoy is:

Using the Hyphenation API for automatic hyphenation

This library provides a command, to contact the Hyphenation API and ask for validated hyphenations:

$ vendor/bin/kiwa-hyphenizer hyphenation:list:hyphenate 

Please note: If you're using this library in a project using the kiwa/console, the command is available calling bin/console.

The response will contain more information about every hyphenated word, for example a score and if the hyphenation has been approved. The response will also be stored in the words-hyphenated.json file.

Extracting words manually

If you don't want to wait, until your hyphenation list contains all words from your project, you can manually scan your files and extract the words from there:

$ vendor/bin/kiwa-hyphenizer hyphenation:list:create 

Using the hyphenations with JavaScript

If you want to use the hyphenations in JavaScript, you can use the Hyphenation library written in JavaScript to do that. In this case, you need to import your words-hyphenated.json before initialising the class:

import { Hyphenation } from "kiwa-hyphenizer";
import hyphenatedWords from "hyphenation/words-hyphenated.json";

const hyphenation = new Hyphenation(hyphenatedWords.words);

Help

If you have any questions, feel free to contact us under hello@bitandblack.com.

Further information about Bit&Black can be found under www.bitandblack.com.