From 8dec55ad667340b96b385f25d3a81c4e6b0fd696 Mon Sep 17 00:00:00 2001 From: Hafsha Mim Jannatee <153720529+HafshaMimJannatee@users.noreply.github.com> Date: Sun, 15 Feb 2026 02:41:05 +0600 Subject: [PATCH] Revise README for clarity and additional information Updated README to enhance project details and instructions. --- README.md | 193 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 164 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 937cad7b..88347dc9 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,178 @@ -# sunnah-website -This is the front end code for [sunnah.com](https://sunnah.com). It is built atop the Yii 2 MVC framework. + -The top level structure is divided into application code (in the `application` folder) that includes MVC code and the `public` folder which contains `index.php`, `css`, `js`, and others. + +
+

+ + Logo + -Your webserver should point to the public folder. The Yii framework code needs to reside on the machine as well; its location is hardcoded into `public/index.php`. +

Sunnah.com

-Under the `application` folder, here are the important locations: +

+ The official frontend source code repository for Sunnah.com +
+
+ Visit Sunnah.com + . + Report Bug + ยท + Request Feature +

+

+ -* `config/main.php`: All the configuration options, including URL routes, database connections, etc. -* Yii divides its MVC code into "modules" that share code. Think of them as sections of a website. For example, an admin section vs. a public section. -* `modules/front/controllers`: All controller classes. There are three main controllers: the search page, the index and sitewide pages, and the collection controller which includes actions for displaying collections, books, and ahadith. -* `modules/front/models`: All model classes. Each kind of object has a model class. E.g. hadith, book, collection. -* `modules/front/views`: Each controller has actions which have view code. This folder contains the view code. -* `modules/front/views/layouts`: Other view code corresponding to side menus, search box, widgets, etc. -* `views/layouts`: Sitewide view code like column layout, footer. +[![Contributors][contributors-shield]][contributors-url] +[![Forks][forks-shield]][forks-url] +[![Issues][issues-shield]][issues-url] +[![Stargazers][stars-shield]][stars-url] +[![License][license-shield]][license-url] +This repository contains the frontend application code for **Sunnah.com**. +The project is built atop the Yii 2 MVC framework and serves as the primary web interface for browsing hadith collections, books, and individual narrations. -## Running on Windows +--- -* Install PHP 7.3 -* Create an IIS website and point it to the `public` folder -* Add the `index.php` file as default document -* Add handler mapping for `.php` files in iis -* Download and install [MySQL for Windows](https://dev.mysql.com/downloads/windows/) -* Import the sample db in MySQL -* Download and install [Composer](https://getcomposer.org/download/) -* Run the `install` comand of composer in the root dir -* Visit localhost in a browser to see the site running +## Project Structure Overview +The top level structure is divided into two major parts: -## Working with the Dev Container -If you don't want to set up a complete dev environment on your host, you can use a Docker container to host the PHP environment, dependencies, and web server. The source code is mounted as a volume inside the container, so any changes will reflect immediately inside the container without having to rebuild it. +- **application/** + Contains all MVC related application code. -Launching the dev container is composed of a simple `docker-compose` command. First however, copy the `.env.local.sample` file to `.env.local` (**important**). Then run the following command in the same directory as the Dockerfile: +- **public/** + Contains the web root, including `index.php`, CSS, JavaScript, and other publicly accessible assets. -`docker-compose up --build` +Your web server **must point to the `public/` directory**. -You should then be able to access the webserver using port 80 on the container's host. +The Yii framework source code must also exist on the machine. Its path is hardcoded inside `public/index.php`. -Use [Visual Studio Code](https://code.visualstudio.com/) with [Remote Containers](https://code.visualstudio.com/docs/remote/containers) extensions to attach to running instance and try out changes rapidly. +--- -Use the [php cs fixer](https://marketplace.visualstudio.com/items?itemName=makao.phpcsfixer) extension for formatting code. +## Application Directory Structure + +Inside the `application/` folder, the following locations are most important: + +### Configuration +- `config/main.php` + Contains application configuration such as URL routing, database connections, and environment settings. + +### MVC Modules +Yii divides the application into **modules**, which represent logical sections of the website. + +#### Controllers +- `modules/front/controllers` + Contains all controller classes. The main controllers include: + - Search related pages + - Index and sitewide pages + - Collection controller responsible for collections, books, and ahadith + +#### Models +- `modules/front/models` + Contains model classes representing core entities such as: + - Hadith + - Book + - Collection + +#### Views +- `modules/front/views` + View files corresponding to controller actions. + +- `modules/front/views/layouts` + Shared UI components such as side menus, widgets, and the search box. + +- `views/layouts` + Sitewide layouts including headers, footers, and column structures. + +--- + +## Running the App Locally (Windows) + +### Requirements +- PHP 7.3 +- MySQL +- Composer +- IIS Web Server + +### Setup Steps +1. Install PHP 7.3 +2. Create an IIS website and point it to the `public/` directory +3. Add `index.php` as the default document +4. Add handler mappings for `.php` files in IIS +5. Install [MySQL for Windows](https://dev.mysql.com/downloads/windows/) +6. Import the provided sample database into MySQL +7. Install [Composer](https://getcomposer.org/download/) +8. Run the Composer install command in the project root directory +9. Visit `http://localhost` in your browser + +If configured correctly, the site should load successfully. + +--- + +## Working With the Dev Container + +If you prefer not to configure a full local environment, a Docker based development container is available. + +### Steps +1. Copy `.env.local.sample` to `.env.local` +2. Run the following command in the directory containing the `Dockerfile`: + +```bash +docker-compose up --build +``` +3. Access the web server on port `80` of the container host + +### Development Workflow +- The source code is mounted as a volume inside the container +- Any file changeiately without rebuilding +- Use [Visual Studio Code](https://code.visualstudio.com/) with the [Remote Containers](https://code.visualstudio.com/docs/remote/containers) extension to attach to the running instance + +--- + +## Code Style and Formatting +- Use [php cs fixer](https://marketplace.visualstudio.com/items?itemName=makao.phpcsfixer) for consistent code formatting +- Follow existing project conventions when adding or modifying code + +--- + +## How to Contribute +Contributions are welcome from anyone with sincere intentions to improve access to authentic hadith. + +Please do not copy or reuse this project for derivative platforms. This project exists solely to serve the Ummah and preserve knowledge with integrity. + +If you wish to help: +- Check existing issues +- Open a new issue for bugs or suggestions +- Submit a pull request with a clear explanation + +--- + +## Filing Bugs +If you encounter a bug, please open an issue on GitHub with: +- Clear reproduction steps +- Expected vs actual behavior +- Screenshots if applicable + +--- + +## License +This project is licensed under the terms specified in the repository license file. + + + + +[contributors-shield]: https://img.shields.io/github/contributors/sunnah-com/website?style=for-the-badge +[contributors-url]: https://github.com/sunnah-com/website/graphs/contributors +[forks-shield]: https://img.shields.io/github/forks/sunnah-com/website?style=for-the-badge +[forks-url]: https://github.com/sunnah-com/website/network/members +[stars-shield]: https://img.shields.io/github/stars/sunnah-com/website?style=for-the-badge +[stars-url]: https://github.com/sunnah-com/website/stargazers +[issues-shield]: https://img.shields.io/github/issues/sunnah-com/website?style=for-the-badge +[issues-url]: https://github.com/sunnah-com/website/issues +[license-shield]: https://img.shields.io/github/license/sunnah-com/website?style=for-the-badge +[license-url]: https://github.com/sunnah-com/website/blob/master/LICENSE