🛒 Hekmat Online Store – Comprehensive PHP MVC E-Commerce Platform

A fully-featured, production-ready e-commerce platform built with a custom PHP MVC framework. Includes user authentication, product catalog with categories/subcategories, shopping cart, order management, comments system, address selection via interactive map, and responsive Persian UI.

Overview
Features
Technology Stack
Project Structure
Architecture
- MVC Pattern
- Request Flow
Core Modules
Database Schema
Security Features
Frontend Features
Installation Guide
Environment Configuration
Routing
Controllers Reference
Models Reference
Helper Functions
Views Structure
API Integrations
Browser Support
Troubleshooting

Overview

Hekmat Online Store is a complete e-commerce solution developed for a Persian-speaking market. It allows users to browse products by categories and subcategories, add items to cart, place orders with address selection on an interactive map, leave comments on products, and manage their profile. The platform features a responsive design, smooth animations, and a professional user interface.

✨ Features

Category	Features
User Management	🔐 Register, Login, Logout, Profile editing, Password change
Product Catalog	📦 Products with categories/subcategories, Images gallery, Stock management
Shopping Cart	🛒 Add/remove items, Calculate total price, Checkout process
Order System	📦 Place orders, View order history, Order status tracking (Pending/Completed/Rejected)
Comments	💬 Add comments on products, Admin approval system, Phone number masking
Address Selection	🗺️ Interactive map (Neshan) for location picking, Save address details
Search	🔍 Product search with real-time results
Bestsellers	⭐ Dynamic display of most sold products
News/New Products	🆕 Latest products showcase
Carousel Sliders	🖼️ Category carousels, Product sliders
Security	🛡️ CSRF protection, Password hashing (Argon2id), SQL injection prevention, Session management
Responsive Design	📱 Mobile-friendly layout, Persian (RTL) support
Animations	✨ Smooth transitions, Preloader, Swiper.js carousels

🛠️ Technology Stack

Backend

Technology	Purpose
PHP 8.0+	Core programming language
Custom MVC Framework	Application architecture
MySQL	Database management
PDO	Database abstraction with prepared statements
Argon2id	Password hashing

Frontend

Technology	Purpose
HTML5/CSS3	Structure & styling
JavaScript (Vanilla)	Interactive elements
Swiper.js	Touch-enabled carousels
Material Design Icons	Icon system
Vazirmatn Font	Persian typography
Neshan Maps API	Interactive location picker

Third-Party Integrations

Service	Purpose
Neshan Maps API	Reverse geocoding & map display
SweetAlert2	Beautiful alert dialogs

📁 Project Structure

project-root/
├── app/
│   ├── auto/                      # Auto-loaders
│   │   ├── PHP_ENV.php           # .env file loader
│   │   └── PHP_ERROR.php         # Error handler
│   ├── bootstrap/                 # Bootstrap files
│   │   └── bootstrap.php         # Session start, headers, autoload
│   ├── configs/                   # Configuration classes
│   │   ├── Config.php            # App configuration
│   │   └── DB.php                # Database credentials
│   ├── controllers/               # Application controllers
│   │   ├── HomeController.php    # Home page
│   │   ├── LoginController.php   # Login logic
│   │   ├── RegisterController.php# Registration logic
│   │   ├── ProductsController.php# Product listing
│   │   ├── ProductsSingleController.php # Single product
│   │   ├── SearchController.php  # Search functionality
│   │   ├── ProfileController.php # User profile
│   │   ├── ProfileCartController.php # Cart management
│   │   ├── ProfileAddressController.php # Address submission
│   │   ├── ProfileOrdersController.php # Order history
│   │   ├── ProfileEditProfileController.php # Profile editing
│   │   └── ProfileEditPasswordController.php # Password change
│   ├── core/                      # Core framework
│   │   └── Core.php              # Router dispatcher
│   ├── database/                  # Database connection
│   │   └── Database.php          # PDO connection class
│   ├── errors/                    # Error handlers
│   │   └── Errors.php            # HTTP error responses
│   ├── helpers/                   # Helper functions
│   │   └── helpers.php           # Global helpers
│   ├── libraries/                 # Base classes
│   │   └── Controller.php        # Base controller
│   ├── models/                    # Database models
│   │   ├── Categories.php        # Category operations
│   │   ├── Subcategories.php     # Subcategory operations
│   │   ├── Products.php          # Product operations
│   │   ├── Cart.php              # Cart operations
│   │   ├── Orders.php            # Order operations
│   │   ├── Comments.php          # Comment operations
│   │   ├── Users.php             # User operations
│   │   ├── Login.php             # Login validation
│   │   ├── Register.php          # Registration operations
│   │   └── Search.php            # Search operations
│   ├── resources/views/           # View templates
│   │   ├── home/                 # Home page views
│   │   ├── login/                # Login views
│   │   ├── register/             # Registration views
│   │   ├── products/             # Product views
│   │   ├── profile/              # Profile views
│   │   ├── search/               # Search views
│   │   ├── partials/             # Reusable components
│   │   │   ├── inc.start.php    # HTML opener
│   │   │   ├── inc.end.php      # HTML closer
│   │   │   ├── menu.php         # Main navigation
│   │   │   ├── navbar.php       # Top bar
│   │   │   ├── footer.php       # Main footer
│   │   │   └── footer_2.php     # Simple footer
│   │   └── errors/               # Error pages
│   │       ├── _403_.php
│   │       ├── _404_.php
│   │       └── _500_.php
│   └── routes/                    # Routing definitions
│       ├── Route.php             # Route class
│       └── Web.php               # Route declarations
├── public/                        # Public assets
│   ├── assets/                   # CSS, JS, images
│   │   ├── css/
│   │   ├── js/
│   │   ├── images/
│   │   ├── packages/            # Vendor assets
│   │   └── main-*.js            # Compiled bundle
│   └── index.php                # Front controller
├── vendor/                       # Composer dependencies
├── .env                          # Environment variables
└── composer.json                # Composer configuration

🏗️ Architecture

MVC Pattern

┌─────────────────────────────────────────────────────────────┐
│                         Browser                              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Front Controller                          │
│                    (public/index.php)                        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                         Core.php                             │
│                    (Router Dispatcher)                       │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│   Controllers   │ │     Models      │ │      Views      │
│ (Business Logic)│ │ (Data Access)   │ │   (Presentation)│
└─────────────────┘ └─────────────────┘ └─────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                         Database                             │
│                          (MySQL)                             │
└─────────────────────────────────────────────────────────────┘

Request Flow

User request → public/index.php
Bootstrap loads: session, error handling, helpers, autoloader
Core.php parses URL and determines controller/method
Controller processes request, calls models
Models interact with database via PDO
Controller passes data to View
View renders HTML response

Core Modules

User Authentication

Component	Description
Registration	Phone, username, password with validation (phone format: 09XXXXXXXXX, password: 6-30 chars)
Login	Username/password verification with Argon2id hash check
Session Management	User data stored in `$_SESSION["public"]`
Logout	Destroys session and redirects to home
Profile Editing	Update phone number or complete address (based on address status)
Password Change	Verify old password, hash new password (Argon2id)

Product Catalog

Component	Description
Categories	Product categories with parity-based display (odd/even)
Subcategories	Nested under categories with hierarchical menu
Product Listing	Paginated display (5 per page) with images
Single Product	Detailed view with image gallery, specifications, stock status
Stock Management	Shows "Out of stock", "Limited stock" (≤10), or normal stock
Bestsellers	Products sorted by order count (JOIN with orders table)
New Products	Latest 12 products displayed on homepage

Shopping Cart

Component	Description
Add to Cart	AJAX-less form submission, stores product title, price, image, user_id
View Cart	List all cart items with total price calculation
Remove Item	Delete individual items from cart
Checkout	Proceeds to address selection page
Cart Clear	After successful order, cart is emptied

Order Management

Component	Description
Order Creation	When user submits address, all cart items become orders
Unique Order ID	Generated using `uniqid() . "__" . time()`
Order Status	1 = Completed, 2 = Pending, 3 = Rejected
Order History	Users can view all their orders with status
Total Spend	Sum of completed orders displayed

Comments System

Component	Description
Add Comment	Authenticated users can leave comments
Phone Masking	Phone numbers are partially hidden (e.g., `*******1234`)
Admin Approval	Comments have status field (0 = pending, 1 = approved)
Comment Count	Shows number of approved comments per product

Address Selection (Map Integration)

Component	Description
Interactive Map	Neshan map integration for location picking
Reverse Geocoding	Click on map → fetch formatted address
Address Details	Collects pelak (plaque), zang (intercom), name, phone, national code, postal code
Validation	Phone, national code, postal code format validation
Duplicate Check	Prevents duplicate phone/national code/postal code

Search Functionality

Component	Description
Search Input	Real-time search by product title
Search Results	Displays matching products with images
No Results	Shows friendly "No results found" message

🗄️ Database Schema

users

Column	Type	Description
id	INT (PK)	Auto-increment
username	VARCHAR(30)	Unique login username
password	VARCHAR(255)	Argon2id hash
phone	VARCHAR(11)	Unique, format: 09XXXXXXXXX
name	VARCHAR(50)	Full name (optional)
national_code	VARCHAR(10)	National ID (optional)
post_code	VARCHAR(10)	Postal code (optional)
address	TEXT	Formatted address
address_desc	TEXT	Address details
width	VARCHAR(20)	Latitude coordinate
height	VARCHAR(20)	Longitude coordinate
zoom	INT	Map zoom level
zang	VARCHAR(10)	Intercom number
pelak	VARCHAR(10)	Plaque number
address_status	TINYINT	0 = no address, 1 = has address
ip	VARCHAR(45)	Registration IP address

subcategories

Column	Type	Description
id	INT (PK)	Auto-increment
cat_id	INT (FK)	Reference to categories.id
title	VARCHAR(100)	Subcategory name

products

Column	Type	Description
id	INT (PK)	Auto-increment
cat_id	INT (FK)	Reference to categories.id
subcat_id	INT (FK)	Reference to subcategories.id
title	VARCHAR(200)	Product name
price	DECIMAL(15,2)	Product price
total	INT	Stock quantity
description	TEXT	Product description

products_images

Column	Type	Description
id	INT (PK)	Auto-increment
product_id	INT (FK)	Reference to products.id
image	VARCHAR(255)	Image filename

products_search

Column	Type	Description
id	INT (PK)	Auto-increment
product_id	INT (FK)	Reference to products.id
search	TEXT	Searchable product title

users_cart

Column	Type	Description
id	INT (PK)	Auto-increment
title	VARCHAR(200)	Product title (denormalized)
price	DECIMAL(15,2)	Product price (denormalized)
user_id	INT (FK)	Reference to users.id
product_id	INT	Product ID reference
image	VARCHAR(255)	Product image path

orders

Column	Type	Description
id	INT (PK)	Auto-increment
title	VARCHAR(200)	Product title (denormalized)
price	DECIMAL(15,2)	Product price (denormalized)
user_id	INT (FK)	Reference to users.id
product_id	INT	Product ID reference
unique_id	VARCHAR(100)	Unique order identifier
status	TINYINT	1=Completed, 2=Pending, 3=Rejected

products_comments

Column	Type	Description
id	INT (PK)	Auto-increment
product_id	INT (FK)	Reference to products.id
comment	TEXT	Comment content
name	VARCHAR(50)	Commenter name (phone masked)
status	TINYINT	0=Pending, 1=Approved

🔒 Security Features

Feature	Implementation
SQL Injection	Prepared statements (PDO) with bound parameters
XSS Prevention	`safeEcho()` uses `htmlspecialchars()`
CSRF Protection	Token generation and validation on all forms
Password Security	Argon2id hashing (MakeSecureHash/CheckSecureHashed)
Session Security	Session start with custom headers
Input Validation	Server-side validation for all inputs
Phone Validation	Regex check (starts with 09, length 11)
National Code Validation	Length 10, starts with 0
Postal Code Validation	Length 10
Output Encoding	All dynamic output escaped
Security Headers	X-Frame-Options, X-XSS-Protection, etc.

CSRF Protection Flow

// In view
<input type="hidden" name="csrf_token" value="<?= generateToken() ?>">

// In controller
validateToken(); // Throws error if invalid

🎨 Frontend Features

Feature	Description
Preloader	Shows loading animation while assets load
Swiper Sliders	Touch-enabled carousels for categories, bestsellers, news
Responsive Menu	Hamburger menu for mobile devices
Interactive Map	Neshan map for address selection
Form Validation	Real-time browser validation + server validation
Success/Error Messages	SweetAlert2 for results, styled lists for form errors
Responsive Layout	Mobile-first design with breakpoints
Persian Typography	Vazirmatn font with proper RTL support
Smooth Animations	CSS transitions and keyframe animations

📦 Installation Guide

Prerequisites

PHP >= 8.0
MySQL >= 5.7
Composer
Apache/Nginx with mod_rewrite

Step-by-Step Installation

# 1. Clone or download the project
cd /var/www/html/
git clone [repository-url] hekmat-store
cd hekmat-store

# 2. Install Composer dependencies
composer install

# 3. Create .env file
cp .env.example .env

# 4. Edit .env with your database credentials
# DB_HOST, DB_NAME, DB_USER, DB_PASS

# 5. Import database schema
mysql -u root -p database_name < database.sql

# 6. Set document root to /public folder
# Configure Apache VirtualHost or Nginx server block

# 7. Set proper permissions
chmod -R 755 storage/
chmod -R 755 public/assets/

# 8. Access the application
# http://localhost/hekmat-store

Apache Configuration (.htaccess)

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.php?url=$1 [QSA,L]

🌍 Environment Configuration

Create .env file in project root:

# Application
WEB=off                    # "off" for development, "on" for production
PROJECTNAME=hekmat-store
URL=http://localhost/hekmat-store

# Database
DB_HOST=localhost
DB_NAME=hekmat_db
DB_USER=root
DB_PASS=your_password

🚦 Routing

Routes are defined in app/routes/Web.php:

Route::Get("/", "HomeController", "index");
Route::Get("/login", "LoginController", "index");
Route::Post("/login", "LoginController", "login");
Route::Get("/register", "RegisterController", "index");
Route::Post("/register", "RegisterController", "register");
Route::Post("/logout", "LoginController", "logout");
Route::Get("/products", "ProductsController", "categories");
Route::Get("/sub/products", "ProductsController", "subcategories");
Route::Get("/product/:number", "ProductsSingleController", "index");
Route::Post("/comments", "ProductsSingleController", "comment");
Route::Get("/search", "SearchController", "index");
Route::Get("/profile", "ProfileController", "index");
Route::Get("/profile/cart", "ProfileCartController", "index");
Route::Post("/profile/cart", "ProfileCartController", "cart");
Route::Post("/profile/cart/delete/:number", "ProfileCartController", "delete");
Route::Get("/profile/address", "ProfileAddressController", "index");
Route::Post("/profile/address", "ProfileAddressController", "address");
Route::Get("/profile/orders", "ProfileOrdersController", "index");
Route::Get("/profile/edit", "ProfileEditProfileController", "index");
Route::Post("/profile/edit", "ProfileEditProfileController", "change");
Route::Get("/profile/edit/password", "ProfileEditPasswordController", "index");
Route::Post("/profile/edit/password", "ProfileEditPasswordController", "change");

📋 Controllers Reference

Controller	Methods	Description
`HomeController`	`index()`	Homepage with categories, bestsellers, news
`LoginController`	`index()`, `login()`, `logout()`	User authentication
`RegisterController`	`index()`, `register()`	User registration
`ProductsController`	`categories()`, `subcategories()`	Product listing by category/subcategory
`ProductsSingleController`	`index()`, `comment()`	Single product view, comment submission
`SearchController`	`index()`	Product search
`ProfileController`	`index()`	User profile display
`ProfileCartController`	`index()`, `cart()`, `delete()`	Cart management
`ProfileAddressController`	`index()`, `address()`	Address submission & order finalization
`ProfileOrdersController`	`index()`	Order history
`ProfileEditProfileController`	`index()`, `change()`	Profile editing
`ProfileEditPasswordController`	`index()`, `change()`	Password change

📊 Models Reference

Model	Methods	Description
`Categories`	`getAll()`, `getOne()`, `getByParity()`, `countProducts()`	Category operations
`Subcategories`	`getAll()`, `getOne()`, `countProducts()`	Subcategory operations
`Products`	`getAll()`, `getOne()`, `getProductsByCategory()`, `getProductsBySubcategory()`, `getProductBySubcategory()`, `getProductImages()`, `getProductByHighOrder()`	Product operations
`Cart`	`addCart()`, `getCartByUser()`, `SumPriceCart()`, `getOne()`, `deleteCart()`	Cart operations
`Orders`	`getOrdersByUser()`, `add()`, `SumPriceOrders()`	Order operations
`Comments`	`CommentsOfProducts()`, `CommentCount()`, `addComment()`	Comment operations
`Users`	`getOne()`, `getExistsPhone()`, `getExistsPhoneAndPostCodeAndNationalCode()`, `editPhone()`, `updatePassword()`, `editInformation()`, `createCartAddress()`	User operations
`Login`	`CheckUsername()`	Login validation
`Register`	`register()`, `getExistUsernameAndPhone()`	Registration operations
`Search`	`SearchProducts()`, `SearchProductsImages()`	Search operations

🛠️ Helper Functions

Located in app/helpers/helpers.php:

Function	Description
`MakeSecureHash($password)`	Argon2id password hashing
`CheckSecureHashed($hash, $plain)`	Password verification
`periodPath($path)`	Convert dot notation to path
`redirect($path)`	Redirect to URL
`dd($content)`	Dump and die (debugging)
`require_view($path)`	Include view file
`safeEcho($value)`	XSS-safe output
`urlPath($path)`	Generate full URL
`publicPath($path)`	Generate public asset path
`getDbConnection()`	Return PDO instance
`generateToken()`	Generate CSRF token
`validateToken()`	Validate CSRF token
`excel($tableName)`	Export table to Excel
`word($tableName)`	Export table to Word
`csv($tableName)`	Export table to CSV
`tableExport($tableName)`	Export table as SQL

📁 Views Structure

resources/views/
├── partials/
│   ├── inc.start.php          # DOCTYPE, head, preloader
│   ├── inc.end.php            # Closing tags
│   ├── menu.php               # Side menu
│   ├── navbar.php             # Top navigation bar
│   ├── footer.php             # Main footer (4 columns)
│   └── footer_2.php           # Simple footer
├── home/
│   └── index.php              # Homepage
├── login/
│   ├── index.php              # Login form
│   └── welcome.php            # Post-login redirect
├── register/
│   └── index.php              # Registration form
├── products/
│   ├── categories.php         # Products by category
│   ├── subcategories.php      # Products by subcategory
│   └── single.php             # Single product page
├── profile/
│   ├── index.php              # Profile display
│   ├── cart.php               # Shopping cart
│   ├── address.php            # Address form
│   ├── orders.php             # Order history
│   ├── edit-profile.php       # Edit profile form
│   ├── edit-password.php      # Change password form
│   └── inc.menu.php           # Profile sub-menu
├── search/
│   └── index.php              # Search results
└── errors/
    ├── _403_.php
    ├── _404_.php
    └── _500_.php

🌐 API Integrations

Neshan Maps API

Endpoint	Purpose
`https://api.neshan.org/v5/reverse`	Reverse geocoding (lat/lng → address)
Leaflet map tiles	Interactive map display

Configuration:

const CONFIG = {
  mapApiKey: "web.a681e265827c4815adc2bb291fd4b2ae",
  serviceApiKey: "service.d490722192844f6c8aac5f0d3dc6481b",
  defaultCenter: [35.6997, 51.338], // Tehran
  defaultZoom: 13,
};

📱 Browser Support

Browser	Version	Support
Chrome	60+	✅ Full
Firefox	55+	✅ Full
Safari	12+	✅ Full
Edge	79+	✅ Full
Opera	47+	✅ Full
iOS Safari	12+	✅ Full
Android Chrome	80+	✅ Full

🔧 Troubleshooting

Issue	Solution
White screen	Check PHP error log, ensure `.env` exists
Database connection error	Verify credentials in `.env`, check MySQL is running
404 errors	Ensure `.htaccess` is enabled, mod_rewrite active
CSRF token invalid	Clear browser cookies and session, refresh page
Map not loading	Check API keys, ensure internet connection
Images not showing	Verify paths in `/public/assets/images/`
Login redirect loop	Check session configuration, cookie settings

📄 License

MIT – Free for personal and commercial projects.

👨‍💻 Developer

Danial Jamshidi

🙏 Acknowledgements

Swiper.js for carousel functionality
Neshan for mapping services
SweetAlert2 for beautiful alerts
Material Design Icons
Vazirmatn font

A complete e-commerce solution built with PHP MVC – Secure, Scalable, and Feature-Rich 🚀

Name		Name	Last commit message	Last commit date
app		app
public		public
vendor		vendor
.env		.env
.htaccess		.htaccess
README.md		README.md
composer.json		composer.json
hekmat.sql		hekmat.sql

Latest commit

History

Folders and files

Repository files navigation