Adzan! — Islamic Prayer Time Schedule System

Adzan! is a comprehensive, lightweight PHP-based system designed to calculate and display Islamic prayer times (Salah) schedules dynamically using astronomical algorithms.

1. Overview & Astronomical Foundation
2. Calculation Conventions & Methods
3. The Astronomical Algorithm (Method #3)
4. Prayer Time Determinations
5. Architecture & Installation
6. Security & PHP 8.3+ Compatibility Hardening
7. References
8. Changelog

The primary astronomical data required to determine prayer schedules is the position of the sun in horizon coordinates, specifically the zenith angle ($z$) or altitude ($h$).

Astronomy interprets Islamic religious definitions into precise solar positions:

• Fajr (Dawn): Begins at the start of Astronomical Twilight (when light starts appearing on the eastern horizon) when the sun is typically $18^\circ$ to $20^\circ$ below the horizon.
• Dhuhr (Midday): Commences when the sun passes the meridian (noon), typically adjusted 2 minutes later for safety.
• Asr (Afternoon): Starts when the shadow of an object equals its height plus its noon shadow (Standard/Shafi'i) or twice its height plus its noon shadow (Hanafi).
• Maghrib (Sunset): Defined as when the sun fully disappears below the horizon ($z = 90.833^\circ$ or $91^\circ$ accounting for altitude corrections).
• Isha (Night): Commences when twilight fades completely from the western horizon, typically when the sun is $15^\circ$ to $18^\circ$ below the horizon.

Different regions of the world adhere to distinct legal and astronomical conventions for Fajr and Isha angles:

Source: Almanac for Computers, 1990 (United States Naval Observatory)

• day, month, year: Calendar date.
• latitude, longitude: Geographic coordinates in degrees (positive for North/East, negative for South/West).
• localOffset: Local timezone offset from UTC (in hours).
• zenith: Solar zenith angle ($90^\circ 50'$ for official sunrise/sunset, $108^\circ$ for astronomical twilight).

1. Calculate the day of the year ($N$): $$N_1 = \lfloor \frac{275 \times \text{month}}{9} \rfloor$$ $$N_2 = \lfloor \frac{\text{month} + 9}{12} \rfloor$$ $$N_3 = 1 + \lfloor \frac{\text{year} - 4 \times \lfloor \text{year}/4 \rfloor + 2}{3} \rfloor$$ $$N = N_1 - (N_2 \times N_3) + \text{day} - 30$$

2. Approximate the solar time ($t$): $$\text{lngHour} = \frac{\text{longitude}}{15}$$

   • For sunrise: $t = N + \frac{6 - \text{lngHour}}{24}$
   • For sunset: $t = N + \frac{18 - \text{lngHour}}{24}$

3. Calculate Sun's mean anomaly ($M$): $$M = (0.9856 \times t) - 3.289$$

4. Calculate Sun's true longitude ($L$): $$L = M + (1.916 \times \sin(M)) + (0.020 \times \sin(2 \times M)) + 282.634$$ (Adjust $L$ into range $[0, 360)$)

5. Calculate Sun's Right Ascension ($RA$): $$RA = \arctan(0.91764 \times \tan(L))$$ (Adjust $RA$ into range $[0, 360)$ and match the quadrant of $L$) $$\text{Convert } RA \text{ to hours: } RA = \frac{RA}{15}$$

6. Calculate Sun's declination ($\delta$): $$\sin(\delta) = 0.39782 \times \sin(L)$$ $$\cos(\delta) = \cos(\arcsin(\sin(\delta)))$$

7. Calculate Sun's local hour angle ($H$): $$\cos(H) = \frac{\cos(\text{zenith}) - (\sin(\delta) \times \sin(\text{latitude}))}{\cos(\delta) \times \cos(\text{latitude})}$$

   • If $\cos(H) > 1$: Sun never rises.
   • If $\cos(H) < -1$: Sun never sets.
   • Otherwise:
     • For Sunrise: $H = 360 - \arccos(\cos(H))$
     • For Sunset: $H = \arccos(\cos(H))$
     • Convert to hours: $H = \frac{H}{15}$

8. Calculate local mean time ($T$) and convert to UTC ($UT$): $$T = H + RA - (0.06571 \times t) - 6.622$$ $$UT = T - \text{lngHour}$$ (Adjust $UT$ into range $[0, 24)$)

9. Calculate Local Time: $$\text{Local Time} = UT + \text{localOffset}$$

• Shubuh (Fajr): Derived using the sunrise steps above, replacing the zenith with $108^\circ$ (or $110^\circ$ as adopted by the Indonesian Ministry of Religious Affairs).
• Dhuhr: Calculated when the sun reaches its zenith (transit time). An ihtiyat (precautionary margin) of +2 to +5 minutes is added.
• Asr: Calculated by finding the zenith angle $z_a$ where: $$z_a = \arctan(S_r + \tan(\text{latitude} - \delta))$$ where $S_r$ is the Shadow Ratio (1.0 or 2.0).
• Maghrib: Calculated based on sunset time ($z = 90.833^\circ$), with an added margin of +2 minutes.
• Isha: Calculated using the sunset steps, replacing zenith with $108^\circ$ (or using fixed intervals like 90 minutes).

• administrator/: Protected admin panel to configure system settings and manage city coordinates.
• ajax/: Handles dynamic retrieval of daily, weekly, monthly, and yearly prayer times.
• class/: Contains core calculation libraries (class.adzan.main.php, etc.) and configuration/user models.
• data/: Text databases containing city coordinates sorted by country.

1. Copy .env.example to .env and configure your credentials (e.g., database connection parameters and admin credentials).
2. Upload the files to your PHP web server.
3. If config.php does not exist or is empty, the system automatically redirects you to the installer (installation/index.php).
4. Follow the installation wizard instructions to set up your primary country, calculation conventions, and admin credentials.
5. Delete the installation/ directory once setup completes.

The application supports environment-based configuration via a .env file for sensitive credentials. Ensure the .env file is present in the root directory:

• DB_HOST: Database hostname/IP address.
• DB_PORT: Database port (default: 3306).
• DB_DATABASE: Database name.
• DB_USERNAME: Database username.
• DB_PASSWORD: Database password.
• ADZAN_USER: Admin portal login username.
• ADZAN_SECRET: Security key/salt or admin secret password.

• CSRF (Cross-Site Request Forgery) Protection: Fully secured admin panel pages against CSRF exploits by implementing session-bound token generation and strict validations on state-changing commands (save, del, add).
• XSS Prevention: Input sanitization has been added to the dynamic AJAX script routes (ajax.php and ajax.row.php), casting variables to integers.
• PHP 8.3+ Compatibility: Completely refactored obsolete PHP 4 constructors and parent invocation syntax to standard __construct() methods to prevent runtime syntax failures on PHP 8.0 through 8.3+.

• Astronomy on the Personal Computer by Oliver Montenbruck and Thomas Pfleger. Springer Verlag 1994. ISBN 3-540-57700-9.
• Prayer Schedules for North America, American Trust Publications, Indianapolis, Indiana, 1978, Appendices A and B.
• Almanac for Computers, 1990 published by Nautical Almanac Office, United States Naval Observatory, Washington, DC 20392.
• Astronomy of Islamic Times by Mohammad Ilyas, 1988. ISBN 0-7201-1983-9.
• The Explanatory Supplement to the Astronomical Almanac P. Kenneth Seidelmann, Ed. ISBN 0-935702-68-7.
• Practical Astronomy With Your Calculator Patrick Duffett-Smith, Third Edition, Cambridge University Press, ISBN 0-521-35699-7.
• Astronomical Algorithms Jean Meeus. Willmann-Bell, Inc. 1998. ISBN 0-943396-63-8.

• Environment Support: Added .env environment configuration support and created .env.example template to externalize database and admin credentials.
• Security Enhancements:
  • Implemented CSRF protection in the administrator panel with session-bound tokens.
  • Added input sanitization (integer casting) in ajax.php and ajax.row.php endpoints to prevent XSS.
• PHP 8.3 Compatibility: Refactored legacy PHP 4 constructors (function layout(), function user(), etc.) to standard modern __construct() methods to support PHP 8.0 through PHP 8.3+.

• Baseline version release containing core prayer schedule calculation libraries, configuration manager, database, and admin console dashboard.