The package is a thin wrapper around a bundled Quran dataset, so the install is the usual two-step Composer + publish flow:
composer require wearedevtical/laravel-quran
php artisan vendor:publish --provider="WeAreDevtical\LaravelQuran\QuranServiceProvider"
Then look at what was actually published before writing any code. Depending on the release, you'll either get a config file (config/quran.php), migrations + a seeder, or a pre-built SQLite file the package registers as its own connection. Run php artisan vendor:publish with no arguments and read the tag list — that's the fastest way to see whether this package expects you to migrate/seed or whether it just ships data. If there's a console command in src/Console, run php artisan list | grep -i quran; that's almost certainly the intended bootstrap path.
Where to look first, in order:
config/quran.php — translation selection, connection name, and any model-swap keys live here.src/Models/ — the model class names and which table/connection they bind to.database/ — migrations, seeders, or the shipped .sqlite file.First use case — a single-surah reader. The idiomatic call is a static model lookup:
use WeAreDevtical\LaravelQuran\Models\Surah;
$surah = Surah::with('ayahs')->where('number', 1)->firstOrFail();
<h1>{{ $surah->name }}</h1>
@foreach ($surah->ayahs as $ayah)
<p class="ayah" dir="rtl">{{ $ayah->text }}</p>
<p class="translation">{{ $ayah->translation }}</p>
@endforeach
Verify the column names (number vs id vs surah_id, text vs arabic) against the migration or the model's $fillable before you build anything on top. That single check saves the most time.
Wrap it in a repository from day one. The package is small and hasn't shipped since 2021, so the highest-value pattern is isolating the vendor namespace behind one class:
final class QuranRepository
{
public function surah(int $number): Surah
{
return Cache::rememberForever(
"quran.surah.{$number}",
fn () => Surah::with('ayahs')->where('number', $number)->firstOrFail()
);
}
}
Controllers and Blade components then depend on QuranRepository, not on WeAreDevtical\.... If you ever swap to a fork or x-wilayah/quran, you rewrite one file.
Cache aggressively. The dataset is immutable — there is no write path in normal usage. Treat every surah as a permanent cache entry. Surah 2 (Al-Baqarah) is 286 ayahs and will be your slowest query; pre-warming the top 10 surahs in a scheduled command is a cheap win on a reader site.
Route model binding on the surah number. Since the primary key is the surah number itself, this works cleanly:
Route::get('/quran/{surah:number}', [SurahController::class, 'show']);
API resource layer. If you're serving a mobile app or SPA, return a SurahResource with ayahs as a nested collection, and include the surah's ayah count so the client can paginate/progress without a second call.
Translation switching. If config/quran.php exposes a translation key, resolve it per-request in a middleware or a Quran::translation() helper rather than at boot — otherwise you can't serve two languages from one process. If it doesn't expose one, that's your first extension point (see below).
Testing. Use RefreshDatabase and seed once per test class, or better, point tests at an in-memory SQLite connection with the package data copied in setUp. Quran queries are read-only, so you can wrap each test in a transaction and skip re-seeding entirely.
Blade component for ayah rendering. Encapsulate the RTL/dir, ayah-number badge, and translation toggle in <x-quran.ayah> so the rendering rules live in one place; you'll change those rules more often than you think.
Check the Laravel constraint before you commit. Last release was July 2021, which is Laravel 8-era. On Laravel 10/11 you may need composer require wearedevtical/laravel-quran --with-all-dependencies and possibly a replace entry or a fork. Confirm the illuminate/* constraints in composer.json first; if they're ^8.0, budget for patching the service provider (usually just the boot() signature and any Str/Arr helpers).
The "static Eloquent model" phrasing matters. It usually means the model pins a $connection to a bundled SQLite database. If your app runs on MySQL/Postgres, you now have two connections, and DB::transaction() inside your app won't cover Quran reads. Debug with:
dd($surah->getConnectionName(), $surah->getTable());
Seeding is the slow step, not querying. A full Quran seed is ~6,236 ayahs plus surah metadata. On shared hosting it can blow max_execution_time or memory. If the package uses a seeder, chunk it or import the SQLite file directly rather than looping Eloquent create() calls.
Don't Surah::all() with ayahs eager-loaded. That's the entire Quran in memory. Always constrain to the surah(s) you're rendering, and only load ayahs when you'll display them.
Ayah numbering and the Basmalah. Verse indices in Quran data are notoriously inconsistent about whether the opening Basmalah counts as ayah 1 (it does in Al-Fatiha, it doesn't elsewhere). Don't assume 1-based indexing matches the printed mushaf; verify against the seed data before building a "go to ayah" feature.
Arabic search needs normalization. If you add search, strip diacritics (harakat) and normalize alef variants before matching, and use utf8mb4 collation. A raw LIKE '%...%' on Arabic text will miss most queries.
RTL and fonts are a rendering problem, not a data problem. Set dir="rtl" and lang="ar" on the ayah element, and pick an Arabic font (Amiri, Scheherazade) — the default system font renders diacritics poorly.
Extension points, in order of usefulness:
config/quran.php for translation/connection — publish it and commit it.models array; if not, that's the smallest useful PR.QuranRepository (above) as the real seam.Debugging queries. Register DB::connection('quran')->listen(fn ($q) => logger($q->sql)) in a service provider temporarily; because the connection is separate, your usual Telescope/query-log setup may not capture it.
License note for translations. The code is MIT, but the bundled translation text carries its own license (often CC-BY or similar). If you ship a commercial product, check the attribution requirements in the README before going live.
How can I help you explore Laravel packages today?