PHP-Spellchecker
Check misspellings from any text source with the most popular PHP spellchecker.
About
PHP-Spellchecker is a spellchecker abstraction library for PHP. By providing a unified interface for many different spellcheckers, you’re able to swap out spellcheckers without extensive rewrites.
Using PHP-Spellchecker can eliminate vendor lock-in, reduce technical debt, and improve the testability of your code.
Features
-
🧐 Supports many popular spellcheckers out of the box: Aspell, Hunspell, Ispell, PHP Pspell, LanguageTools, JamSpell and MultiSpellchecker (add yours!) -
📄 Supports different text sources: file system file/directory, string, and multi-source (add yours!) -
🛠 Supports text processors: MarkdownRemover (add yours!) -
🔁 Supports misspelling handlers: EchoHandler (add yours!) -
➰ Makes use of generators to reduce memory footprint -
⚖ Flexible and straightforward design -
💡 Makes it a breeze to implement your own spellcheckers, text processors and misspellings handlers -
💪 Runs tests against real spellcheckers to ensure full compatibility
PHP-Spellchecker is a welcoming project for new contributors.
Want to make your first open source contribution? Check the roadmap, pick one task, open an issue and we'll help you go through it
Install
Via Composer
$ composer require tigitz/php-spellchecker
Usage
Check out the documentation and examples
Using the spellchecker directly
You can check misspellings directly from a PhpSpellCheck\SpellChecker class and process them on your own.
<?php
// if you made the default aspell installation on you local machine
$aspell = Aspell::create();
// or if you want to use binaries from Docker
$aspell = new Aspell(new CommandLine(['docker','run','--rm', '-i', 'starefossen/aspell']));
$misspellings = $aspell->check('mispell', ['en_US'], ['from_example']);
foreach ($misspellings as $misspelling) {
$misspelling->getWord(); // 'mispell'
$misspelling->getLineNumber(); // '1'
$misspelling->getOffset(); // '0'
$misspelling->getSuggestions(); // ['misspell', ...]
$misspelling->getContext(); // ['from_example']
}
Using the MisspellingFinder orchestrator
You can also use an opinionated MisspellingFinder class to orchestrate your spellchecking flow:
Following the well-known Unix philosophy:
Write programs that do one thing and do it well. Write programs to work together. Write programs to handle text streams, because that is a universal interface.
<?php
// My custom text processor that replaces "_" by " "
$customTextProcessor = new class implements TextProcessorInterface
{
public function process(TextInterface $text): TextInterface
{
$contentProcessed = str_replace('_', ' ', $text->getContent());
return $text->replaceContent($contentProcessed);
}
};
$misspellingFinder = new MisspellingFinder(
Aspell::create(), // Creates aspell spellchecker pointing to "aspell" as it's binary path
new EchoHandler(), // Handles all the misspellings found by echoing their information
$customTextProcessor
);
// using a string
$misspellingFinder->find('It\'s_a_mispelling', ['en_US']);
// word: mispelling | line: 1 | offset: 7 | suggestions: mi spelling,mi-spelling,misspelling | context: []
// using a TextSource
$inMemoryTextProvider = new class implements SourceInterface
{
public function toTexts(array $context): iterable
{
yield new Text('my_mispell', ['from_source_interface']);
// t() is a shortcut for new Text()
yield t('my_other_mispell', ['from_named_constructor']);
}
};
$misspellingFinder->find($inMemoryTextProvider, ['en_US']);
//word: mispell | line: 1 | offset: 3 | suggestions: mi spell,mi-spell,misspell,... | context: ["from_source_interface"]
//word: mispell | line: 1 | offset: 9 | suggestions: mi spell,mi-spell,misspell,... | context: ["from_named_constructor"]
Roadmap
The project is still in its initial phase, requiring more real life usage to stabilize its final 1.0.0 API.
Global
- Add a CLI that could do something like
vendor/bin/php-spellchecker "misspell" Languagetools EchoHandler --lang=en_US - Add asynchronous mechanism to spellcheckers.
- Make some computed misspelling properties optional to improve performance for certain use cases (e.g., lines and offset in
LanguageTools). - Add a language mapper to manage different representations across spellcheckers.
- Evaluate
strtokinstead ofexplodeto parse lines of text, for performance. - Evaluate
MutableMisspellingfor performance comparison. - Wrap
Webmozart/Assertlibrary exceptions to throw PHP-Spellchecker custom exceptions instead. - Improve the
Makefile.
Sources
- Make a
SourceInterfaceclass that's able to have an effect on the used spellchecker configuration. -
League/Flysystemsource. -
Symfony/Findersource.
Text processors
- Markdown - Find a way to keep original offset and line of words after stripping.
- Add PHPDoc processor.
- Add HTML Processor (inspiration).
- Add XLIFF Processor (inspiration).
Spell checkers
- Cache suggestions of already spellchecked words (PSR-6/PSR-16?).
- Pspell - Find way to compute word offset.
- LanguageTools - Evaluate HTTPlug library to make API requests.
- Pspell - find way to list available dictionaries.
- Add JamSpell spellchecker.
- Add NuSpell spellchecker.
- Add SymSpell spellchecker.
- Add Yandex.Speller API spellchecker.
- Add Bing Spell Check API spellchecker.
Handlers
- MonologHandler
- ChainedHandler
- HTMLReportHandler
- XmlReportHandler
- JSONReportHandler
- ConsoleTableHandler
Tests
- Add or improve tests with different text encoding.
- Refactor duplicate Dockerfile content between PHP images.
Versioning
We follow SemVer v2.0.0.
There still are many design decisions that should be confronted with real-world usage before thinking about a v1.0.0 stable release:
- Are
TextInterfaceandMisspellingInterfacereally useful? - Is using generators the right way to go?
- Should all the contributed spellcheckers be maintained by the package itself?
- How to design an intuitive CLI given the needed flexibility of usage?
- Is the "context" array passed through all the layers the right design to handle data sharing?
Testing
Spell checkers come in many different forms, from HTTP API to command line tools. PHP-Spellchecker wants to ensure real-world usage is OK, so it contains integration tests. To run these, spellcheckers need to all be available during tests execution.
The most convenient way to do it is by using Docker and avoid polluting your local machine.
Docker
Requires docker and docker-compose to be installed (tested on Linux).
$ make build # build container images
$ make setup # start spellcheckers container
$ make tests-dox
You can also specify PHP version, dependency version target and if you want coverage. Coverage is only supported by PHP 7.2 for now.
$ PHP_VERSION=7.2 DEPS=LOWEST WITH_COVERAGE="true" make tests-dox
Run make help to list all available tasks.
Locally
Todo
Environment variables
If spellcheckers execution paths are different than their default values (e.g., docker exec -ti myispell instead of ispell) you can override the path used in tests by redefining environment variables in the PHPUnit config file.
Contributing
Please see CONTRIBUTING.
Credits
- Inspired by php-speller, monolog and flysystem
- Philippe Segatori
- All Contributors
License
The MIT License (MIT). Please see license file for more information.
Logo: Elements taken for the final rendering are Designed by rawpixel.com / Freepik.
![fix([ia]spell): prevent interpretation of ispell pipe-mode instructio…](https://avatars.githubusercontent.com/u/97545758?v=4)
136 Sep 29, 2022
3 Apr 11, 2022
31 Jun 23, 2020
44k Jan 3, 2023
227 Nov 6, 2022
23 Dec 17, 2022
6 Jul 15, 2022
281 Jan 2, 2023
2.6k Dec 30, 2022
95 Oct 26, 2022
656 Jan 4, 2023
14 Jun 10, 2022
2 Nov 23, 2021
0 Jul 2, 2022
717 Dec 15, 2022
17.7k Jan 8, 2023
66 Oct 17, 2022