Download the PHP package goodm4ven/arabicable without Composer

بسم الله الرحمن الرحيم

# Arabicable Practical Arabic text processing for Laravel, focused on fast and predictable Arabic search with database-backed searchable variants. [](https://packagist.org/packages/goodm4ven/arabicable) [](https://github.com/goodm4ven/PACKAGE_LARAVEL_arabicable/actions?query=workflow%3Apest+branch%3Adev) [](https://codecov.io/gh/goodm4ven/PACKAGE_LARAVEL_arabicable/tree/dev) [](https://packagist.org/packages/goodm4ven/arabicable) ## Description Arabicable primarily stores Arabic field variants in dedicated database columns, so indexing and querying remain consistent and fast through normal Eloquent workflows. For each Arabicable text column, the package maintains: - `` - `_with_harakat` - `_searchable` - `_stemmed` And all in all, this package provides all of these features:

### Anaylsis and Search

- Generate Arabic-ready database columns and keep searchable variants in sync automatically with [Arabicable model and migration setup](#arabicable-model--migration). - Run exact, like, and relevance-ranked Arabic matching with [search scopes](#search-scopes) and [text processing helpers](#text-processing-helpers). - Build comprehensive query plans using normalization, tokenization, stop-word filtering, stemming, and lexical expansion via [text processing helpers](#text-processing-helpers) and [search scopes](#search-scopes). - Control text with or without harakat and diacritics using the [ArabicFilter facade](#arabicfilter-facade), [Arabic facade common methods](#arabic-facade-common-methods), and [CamelTools facade](#cameltools-facade-pure-php-utility-port). - Normalize letters, punctuation, spacing, and keywords using the [Arabic facade common methods](#arabic-facade-common-methods) and [CamelTools facade](#cameltools-facade-pure-php-utility-port). - Compile and seed local lexical dictionaries for variants and stop-words using the [dictionary workflow](#dictionary-workflow-arabicableraw_data_path). - Use pure-PHP transliteration, mapping, normalization, dediacritization, and tokenization through the [CamelTools facade](#cameltools-facade-pure-php-utility-port).

### Al-Qur'an

- Query Quran data at both ayah and exact word-occurrence levels with [Quran indexing tables](#quran-indexing-tables). - Render Quran text with DigitalKhatt-compatible fonts while searching normalized fields via [DigitalKhatt / Quran font setup](#digitalkhatt--quran-font-setup).

### Date

- Convert dates between Gregorian and Hijri calendars with [Gregorian/Hijri date helpers](#gregorianhijri-date-helpers) and [Arabic facade common methods](#arabic-facade-common-methods).

### Numbers

- Convert numerals between ASCII digits (`123`) and Arabic-Indic digits (`١٢٣`) from backend and browser using [Arabic facade common methods](#arabic-facade-common-methods) and the [JavaScript number helper](#javascript-number-helper).

### Voice

- Add browser speech-to-text, text-to-speech, and voice transforms with the [RunAnywhere STT/TTS companion](#runanywhere-stttts-companion). ## Installation 1. Install via Composer: 2. Run installer: This publishes config + migrations, runs migration (with prompt unless `--testing`), and imports dictionaries when `--seed` is provided. 3. Publish the assets: Raw data resolution defaults are customizable if you wish: - `arabicable.raw_data_path` is auto-resolved from `vendor/goodm4ven/arabicable/resources/raw-data`, then `resources/raw-data`. - You can publish package raw datasets to your app with: ### Upgrading Refresh published package files: If local dictionary sources changed: ## Usage ### Arabicable Model & Migration 1. Add an Arabicable migration macro: 2. Use `Arabicable` trait on your model: Observer-managed columns are now updated automatically when `content` changes: - `$note->content` - `$note->content_with_harakat` - `$note->content_searchable` - `$note->content_stemmed` If using [Spatie Translatable](https://spatie.be/docs/laravel-translatable/v6/introduction), migration macros accept `?bool $isTranslatable`:

### Search Scopes `Arabicable` trait includes: - `scopeSearchArabic` - `scopeWhereArabicLike` - `scopeSearchArabicComprehensive` - `scopeWhereArabicComprehensive` - `scopeOrderByArabicRelevance` Example: Comprehensive mode builds terms from: - normalized query text - tokens - stop-word removal - stems - lexical variants (`roots`, `stems`, `original_words`, or `all`) ### Text Processing Helpers ### ArabicFilter Facade - `withHarakat(string $text): string` - `withoutHarakat(string $text): string` - `withoutDiacritics(string $text, bool $keepShadda = false): string` - `forSearch(string $text): string` - `forStem(string $text): string` - `forMemorizationComparison(string $text, bool $stripCommons = true, bool $stripConnectors = true): string` ### Arabic Facade (Common Methods) - Harakat/diacritics: `removeHarakat`, `removeDiacritics`, `addHarakat` - Normalization: `normalizeHuroof`, `normalizeNumeralsForSearch`, `stripWeirdCharacters` - Keywords/search: `tokenize`, `stemWord`, `stemWords`, `removeStopWords`, `extractKeywords`, `buildComprehensiveSearchPlan`, `expandWordVariants` - Commons/cache: `removeCommons`, `clearConceptCache` - Punctuation/spacing: `toTightPunctuationStyle`, `toLoosePunctuationStyle`, `removeAllPunctuationMarks`, `normalizeSpaces` - Date conversion: `gregorianToHijri`, `hijriToGregorian` ### Quran Indexing Tables Enable Quran features in config when needed: After running migrations, Arabicable creates and imports: - `quran_verses`: one row per ayah with `surah_number`, `ayah_number`, `ayah_index`, `text_uthmani`, `text_searchable`, `text_sanitized`, `text_without_harakat`, `text_without_diacritics`, `text_normalized_huroof`. - `quran_words`: one row per word occurrence with `verse_id`, `word_position`, `global_word_index`, `token_uthmani`, `token_sanitized`, `token_searchable`, `token_without_harakat`, `token_without_diacritics`, `token_normalized_huroof`, `token_stem`, `token_root`, `token_lemma`. - `quran_verse_explanations`: ayah-linked tafsir/i'rab records from SQLite sources (`source_key`, `content_kind`, `content_html`, `content_text`). - `quran_word_annotations`: optional word-level notes/translation payloads linked to exact `quran_words` rows. For repeat words, target the occurrence with: - `verse_id + word_position` for stable position inside ayah. - `global_word_index` for a single canonical word pointer across the full Quran. This structure is ready for later tafsir/translation attachments at ayah level or exact word occurrence level. Default source config keys: - `arabicable.raw_data_path` - `arabicable.data_sources.quran_othmani_surahs_dir` - `arabicable.data_sources.quran_exegesis_databases_dir` - `arabicable.data_sources.quran_layout_databases_dir` - `arabicable.data_sources.quran_lexicon_databases_dir` - `arabicable.data_sources.quran_fonts_dir` - `arabicable.data_sources.quran_surah_headers_fonts_dir` For tafsir / i'rab SQLite data: - Put files like `ar-tafsir-al-tabari.db` and `al-i-rab-al-muyassar.db` in `/quran/exegesis`. - Keep required exegesis SQLite files inside `/quran/exegesis` (or your configured data source path). - Explanations are stored for display and retrieval, and are not part of Arabicable search indexing. ### Gregorian/Hijri Date Helpers ### JavaScript Number Helper Published asset: `public/vendor/arabicable/arabicable.js` ### DigitalKhatt / Quran Font Setup Arabicable can be paired with DigitalKhatt-style Quran rendering in your app frontend. 1. Publish package assets (and optionally Quran raw-data files if you want app-local copies): 2. Use the included Quran font file (published under `public/vendor/arabicable/madina.woff2`), or replace it with your preferred DigitalKhatt-compatible font build. Surah header fonts are also bundled and available in both locations: - `resources/raw-data/quran/fonts/surah-headers/QCF_SurahHeader_COLOR-Regular.woff2` - `resources/raw-data/quran/fonts/surah-headers/surah-name-v2.woff2` - `public/vendor/arabicable/QCF_SurahHeader_COLOR-Regular.woff2` - `public/vendor/arabicable/surah-name-v2.woff2` 3. Define your Quran text class: 4. Render Uthmani text with `.font-quran`, while using `text_searchable`/`token_searchable` fields for search queries. 5. Optional package config for surah header font selection: If you integrate the external `digitalkhatt.js` stack, keep Arabicable as the search/index layer and use DigitalKhatt purely for display shaping. ### RunAnywhere STT/TTS Companion Install frontend packages: Initialize and register your bridge: Bridge API methods: - `speechToText(audioInput, options)` - `textToSpeech(text, options)` - `voiceToText(audioInput, options)` - `textToVoice(text, options)` - `voiceToVoice(audioInput, options)` - `transformArabic({ text, audio, target }, options)` - `decodeAudioBlob(blob, targetSampleRate?)` - `playFloat32Audio(audio, sampleRate?)` - `playAudio(result)` ### Dictionary Workflow (`arabicable.raw_data_path`) `compiled-*` files are runtime dictionaries. `source-*` files are local raw assets. Compile: Seed DB dictionaries: Current DB imports: - `common_arabic_texts` - `arabic_stop_words` Current file-backed lexical expansion sources: - `/verbs/compiled-word-variants.tsv` - `/quran/compiled-quran-word-index.tsv` All source paths are configurable via `config/arabicable.php` using: - `arabicable.raw_data_path` (global base path) - `arabicable.data_sources.*` (per-file/per-directory overrides) ## API ### Validation Rules - `GoodMaven\Arabicable\Rules\Arabic` - `GoodMaven\Arabicable\Rules\ArabicWithSpecialCharacters` - `GoodMaven\Arabicable\Rules\UncommonArabic` - `GoodMaven\Arabicable\Rules\UniqueArabicWithSpecialCharacters` ### Artisan Commands | Command | Purpose | |---|---| | `arabicable:install` | Publish config/migrations, migrate, optional seed (`--testing`, `--seed`) | | `arabicable:compile-data` | Compile local datasets (`--raw-data-path`, `--without-extra-stopwords`) | | `arabicable:seed` | Import configured dictionaries (`--all`, `--common-texts`, `--stop-words`, `--truncate`) | ### Migration Macros | Macro | Purpose | |---|---| | `indianDate($columnName, $isNullable = false, $isUnique = false)` | Creates date column and `_indian` | | `arabicString($columnName, $length = 255, $isNullable = false, $isUnique = false, $supportsFullSearch = false, $isTranslatable = null)` | String + Arabicable variant columns | | `arabicTinyText($columnName, $isNullable = false, $isUnique = false, $supportsFullSearch = false, $isTranslatable = null)` | TinyText + variants | | `arabicText($columnName, $isNullable = false, $isUnique = false, $isTranslatable = null)` | Text + variants | | `arabicMediumText($columnName, $isNullable = false, $isUnique = false, $isTranslatable = null)` | MediumText + variants | | `arabicLongText($columnName, $isNullable = false, $isUnique = false, $isTranslatable = null)` | LongText + variants | ### Global Functions - `ar_indian(string $property): string` - `ar_with_harakat(string $property): string` - `ar_searchable(string $property): string` - `ar_stem(string $property): string` - `ar_expand_variants(...)` - `arabicable_special_characters(...)` - `camel_tools()` and `camel_*` helpers ### CamelTools Facade (Pure-PHP Utility Port) Key utilities: - Builtin mapping/transliteration: `mapWithBuiltin`, `transliterateWithBuiltin`, `arclean` - Unicode/orthographic normalization: `normalizeUnicode`, `normalizeAlef*`, `normalizeAlefMaksura*`, `normalizeTehMarbuta*`, `normalizeOrthography` - Dediacritization: `dediac*` - Tokenization: `simpleWordTokenize` ## Contribution - Always target `dev` branch for your PRs. ## License This package is open-sourced software licensed under the [MIT license](LICENSE.md). ## Credits - Youssif Shaaban Alsager ([yshalsager](https://github.com/yshalsager)) - [Linuxscout](https://github.com/linuxscout) - [CAMeL Tools](https://github.com/CAMeL-Lab/camel_tools) - [ar-php](https://github.com/khaled-alshamaa/ar-php) - [Qul by Tarteel](https://qul.tarteel.ai/resources) - [Nuqaya](https://github.com/nuqayah)

والحمد لله رب العالمين