README

Quran Manager for Laravel provides a configurable Quran data manager for Laravel applications.

The package uses Laravel's manager pattern, allowing the Quran data provider to be changed without changing application code.

Installation

Install the package with Composer:

composer require yugo/laravel-quran

Publish the configuration file when you need to customize the defaults:

php artisan vendor:publish --tag=quran-config

Configuration

QURAN_PROVIDER=ummahapi
QURAN_CACHE_STORE=
QURAN_CACHE_TTL=604800
EQURAN_BASE_URL=https://equran.id
EQURAN_TIMEOUT=10
UMMAH_API_BASE_URL=https://ummahapi.com
UMMAH_API_TIMEOUT=10

Usage

use Yugo\Quran\Facades\Quran;

$surah = Quran::surah(1);
$verse = $surah->verse(10);
$attribution = Quran::attribution();

The returned Surah object contains the surah metadata, a list of Verse objects, and an audio list containing Audio objects for the complete surah. Each audio object exposes a path, with optional reciter and style metadata. Use verse(int $number) to select an individual verse without making another provider request. It returns null when the verse does not exist.

The Quran::surahs() catalog returns SurahSummary objects with an optional meaning field when the configured provider supplies it.

Providers

UmmahAPI

Data provided by UmmahAPI.

eQuran.id

Data provided by eQuran.id.

Custom providers

Custom providers implement QuranProvider and can be registered through the manager:

use Yugo\Quran\Contracts\QuranProvider;
use Yugo\Quran\Facades\Quran;

Quran::extend('custom', fn (): QuranProvider => new CustomQuranProvider);

A provider must implement:

public function getSurah(int $number): Surah;

/**
 * @return array{label: string, url: string}
 */
public function getAttribution(): array;