docs(readme): restructure and expand README with features, requirements, and project structure
The README has been significantly updated to provide better project documentation: - Updated project description and metadata formatting - Added comprehensive Features section listing all framework capabilities - Added Requirements table with PHP, Composer, Web Server, and Database versions - Added Project Structure section with directory tree visualization - Removed outdated donation button section
This commit is contained in:
marco
@@ -1,152 +1,337 @@
|
|||||||
# SysMVC
|
# SysMVC
|
||||||
|
|
||||||
## 📌 Project Information
|
**SysMVC** is a lightweight PHP MVC framework created by **Marco Costa** ([syspanel@gmx.com](mailto:syspanel@gmx.com)), licensed under the **MIT License**.
|
||||||
**SysMVC** is a system developed by **Marco Costa** (**syspanel@gmx.com**), with source code licensed under the **MIT License**.
|
|
||||||
|
|
||||||
This software is offered for free and can be used, modified, and distributed under the terms of the MIT License.
|
This software is free to use, modify, and distribute under the terms of the MIT License.
|
||||||
|
|
||||||
Project website: [https://sysmvc.duckdns.org](https://sysmvc.duckdns.org)
|
- **Website:** [https://sysmvc.duckdns.org](https://sysmvc.duckdns.org)
|
||||||
|
- **GitHub:** [https://github.com/syspanel/SysMVC](https://github.com/syspanel/SysMVC)
|
||||||
Github: https://github.com/syspanel/SysMVC.git
|
|
||||||
|
|
||||||
### Support the Project
|
|
||||||
If you find this project useful, consider supporting its development with a donation via PayPal:
|
|
||||||
|
|
||||||
[](https://www.paypal.com/donate/?business=marcocosta@gmx.com¤cy_code=USD)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🚀 Installation Tutorial
|
## Features
|
||||||
|
|
||||||
### ✅ Prerequisites
|
- **MVC Architecture** — clean separation of concerns with Models, Views, and Controllers
|
||||||
- **PHP 7.4** or higher
|
- **ORM (Eloquent)** — database access via `illuminate/database` (Laravel's Eloquent ORM)
|
||||||
- **Composer** (dependency manager for PHP)
|
- **Twin Template Engines** — BladeOne and Twig, configured side by side
|
||||||
- **Web Server** (Apache or Nginx)
|
- **Dependency Injection** — PHP-DI container with autowiring
|
||||||
- **MySQL** or another compatible database
|
- **Routing** — flexible HTTP routing via Pecee SimpleRouter
|
||||||
|
- **CSRF Protection** — built-in token generation and validation
|
||||||
|
- **Security Headers** — applied automatically via `BaseController`
|
||||||
|
- **Input/Output Sanitisation** — `Sanitizer` service with email and URL awareness
|
||||||
|
- **CLI Console** — Symfony Console commands for key generation and database migrations
|
||||||
|
- **Logging** — Monolog writes to `logs/app.log`
|
||||||
|
- **Mail** — Symfony Mailer integration
|
||||||
|
- **Authentication** — Delight Auth and PHP Auth libraries
|
||||||
|
|
||||||
### 🔧 Step-by-Step Guide
|
---
|
||||||
|
|
||||||
#### 1️⃣ Unzip the File
|
## Requirements
|
||||||
Download and unzip the SysMVC file to your local environment:
|
|
||||||
|
|
||||||
bash
|
| Requirement | Version |
|
||||||
unzip sysmvc.zip -d sysmvc
|
|---|---|
|
||||||
cd sysmvc
|
| PHP | >= 7.4 |
|
||||||
|
| Composer | latest stable |
|
||||||
2️⃣ Install Dependencies
|
| Web Server | Apache or Nginx |
|
||||||
|
| Database | MySQL 5.7+ |
|
||||||
Use Composer to install the project dependencies:
|
|
||||||
|
---
|
||||||
composer install
|
|
||||||
|
## Project Structure
|
||||||
3️⃣ Configure the Environment
|
|
||||||
|
```
|
||||||
Copy the .env.example file to .env and configure your environment variables:
|
app/
|
||||||
|
├── app/
|
||||||
cp .env.example .env
|
│ ├── Controllers/ # HTTP controllers
|
||||||
|
│ ├── Models/ # Eloquent models
|
||||||
Open the .env file and edit the following lines with your information:
|
│ ├── Services/ # Shared services (BaseController, Sanitizer)
|
||||||
|
│ └── Console/Command/ # CLI console commands
|
||||||
DB_CONNECTION=mysql
|
├── bootstrap/
|
||||||
DB_HOST=127.0.0.1
|
│ ├── app.php # Bootstrap: loads config, routes, container
|
||||||
DB_PORT=3306
|
│ ├── csrf.php # CSRF token helpers
|
||||||
DB_DATABASE=your_database_name
|
│ └── helpers.php # Global helper functions
|
||||||
DB_USERNAME=your_username
|
├── config/
|
||||||
DB_PASSWORD=your_password
|
│ ├── container.php # DI container definitions (Blade, Twig, Monolog)
|
||||||
|
│ ├── database.php # Eloquent ORM connection setup
|
||||||
4️⃣ Set Permissions
|
│ ├── envread.php # .env loader (defines constants)
|
||||||
|
│ ├── paths.php # VIEWS_PATH and CACHE_PATH constants
|
||||||
Change the permissions for the storage and cache directories to ensure the web server can write to them:
|
│ └── templateengine.php # CSRF template helpers
|
||||||
|
├── database/
|
||||||
chmod -R 775 storage
|
│ └── crudexample.sql # Sample SQL schema
|
||||||
chmod -R 775 bootstrap/cache
|
├── routes/
|
||||||
|
│ ├── web.php # Web routes
|
||||||
5️⃣ Generate the Application Key
|
│ ├── api.php # API routes (extend as needed)
|
||||||
|
│ └── auth.php # Auth routes (extend as needed)
|
||||||
php bin/console generate:app-key
|
├── resources/views/ # Blade and Twig template files
|
||||||
|
├── public/
|
||||||
6️⃣ Run Migrations
|
│ └── index.php # Application entry point
|
||||||
|
├── storage/ # Uploads and generated files
|
||||||
Run the migrations to create the tables in the database:
|
├── cache/ # Compiled template cache
|
||||||
|
├── logs/ # Application log files
|
||||||
php bin/console migrate
|
├── tests/
|
||||||
|
│ ├── Feature/ # Feature tests
|
||||||
7️⃣ Configure the Web Server
|
│ └── Unit/ # Unit tests
|
||||||
📌 Apache
|
├── bin/
|
||||||
|
│ └── console # CLI entry point
|
||||||
Add the following configuration to your Apache configuration file:
|
├── composer.json
|
||||||
|
└── .env # Environment configuration (gitignored)
|
||||||
<VirtualHost *:80>
|
```
|
||||||
ServerName sysmvc.local
|
|
||||||
DocumentRoot /path/to/sysmvc/public
|
---
|
||||||
|
|
||||||
<Directory /path/to/sysmvc/public>
|
## Installation
|
||||||
AllowOverride All
|
|
||||||
Require all granted
|
### 1. Clone or unzip the project
|
||||||
</Directory>
|
|
||||||
</VirtualHost>
|
```bash
|
||||||
|
unzip sysmvc.zip -d sysmvc
|
||||||
📌 Nginx
|
cd sysmvc
|
||||||
|
```
|
||||||
Add the following configuration to your Nginx configuration file:
|
|
||||||
|
### 2. Install PHP dependencies
|
||||||
server {
|
|
||||||
listen 80;
|
```bash
|
||||||
server_name sysmvc.local;
|
composer install
|
||||||
root /path/to/sysmvc/public;
|
```
|
||||||
|
|
||||||
index index.php index.html index.htm;
|
### 3. Configure the environment
|
||||||
|
|
||||||
location / {
|
```bash
|
||||||
try_files $uri $uri/ /index.php?$query_string;
|
cp .env.example .env
|
||||||
}
|
```
|
||||||
|
|
||||||
location ~ \.php$ {
|
Edit `.env` with your database and application settings:
|
||||||
include snippets/fastcgi-php.conf;
|
|
||||||
fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
|
```ini
|
||||||
}
|
# Application
|
||||||
|
APP_NAME=SysMVC
|
||||||
|
APP_ENV=production
|
||||||
|
APP_DEBUG=false
|
||||||
|
APP_URL=http://localhost:16270
|
||||||
|
|
||||||
|
# Database
|
||||||
|
DB_CONNECTION=mysql
|
||||||
|
DB_HOST=127.0.0.1
|
||||||
|
DB_PORT=3306
|
||||||
|
DB_DATABASE=your_database_name
|
||||||
|
DB_USERNAME=your_username
|
||||||
|
DB_PASSWORD=your_password
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Set directory permissions
|
||||||
|
|
||||||
|
```bash
|
||||||
|
chmod -R 775 storage
|
||||||
|
chmod -R 775 cache
|
||||||
|
chmod -R 775 logs
|
||||||
|
chmod -R 775 bootstrap/cache
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Generate the application key
|
||||||
|
|
||||||
|
```bash
|
||||||
|
php bin/console generate:app-key
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Set up the database
|
||||||
|
|
||||||
|
Create the database manually or run the sample migration command:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
php bin/console migrate:crudexample
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Configure the web server
|
||||||
|
|
||||||
|
**Apache** — add a virtual host pointing to the `public/` directory:
|
||||||
|
|
||||||
|
```apache
|
||||||
|
<VirtualHost *:80>
|
||||||
|
ServerName sysmvc.local
|
||||||
|
DocumentRoot /path/to/sysmvc/public
|
||||||
|
|
||||||
|
<Directory /path/to/sysmvc/public>
|
||||||
|
AllowOverride All
|
||||||
|
Require all granted
|
||||||
|
</Directory>
|
||||||
|
</VirtualHost>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Nginx** — add a server block pointing to the `public/` directory:
|
||||||
|
|
||||||
|
```nginx
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
server_name sysmvc.local;
|
||||||
|
root /path/to/sysmvc/public;
|
||||||
|
|
||||||
|
index index.php index.html;
|
||||||
|
|
||||||
|
location / {
|
||||||
|
try_files $uri $uri/ /index.php?$query_string;
|
||||||
}
|
}
|
||||||
|
|
||||||
📦 Dependencies Used
|
location ~ \.php$ {
|
||||||
|
include snippets/fastcgi-php.conf;
|
||||||
|
fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
The project uses the following third-party packages, each with its respective license:
|
---
|
||||||
✅ Packages with MIT License
|
|
||||||
|
|
||||||
Illuminate Database → illuminate/database
|
## CLI Commands
|
||||||
Monolog → monolog/monolog
|
|
||||||
BladeOne → eftec/bladeone
|
|
||||||
Twig → twig/twig
|
|
||||||
Symfony Console → symfony/console
|
|
||||||
Phinx → robmorgan/phinx
|
|
||||||
Defuse Encryption → defuse/php-encryption
|
|
||||||
Random Compatibility → paragonie/random_compat
|
|
||||||
Rakit Validation → rakit/validation
|
|
||||||
Carbon → nesbot/carbon
|
|
||||||
Flysystem → league/flysystem
|
|
||||||
Intervention Image → intervention/image
|
|
||||||
Symfony Cache → symfony/cache
|
|
||||||
Predis Redis Client → predis/predis
|
|
||||||
PHP Dependency Injection → php-di/php-di
|
|
||||||
Symfony Dotenv → symfony/dotenv
|
|
||||||
BladeOne HTML → eftec/bladeonehtml
|
|
||||||
Pecee SimpleRouter → pecee/simple-router
|
|
||||||
Nyholm PSR7 → nyholm/psr7
|
|
||||||
FakerPHP Faker → fakerphp/faker
|
|
||||||
Symfony Mailer → symfony/mailer
|
|
||||||
|
|
||||||
📜 Terms of Use
|
All CLI commands are available through the `bin/console` entry point:
|
||||||
|
|
||||||
This project is licensed under the MIT License.
|
```bash
|
||||||
|
php bin/console [command]
|
||||||
|
```
|
||||||
|
|
||||||
You can use, copy, modify, merge, publish, distribute, sublicense, or sell copies of the Software, as long as the license and copyright notice are included in all copies or substantial portions of the Software.
|
| Command | Description |
|
||||||
|
|---|---|
|
||||||
|
| `generate:app-key` | Generates a new `APP_KEY` and writes it to `.env` |
|
||||||
|
| `generate:api-keys` | Generates `API_PUBLIC_KEY` and `API_SECRET_KEY` in `.env` |
|
||||||
|
| `migrate:crudexample` | Creates the `crudexample` table with 30 sample records |
|
||||||
|
| `say:hello` | Example / demo command |
|
||||||
|
|
||||||
The Software is provided "as is", without warranties of any kind. For more details, see the MIT License.
|
---
|
||||||
|
|
||||||
For more information, contact: marcocosta@gmx.com
|
## Routing
|
||||||
|
|
||||||
### Support the Project
|
Routes are defined in `routes/web.php` using Pecee SimpleRouter syntax.
|
||||||
If you find this project useful, consider supporting its development with a donation via PayPal:
|
|
||||||
|
|
||||||
[](https://www.paypal.com/donate/?business=marcocosta@gmx.com¤cy_code=USD)
|
### Example routes
|
||||||
|
|
||||||
© 2025 Marco Costa - All rights reserved under the MIT License.
|
```php
|
||||||
|
Router::get('/', [HomeController::class, 'index'])->name('home');
|
||||||
|
Router::get('/about', function () { ... })->name('about');
|
||||||
|
Router::post('/crudexample', [CrudExampleController::class, 'store'])->name('crudexample.store');
|
||||||
|
```
|
||||||
|
|
||||||
|
### Route groups
|
||||||
|
|
||||||
|
```php
|
||||||
|
Router::group(['prefix' => '/crudexample'], function () {
|
||||||
|
Router::get('/', 'CrudExampleController@index')->name('crudexample.index');
|
||||||
|
Router::get('/create', 'CrudExampleController@create')->name('crudexample.create');
|
||||||
|
Router::get('/edit/{id}', 'CrudExampleController@edit')->name('crudexample.edit');
|
||||||
|
Router::post('/store', 'CrudExampleController@store')->name('crudexample.store');
|
||||||
|
Router::post('/update/{id}', 'CrudExampleController@update')->name('crudexample.update');
|
||||||
|
Router::post('/delete/{id}', 'CrudExampleController@delete')->name('crudexample.delete');
|
||||||
|
Router::get('/show/{id}', 'CrudExampleController@show')->name('crudexample.show');
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
404 errors are handled by a global error handler that renders `resources/views/errors/404.html`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Security
|
||||||
|
|
||||||
|
SysMVC includes multiple security layers, all applied automatically.
|
||||||
|
|
||||||
|
### Security Headers (`BaseController`)
|
||||||
|
|
||||||
|
Applied to every controller that extends `BaseController`:
|
||||||
|
|
||||||
|
| Header | Value |
|
||||||
|
|---|---|
|
||||||
|
| `Content-Security-Policy` | `default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:` |
|
||||||
|
| `X-Frame-Options` | `DENY` |
|
||||||
|
| `X-Content-Type-Options` | `nosniff` |
|
||||||
|
| `Referrer-Policy` | `no-referrer` |
|
||||||
|
| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains; preload` |
|
||||||
|
|
||||||
|
### CSRF Protection
|
||||||
|
|
||||||
|
Tokens are generated per session via `generateCsrfToken()` in `bootstrap/csrf.php`. Include the hidden field in forms with:
|
||||||
|
|
||||||
|
```php
|
||||||
|
<?= csrf() ?>
|
||||||
|
<!-- or -->
|
||||||
|
<input type="hidden" name="csrf_token" value="<?= getCsrfToken() ?>">
|
||||||
|
```
|
||||||
|
|
||||||
|
### Input Sanitisation
|
||||||
|
|
||||||
|
All form inputs are sanitised through `Sanitizer::sanitizeInput()` before storage. Output escaping is applied via `Sanitizer::sanitizeOutput()` before rendering.
|
||||||
|
|
||||||
|
### Password Storage
|
||||||
|
|
||||||
|
Passwords are hashed with `password_hash($password, PASSWORD_BCRYPT)` before being persisted.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Environment Variables
|
||||||
|
|
||||||
|
Key environment variables loaded from `.env`:
|
||||||
|
|
||||||
|
| Variable | Default | Description |
|
||||||
|
|---|---|---|
|
||||||
|
| `APP_NAME` | `SysMVC` | Application name |
|
||||||
|
| `APP_KEY` | — | Random encryption key |
|
||||||
|
| `APP_ENV` | `production` | Environment: `production` / `local` / `testing` |
|
||||||
|
| `APP_DEBUG` | `false` | Display error details |
|
||||||
|
| `APP_URL` | — | Base URL of the application |
|
||||||
|
| `DB_CONNECTION` | `mysql` | Database driver |
|
||||||
|
| `DB_HOST` | `127.0.0.1` | Database host |
|
||||||
|
| `DB_PORT` | `3306` | Database port |
|
||||||
|
| `DB_DATABASE` | — | Database name |
|
||||||
|
| `DB_USERNAME` | — | Database user |
|
||||||
|
| `DB_PASSWORD` | — | Database password |
|
||||||
|
| `SESSION_DRIVER` | `file` | Session driver |
|
||||||
|
| `SESSION_LIFETIME` | `120` | Session duration in minutes |
|
||||||
|
|
||||||
|
PHP runtime settings are also configurable via `PHP_MEMORY_LIMIT`, `PHP_MAX_EXECUTION_TIME`, `PHP_DISPLAY_ERRORS`, and related variables in `.env`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Dependencies
|
||||||
|
|
||||||
|
| Package | Version | License |
|
||||||
|
|---|---|---|
|
||||||
|
| `illuminate/database` | ^8.0 | MIT |
|
||||||
|
| `phpauth/phpauth` | ^1.0 | MIT |
|
||||||
|
| `monolog/monolog` | ^2.0 | MIT |
|
||||||
|
| `eftec/bladeone` | ^4.0 | MIT |
|
||||||
|
| `eftec/bladeonehtml` | ^2.5 | MIT |
|
||||||
|
| `twig/twig` | ^3.20 | BSD-3-Clause |
|
||||||
|
| `symfony/console` | ^5.0 | MIT |
|
||||||
|
| `symfony/mailer` | ^7.2 | MIT |
|
||||||
|
| `symfony/cache` | ^5.0 | MIT |
|
||||||
|
| `symfony/dotenv` | ^6.4 | MIT |
|
||||||
|
| `symfony/event-dispatcher` | ^5.0 | MIT |
|
||||||
|
| `symfony/filesystem` | ^5.0 | MIT |
|
||||||
|
| `symfony/translation` | ^5.0 | MIT |
|
||||||
|
| `symfony/mime` | ^6.4 | MIT |
|
||||||
|
| `robmorgan/phinx` | ^0.12.0 | MIT |
|
||||||
|
| `defuse/php-encryption` | ^2.2 | MIT |
|
||||||
|
| `paragonie/random_compat` | ^9.99 | MIT |
|
||||||
|
| `rakit/validation` | ^1.4 | MIT |
|
||||||
|
| `nesbot/carbon` | ^2.0 | MIT |
|
||||||
|
| `league/flysystem` | ^1.1 | MIT |
|
||||||
|
| `intervention/image` | ^2.5 | MIT |
|
||||||
|
| `predis/predis` | ^1.1 | MIT |
|
||||||
|
| `php-di/php-di` | ^7.0 | MIT |
|
||||||
|
| `pecee/simple-router` | ^5.4 | MIT |
|
||||||
|
| `nyholm/psr7` | ^1.8 | MIT |
|
||||||
|
| `fakerphp/faker` | ^1.24 | MIT |
|
||||||
|
| `delight-im/auth` | ^8.3 | MIT |
|
||||||
|
| `delight-im/db` | ^8.3 | MIT |
|
||||||
|
| `delight-im/cookie` | ^8.3 | MIT |
|
||||||
|
| `delight-im/http` | ^8.3 | MIT |
|
||||||
|
| `google/recaptcha` | ^1.2 | BSD-3-Clause |
|
||||||
|
| `guzzlehttp/guzzle` | ^7.0 | MIT |
|
||||||
|
| `guzzlehttp/promises` | ^1.5 | MIT |
|
||||||
|
| `guzzlehttp/psr7` | ^2.0 | MIT |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
This project is licensed under the **MIT License**. You may use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software, provided the original license and copyright notice are included.
|
||||||
|
|
||||||
|
See [LICENSE](LICENSE) for the full license text.
|
||||||
|
|
||||||
|
© 2025 Marco Costa — All rights reserved under the MIT License.
|
||||||
|
|||||||
Reference in New Issue
Block a user