BookStore

Technical documentation for the BookStore application.

Overview

BookStore is a simple demonstration web application implemented in plain PHP following an MVC structure with explicit Service and Repository layers. It is intended as a learning example for web application architecture, basic CRUD operations, and a minimal admin interface.

Repository layout

• app/
  • Controllers/ - HTTP controllers and request handlers
  • Services/ - Business logic layer
  • Repositories/ - Data access layer (SQL queries)
  • Models/ - Domain entities
  • Core/ - Framework-like utilities (Router, Database)
• config/ - Application configuration
• public/ - Public assets (CSS, JS, images)
• views/ - PHP view templates
• index.php - Application entry point
• bookstore_db.sql - Database schema and seed data

Architecture

The codebase is structured into these logical layers:

• Controller: Receives HTTP requests, handles input, coordinates services, and returns views or redirects.
• Service: Implements business rules and validation. Works with repositories to read/write data.
• Repository: Encapsulates SQL queries and maps database rows to Model objects.
• Model: Plain PHP objects representing domain entities (e.g., Book).

This separation improves testability and keeps SQL isolated from controllers.

Requirements

• PHP 7.4 or newer
• MySQL 5.7 or newer (or compatible server)
• Web server (Apache or Nginx recommended)
• Composer is not required (no external PHP dependencies used)

Installation and configuration

1. Place the project folder into your web server document root (for example, XAMPP's htdocs).

2. Create the database and import schema:

   • Using mysql client:

     mysql -u <db_user> -p < bookstore_db.sql

   • Or use phpMyAdmin to import bookstore_db.sql.

3. Configure database connection and application URL in config/config.php or via environment variables (.env loader reads project root .env):

   'database' => [
       'host' => 'localhost',
       'port' => '3306',
       'dbname' => 'bookstore',
       'username' => 'root',
       'password' => '',
       'charset' => 'utf8mb4',
   ]
   
   'app' => [
       'url' => 'http://localhost/BookStore',
       'debug' => true,
   ]

4. Start your web server and navigate to the configured application URL.

Running the application (development)

• For XAMPP: place BookStore under htdocs/ and visit http://localhost/BookStore.
• Ensure PHP error display or logging is enabled when debugging (config/config.php has an app.debug option read by the app).

Features

• Admin interface for managing books (list, create, edit, delete)
• Public book listing and book detail pages
• Server-side validation and duplicate checking
• Simple pagination and search

Routes (selected)

The application maps URL patterns to controller actions via the router. Representative routes:

• GET / -> HomeController::index
• GET /books -> BookController::index
• GET /books/create -> BookController::create
• POST /books/store -> BookController::store
• GET /books/{id} -> BookController::show
• GET /books/{id}/edit -> BookController::edit
• POST /books/update -> BookController::update
• POST /books/delete -> BookController::delete

Admin routes are prefixed under /admin/* and handled by AdminController.

Development notes

• Views are plain PHP templates in views/. Use BaseController::render() to render templates with the main layout.
• Database access is implemented with PDO in app/Core/Database.php. Prepared statements are used.
• Models are simple POPOs (plain old PHP objects) in app/Models/ and are constructed by passing associative arrays returned from repository queries.

Recommended workflow for changes:

1. Update database schema (if necessary) and version it.
2. Update Repository SQL and mapping code.
3. Update Model fields and getters/setters.
4. Update Service layer validation and business rules.
5. Update Controllers and Views.

Testing and manual checks

• There is a tests/manual_tests.ps1 script included for manual checks on Windows/PowerShell. It is not an automated test suite.
• Check application logs and PHP error log on failures.

Contributing

1. Fork the repository.
2. Create a feature branch.
3. Make changes and verify locally.
4. Submit a pull request describing the change and rationale.

License

This repository includes a license file if applicable. Confirm the LICENSE file in the project root for details.

Contact

This project is provided as-is for educational purposes. There is no production support service associated with it.

Project Structure

Below is a full, expanded project structure for this repository with file-level detail and short descriptions. Use this as a reference when navigating the codebase.

BookStore/
├─ bookstore_db.sql            # Database schema and seed data (SQL dump)
├─ index.php                   # Application entry point / front controller
├─ README.md                   # Project documentation (this file)
├─ app/
│  ├─ Controllers/
│  │  ├─ AdminController.php   # Admin routes and admin-specific actions
│  │  ├─ AuthController.php    # Login, logout, register handling
│  │  ├─ BaseController.php    # Shared controller helpers / view rendering
│  │  ├─ BookController.php    # Public book listing / detail / search
│  │  ├─ ContactController.php # Contact form handling
│  │  └─ HomeController.php    # Home page actions
│  ├─ Core/
│  │  ├─ Database.php          # PDO wrapper and DB connection
│  │  ├─ HttpException.php     # Custom HTTP exception handling
│  │  └─ Router.php            # Simple routing implementation
│  ├─ Models/
│  │  ├─ Book.php              # Book domain model
│  │  └─ User.php              # User domain model
│  ├─ Repositories/
│  │  ├─ BookRepository.php    # SQL queries and mapping for books
│  │  └─ UserRepository.php    # SQL queries and mapping for users
│  └─ Services/
│     ├─ AuthService.php       # Authentication logic and session management
│     └─ BookService.php       # Business logic for books (validation, rules)

├─ config/
│  └─ config.php              # Application configuration (DB credentials, app URL, debug)

├─ public/
│  ├─ index.php               # Public entry (may mirror root index.php or route assets)
│  ├─ css/
│  │  ├─ admin.css
│  │  ├─ auth.css
│  │  ├─ base.css
│  │  ├─ books.css
│  │  ├─ contact.css
│  │  ├─ errors.css
│  │  ├─ forms.css
│  │  ├─ home.css
│  │  ├─ layout.css
│  │  ├─ modal.css
│  │  └─ responsive.css
│  ├─ images/                 # Site images and assets (icons, covers)
│  └─ js/
│     └─ app.js               # Frontend JS for UI interactions

├─ views/
│  ├─ admin/
│  │  └─ books/
│  │     ├─ create.php        # Create book form
│  │     ├─ edit.php          # Edit book form
│  │     └─ index.php         # Admin listing of books
│  ├─ auth/
│  │  ├─ login.php            # Login form view
│  │  └─ register.php         # Registration form view
│  ├─ books/
│  │  └─ index.php            # Public book listing page
│  ├─ contact/
│  │  └─ index.php            # Contact page view
│  ├─ home/
│  │  └─ index.php            # Home page view
│  └─ layouts/
│     └─ main.php             # Main layout (header, footer, includes CSS/JS)

Folder descriptions

• index.php (root) — application front controller that bootstraps dependencies and dispatches requests to controllers.
• app/Controllers/ — contains HTTP controllers which handle requests, validate input, call services, and render views or return redirects.
• app/Core/ — low-level utilities used across the app (database connection, routing, custom exceptions).
• app/Models/ — simple PHP classes representing domain entities used throughout services and repositories.
• app/Repositories/ — encapsulates direct database access (SQL) and maps result sets to Model objects.
• app/Services/ — business logic layer: validation, transaction boundaries, and higher-level operations combining repositories.
• config/config.php — central place for DB credentials, app URL, and toggles like debug.
• public/ — publicly served files (CSS, JS, images) intended to be the webserver document root.
• views/ — PHP templates rendered by controllers; organized by feature with a shared layouts/main.php for consistent layout.
• bookstore_db.sql — SQL schema and seed data to initialize the database.

Notes and usage

• The app follows a conventional MVC split plus explicit Services and Repositories to keep SQL isolated from controllers.
• To start locally with XAMPP/Apache: place the BookStore folder under htdocs/ and ensure config/config.php has correct DB credentials. Import bookstore_db.sql into MySQL.