README

The official, typed PHP client for the public PrayerZone prayer-times API.

Use it in Laravel, Symfony, WordPress, Drupal, command-line applications, scheduled jobs, and any modern PHP 8.1+ project.

Features

Immutable, typed response objects
City and mosque prayer schedules
Nearby mosque discovery
Qibla and calculation metadata
Eight supported languages through a backed enum
Request timeout and exponential retries
In-memory response cache
Structured, actionable exceptions
Injectable transport for tests and custom infrastructure
No framework dependency

Installation

composer require prayerzone/prayer-times

PHP 8.1 or later with the JSON and cURL extensions is required.

Quick start

<?php

use PrayerZone\Language;
use PrayerZone\PrayerZoneClient;

require __DIR__ . '/vendor/autoload.php';

$prayerZone = new PrayerZoneClient();
$schedule = $prayerZone->getCityPrayerTimes('paris', Language::French);

echo $schedule->city->name . PHP_EOL;
foreach ($schedule->data->prayerTimes as $prayer) {
    echo $prayer->name . ': ' . $prayer->time . PHP_EOL;
}

echo 'Qibla: ' . $schedule->data->qibla->bearing . '°' . PHP_EOL;

Mosque schedules

$schedule = $prayerZone->getMosquePrayerTimes(
    'paris_grande-mosquee-de-paris',
    'fr',
);

echo $schedule->mosque->title;

Find nearby mosques

$mosques = $prayerZone->getNearbyMosques(
    longitude: 2.3522,
    latitude: 48.8566,
    maxDistance: 5000,
);

foreach ($mosques as $mosque) {
    echo $mosque->title . ' — ' . $mosque->distance . ' km' . PHP_EOL;
}

Configuration

$prayerZone = new PrayerZoneClient(
    timeout: 8.0,
    retries: 2,
    retryDelayMilliseconds: 250,
    cacheTtlSeconds: 300,
    headers: ['X-Application' => 'my-prayer-app'],
);

Option	Default	Description
`baseUrl`	`https://pray.zone`	API origin; useful for tests and proxies
`timeout`	`10.0`	Timeout in seconds for each attempt
`retries`	`2`	Retries for timeouts, network failures, HTTP 408, 429, and 5xx
`retryDelayMilliseconds`	`250`	Initial exponential retry delay
`cacheTtlSeconds`	`300`	Successful response cache duration; `0` disables it
`headers`	—	Additional HTTP request headers
`transport`	cURL	Injectable implementation of `TransportInterface`

Call $prayerZone->clearCache() when an application needs a forced refresh.

Error handling

use PrayerZone\PrayerZoneException;

try {
    $prayerZone->getCityPrayerTimes('unknown-city');
} catch (PrayerZoneException $error) {
    echo $error->errorCode;
    echo $error->statusCode;

    if ($error->retryable) {
        echo 'This failure may be temporary.';
    }
}

Error codes are api_error, network_error, timeout, and validation_error.

Languages

The language argument accepts a Language enum or one of these strings:

ar, bn, de, en, es, fr, it, pt

English (en) is used by default.

API and related projects

Localized PrayerZone websites

pray.zone is the canonical project and developer domain. PrayerZone also provides localized prayer-time websites:

Development

composer install
composer validate --strict
composer check

See CONTRIBUTING.md for the contribution workflow.

Attribution

Attribution is mandatory when PrayerZone API data is displayed or redistributed in a public project using this SDK. Include a visible link to the canonical PrayerZone website:

Prayer times powered by <a href="https://pray.zone/">PrayerZone</a>

This service and data attribution requirement is separate from the repository's open-source license.

License

MIT

prayerzone / prayer-times

Maintainers

Package info

Statistics

Security