Skip to content

Improve README structure and add contributor guidance #163

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
mahmoodhamdi wants to merge 1 commit into
base: master
Choose a base branch
from
+94 −29
Open

Improve README structure and add contributor guidance #163

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
123 changes: 94 additions & 29 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,108 @@
# sunnah-website
This is the front end code for [sunnah.com](https://sunnah.com). It is built atop the Yii 2 MVC framework.
# sunnah.com Website

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.
Frontend code for [sunnah.com](https://sunnah.com), built on the [Yii 2](https://www.yiiframework.com/) MVC framework (PHP).

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`.
## Table of Contents

Under the `application` folder, here are the important locations:
- [Project Structure](#project-structure)
- [Quick Start with Docker](#quick-start-with-docker)
- [Manual Setup](#manual-setup)
- [Sample Database](#sample-database)
- [Contributing](#contributing)
- [License](#license)

* `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.
## Project Structure

The repository is divided into two top-level areas:

## Running on Windows
- `public/` — the webroot. Contains `index.php`, static assets (`css/`, `js/`, `images/`), and the Yii bootstrap. Point your webserver at this directory.
- `application/` — the Yii application code (MVC), grouped into modules.

* 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
The Yii framework itself lives outside the repo; its location is hardcoded in `public/index.php`.

Inside `application/`, the key locations are:

## 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.
| Path | Purpose |
|---|---|
| `config/main.php` | All configuration options: URL routes, database connection, components |
| `controllers/SController.php` | The base controller class that all feature controllers extend |
| `modules/front/controllers/` | Controllers for the public-facing site. The main controllers handle search, the index and sitewide pages, and the collection display (collections, books, individual ahadith) |
| `modules/front/models/` | Model classes — one per hadith language, plus `Book`, `Chapter`, `Collection`, `Narrator`, `Search` |
| `modules/front/views/` | View files, one subfolder per controller |
| `modules/front/views/layouts/` | Reusable view fragments: side menus, search box, widgets |
| `views/layouts/` | Sitewide view code: column layout, footer |

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:
Yii groups MVC code into "modules", which you can think of as sections of the website (e.g. an admin section vs. a public section). The public-facing feature code lives under `modules/front/`.

`docker-compose up --build`
## Quick Start with Docker

You should then be able to access the webserver using port 80 on the container's host.
The recommended setup. Boots PHP + Apache + MySQL (with sample data) in one command.

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.
1. Copy the environment file (**this step is required**):

Use the [php cs fixer](https://marketplace.visualstudio.com/items?itemName=makao.phpcsfixer) extension for formatting code.
```bash
cp .env.local.sample .env.local
```

2. Start the stack:

```bash
docker compose up --build
```

3. Visit [http://localhost](http://localhost) in your browser.

The source code is bind-mounted into the container, so edits are reflected without a rebuild. For development with VS Code, install the [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) extension to attach to the running container.

## Manual Setup

If you'd rather run PHP and MySQL directly on your host:

1. Install PHP (see the `require.php` constraint in `composer.json`) and MySQL.
2. Install [Composer](https://getcomposer.org/download/) and run `composer install` from the repo root.
3. Import the sample database files from `db/` (see [Sample Database](#sample-database) below).
4. Point your webserver at the `public/` folder and add `index.php` as the default document.

### Windows with IIS

1. Create an IIS website pointing to the `public/` folder.
2. Add `index.php` as the default document and map the `.php` extension to the PHP handler.
3. Install [MySQL for Windows](https://dev.mysql.com/downloads/windows/) and import the sample database.
4. Visit `localhost` in a browser to verify the site is running.

## Sample Database

The `db/` directory contains SQL seed files. When using Docker, they are loaded automatically by the MySQL container via `docker-entrypoint-initdb.d`.

| File | Contents |
|---|---|
| `00-samplegitdb.sql` | Schema and base sample data |
| `01-hadithTable.sql` | Hadith records |
| `02-collections.sql` | Collection metadata |
| `03-bookdata.sql` | Book metadata |

When setting up manually, import the files in numerical order.

## Contributing

Bug reports, feature suggestions, and pull requests are welcome via [GitHub Issues](https://github.com/sunnah-com/website/issues) and [Pull Requests](https://github.com/sunnah-com/website/pulls).

When sending a pull request:

1. **One concern per PR.** Don't mix formatting changes with logic changes, and keep refactors separate from behavior changes.
2. **Reference the issue** being fixed in the commit message (for example, `Fixes #123`).
3. **Squash your commits** before merge, including any commits added in response to review feedback.
4. **Attach screenshots** for any UI changes.
5. **Discuss large changes first** by opening an issue before writing the code.

### Code Style

Format PHP code with [`php-cs-fixer`](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer) before submitting. A [VS Code extension](https://marketplace.visualstudio.com/items?itemName=makao.phpcsfixer) is available.

### Content Corrections

If you've found an error in a hadith text, translation, grading, or reference, please **don't** open a code pull request against this repository — content corrections are handled through a separate workflow. Open an issue describing the correction and a maintainer will route it appropriately.

## License

BSD-3-Clause. See the `license` field in [`composer.json`](composer.json).