diff --git a/README.md b/README.md index 937cad7..4536006 100644 --- a/README.md +++ b/README.md @@ -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).