Skip to content

Revise README for clarity and additional information #156

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
HafshaMimJannatee wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Revise README for clarity and additional information #156

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
193 changes: 164 additions & 29 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
<!--
*** Thank you for checking out this Sunnah.com repository.
*** If you have suggestions to improve this project, please fork the repo
*** and open a pull request or create an issue.
*** May Allah put barakah in every sincere contribution.
-->

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.
<!-- PROJECT LOGO -->
<br />
<p align="center">
<a href="https://sunnah.com">
<img src="public/images/fb_logo.png" alt="Logo" width="80" height="80">
</a>

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`.
<h1 align="center">Sunnah.com</h1>

Under the `application` folder, here are the important locations:
<p align="center">
The official frontend source code repository for Sunnah.com
<br />
<br />
<a href="https://sunnah.com">Visit Sunnah.com</a>
.
<a href="https://github.com/sunnah-com/website/issues">Report Bug</a>
·
<a href="https://github.com/sunnah-com/website/issues">Request Feature</a>
</p>
</p>
<!-- PROJECT SHIELDS -->

* `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.

<!-- MARKDOWN LINKS & IMAGES -->
<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->

[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