README

Bit&Black TypoRules

Typographic improvements for professional-looking and easy-to-read texts written in PHP.

TOC

• Installation
• Usage
  • Using a single rule
  • Using a rule set
• Rules existing
  • Customization
• Rule sets existing
  • Customization
• Display and check changes
• Thanks
• Help

Installation

This library is available for the use with Composer. Add it to your project by running $ composer require bitandblack/typorules.

Usage

The Bit&Black TypoRules library comes with a lot of rules that help achieve a better typography. In addition, there are rule sets providing multiple rules at once.

Using a single rule

A single rule can be used like that:

<?php

use BitAndBlack\TypoRules\Rule\RemoveDuplicatedWhitespaceRule;

$content = 'This is  my    sentence.';

$removeDuplicatedWhitespaceRule = new RemoveDuplicatedWhitespaceRule();

/**
 * This will return a list of all violations, that have been found. 
 * You can use this for more control or an interactive process.
 */
$violations = $removeDuplicatedWhitespaceRule->getViolations($content);

/**
 * This method will return the fixed content. In our example:
 * `This is my sentence.`
 */
$contentFixed = $removeDuplicatedWhitespaceRule->getContentFixed($content);

You can find a similar example under /examples/1-single-rule-without-html.php.

Using a rule set

Using a rule set may look like that:

<?php

use BitAndBlack\TypoRules\RuleSet\EnglishRuleSet;

$content = 'This is  my    - terribly - formatted sentence!!!!!';

$englishRuleSet = new EnglishRuleSet();

/**
 * This will return a list of all violations, that have been found.
 * You can use this for more control or an interactive process.
 */
$violations = $englishRuleSet->getViolations($content);

/**
 * This method will return the fixed content. In our example:
 * `This is my — terribly — formatted sentence!!`
 */
$contentFixed = $englishRuleSet->getContentFixed($content);

You can find a similar example under /examples/2-rule-set.php.

Rules existing

Read more about the existing rules under /docs/rules.md.

Customization

You can create custom rules by creating own classes and implementing the RuleInterface.

If you want to set up a rule completely by your own, you can use the CustomRule class.

Rule sets existing

Read more about the existing rule sets under /docs/rulesets.md.

Customization

You can create custom rule sets by creating own classes and implementing the RuleSetInterface.

You can customize existing rule sets and add or remove rules by using the withRule or withoutRule methods.

If you want to set up an empty rule set completely by your own, you can use the CustomRuleSet class.

Display and check changes

Every rule returns a list of violations, and every violation may tell about the exact position of the violation found.

However, in some cases, you probably want to create an exact diff view. This can be done using the CharacterDiff class. This may look like here:

<?php

use BitAndBlack\TypoRules\Diff\CharacterDiff;

$content = 'Content before';
$contentFixed = 'Content, that has been fixed';

$diff = CharacterDiff::create()->getDiff($content, $contentFixed);

The CharacterDiff class can be initialized with the CliOutput or the HtmlOutput class, and will decide the output format by itself if you don't set up one of those.

Handling UTF-8 and HTML

Per default, this library uses utf-8 characters. In same cases, you may prefer HTML characters instead. This can be changed in rules and rule sets as well by calling the methods preferHtmlOverUtf8Characters() or preferUtf8OverHtmlCharacters().

Thanks

Our thanking goes to the contributors of JoliTypo, that have inspired our development of this library.

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.