Skip to content

Commit f4162fd

Browse files
cakmoelcakmoel
committed
docs: update README.md to align with DEVELOPER_GUIDE.md
- Updated PHP requirements and extensions - Added installation wizard steps (21 tables) - Added config.php structure with fallbacks and SMTP config - Added running URLs for Public/Admin/API - Updated directory structure to match guide - Added architecture flow table (Bootstrap → Dispatcher → etc.) - Added feature layering pattern for new features - Added user levels and security features table
1 parent 807a18e commit f4162fd

1 file changed

Lines changed: 159 additions & 46 deletions

File tree

‎README.md‎

Lines changed: 159 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
44
[![PHP Version](https://img.shields.io/badge/PHP-7.4%2B-777BB4.svg)](https://www.php.net/)
5-
[![MySQL Version](https://img.shields.io/badge/MySQL-5.6%2B-4479A1.svg)](https://www.mysql.com/)
5+
[![MySQL Version](https://img.shields.io/badge/MySQL-5.7%2B-4479A1.svg)](https://www.mysql.com/)
66
[![MariaDB Version](https://img.shields.io/badge/MariaDB-10.3%2B-003545.svg)](https://mariadb.org/)
77
[![PSR-12](https://img.shields.io/badge/PSR--12-Compliant-2C2C2C.svg)](https://www.php-fig.org/psr/psr-12/)
88
[![Tests](https://github.com/cakmoel/Scriptlog/workflows/Tests/badge.svg)](https://github.com/cakmoel/Scriptlog/actions/workflows/tests.yml)
@@ -19,98 +19,211 @@ Scriptlog is not designed to replace full-scale CMS frameworks. Instead, it is m
1919
### Core Technologies
2020
- **Backend:** PHP 7.4+ (PSR-12 compliant)
2121
- **Database:** MySQL 5.7+ / MariaDB 10.3+
22-
- **Architecture:** Multi-layered MVC-like (`Request` → `Controller` → `Service` → `DAO` → `Database`)
22+
- **Architecture:** Multi-layered MVC-like (`Request` → `Bootstrap` → `Dispatcher` → `Controller` → `Service` → `DAO` → `Database`)
2323
- **Security:** Laminas (Escaper, Crypt), Defuse PHP Encryption, voku Anti-XSS, HTMLPurifier.
2424

2525
## Requirements
2626

2727
Ensure your hosting environment meets the following requirements:
28-
- **PHP:** 7.4.33 or higher
28+
- **PHP:** 7.4+ (with extensions: `pdo`, `pdo_mysql`, `json`, `mbstring`, `curl`)
2929
- **Web Server:** Apache (with `mod_rewrite` enabled) or Nginx
30-
- **Database:** MySQL 5.6+ or MariaDB 10.3+
31-
- **Extensions:** `pdo`, `mysqli`, `curl`, `gd`, `mbstring`, `fileinfo`, `zip`, `exif`
30+
- **Database:** MySQL 5.7+ or MariaDB 10.3+
31+
- **Composer:** Latest (for dependency management)
3232

3333
## Installation
3434

35-
1. **Download & Extract**
36-
Unzip the package into your web root directory.
35+
1. **Clone the Repository**
36+
```bash
37+
git clone https://github.com/ScriptLog/scriptlog.git
38+
cd scriptlog
39+
```
3740

3841
2. **Install Dependencies**
39-
Scriptlog uses Composer for dependency management.
4042
```bash
4143
composer install
4244
```
4345

4446
3. **Set Permissions**
45-
Ensure the following directories are writeable by the web server user:
46-
- `install/`
47-
- `public/log/`
48-
- `public/cache/`
49-
- `public/themes/`
50-
- `admin/plugins/` (if present)
47+
```bash
48+
chmod -R 755 public/
49+
chmod -R 777 public/cache/ public/log/
50+
```
5151

5252
4. **Database Setup**
5353
Create a new empty database (use `utf8mb4_general_ci` collation).
5454

5555
5. **Run the Installer**
56-
Navigate to `/install/` in your web browser (e.g., `http://your-site.com/install/`) and follow the wizard:
57-
- Requirement Check
58-
- Database Configuration
59-
- Administrator Account Setup
56+
Navigate to `/install/` in your web browser and follow the wizard:
57+
- Step 1: System Requirements Check (`install/index.php`)
58+
- Step 2: Database Setup (`install/setup-db.php`) - creates 21 tables
59+
- Step 3: Complete Setup (`install/finish.php`)
6060

6161
6. **Cleanup (Critical)**
6262
For security purposes, **delete the `install/` directory** immediately after installation is complete.
6363

64+
### Configuration Files
65+
66+
After installation, two configuration files are generated:
67+
68+
| File | Purpose |
69+
|------|---------|
70+
| `config.php` | Main configuration with `$_ENV` fallbacks |
71+
| `.env` | Environment variables (auto-generated) |
72+
| `lib/utility/.lts/lts.txt` | Defuse encryption key for authentication cookies |
73+
6474
## Configuration
6575

66-
If the installer cannot write the configuration file, rename `config.sample.php` to `config.php` and update it manually:
76+
Scriptlog supports both `.env` and `config.php` files for configuration. During installation, both files are automatically generated and kept in sync.
77+
78+
### config.php Structure
6779

6880
```php
81+
<?php
6982
return [
7083
'db' => [
71-
'host' => 'localhost',
72-
'user' => 'your_db_user',
73-
'pass' => 'your_db_password',
74-
'name' => 'your_db_name'
75-
],
84+
'host' => $_ENV['DB_HOST'] ?? 'localhost',
85+
'user' => $_ENV['DB_USER'] ?? '',
86+
'pass' => $_ENV['DB_PASS'] ?? '',
87+
'name' => $_ENV['DB_NAME'] ?? '',
88+
'port' => $_ENV['DB_PORT'] ?? '3306',
89+
'prefix' => $_ENV['DB_PREFIX'] ?? ''
90+
],
7691
'app' => [
77-
'url' => 'http://your-site.com',
78-
'email' => 'admin@example.com',
79-
'key' => 'generated-app-key'
80-
]
92+
'url' => $_ENV['APP_URL'] ?? 'http://example.com',
93+
'email' => $_ENV['APP_EMAIL'] ?? '',
94+
'key' => $_ENV['APP_KEY'] ?? '',
95+
'defuse_key' => 'lib/utility/.lts/lts.txt'
96+
],
97+
'mail' => [
98+
'smtp' => [
99+
'host' => $_ENV['SMTP_HOST'] ?? '',
100+
'port' => $_ENV['SMTP_PORT'] ?? 587,
101+
'encryption' => $_ENV['SMTP_ENCRYPTION'] ?? 'tls',
102+
'username' => $_ENV['SMTP_USER'] ?? '',
103+
'password' => $_ENV['SMTP_PASS'] ?? '',
104+
],
105+
'from' => [
106+
'email' => $_ENV['MAIL_FROM_ADDRESS'] ?? '',
107+
'name' => $_ENV['MAIL_FROM_NAME'] ?? 'Blogware'
108+
]
109+
],
81110
];
82111
```
83112

113+
## Running the Application
114+
115+
| Environment | URL |
116+
|-------------|-----|
117+
| **Public Site** | `http://your-domain/` |
118+
| **Admin Panel** | `http://your-domain/admin/` |
119+
| **API Endpoint** | `http://your-domain/api/v1/` |
120+
84121
## Directory Structure
85122

86-
- `admin/`: Administrator panel logic and UI.
87-
- `lib/`: Core application logic (Controllers, Services, DAOs).
88-
- `public/`: Web root for assets, themes, and user uploads.
89-
- `themes/`: Frontend templates.
90-
- `files/`: User uploads.
91-
- `tests/`: PHPUnit test suite.
92-
- `docs/`: Developer guides and API documentation.
123+
```
124+
ScriptLog/
125+
|-- index.php # Public front controller
126+
|-- config.php # Application configuration
127+
|-- .env # Environment variables
128+
|
129+
|-- admin/ # Admin panel
130+
| |-- index.php # Admin entry point
131+
| |-- login.php # Login page
132+
| +-- ... # Other admin pages
133+
|
134+
|-- api/ # RESTful API
135+
| +-- index.php # API entry point
136+
|
137+
|-- lib/ # Core library
138+
| |-- main.php # Application bootstrap
139+
| |-- common.php # Constants and functions
140+
| +-- core/ # Core classes (Bootstrap, Dispatcher, DbFactory, etc.)
141+
| +-- dao/ # Data Access Objects
142+
| +-- service/ # Business logic layer
143+
| +-- controller/ # Request controllers
144+
| +-- model/ # Data models
145+
| +-- utility/ # Utility functions (100+ files)
146+
| +-- vendor/ # Composer dependencies
147+
|
148+
|-- public/ # Web root
149+
| +-- themes/ # Theme templates
150+
| +-- blog/ # Default theme
151+
| +-- files/ # User uploads (pictures, audio, video, docs)
152+
| +-- cache/ # Cache directory
153+
| +-- log/ # Log directory
154+
|
155+
|-- install/ # Installation wizard
156+
| +-- include/ # Installation includes
157+
|
158+
|-- docs/ # Developer guides
159+
+-- DEVELOPER_GUIDE.md
160+
+-- TESTING_GUIDE.md
161+
+-- PLUGIN_DEVELOPER_GUIDE.md
162+
+-- API_DOCUMENTATION.md
163+
+-- API_OPENAPI.yaml
164+
+-- API_OPENAPI.json
165+
|
166+
+-- tests/ # PHPUnit test suite
167+
```
168+
169+
For detailed architecture and component documentation, see [DEVELOPER_GUIDE.md](src/docs/DEVELOPER_GUIDE.md).
93170

94171
## Development
95172

96173
Scriptlog adheres to **PSR-12** coding standards and uses **Conventional Commits**.
97174

98-
### Key Commands
99-
- **Run Tests:** `vendor/bin/phpunit`
100-
- **Setup Test DB:** `php tests/setup_test_db.php`
175+
### Architecture
176+
177+
Scriptlog uses a **multi-layer architecture** designed for maintainability and scalability:
178+
179+
```
180+
Request → Front Controller → Bootstrap → Dispatcher → Controller → Service → DAO → Database
181+
```
182+
183+
| Step | Component | Location |
184+
|------|-----------|----------|
185+
| 1 | **Front Controller** | `index.php` |
186+
| 2 | **Bootstrap** | `lib/core/Bootstrap.php` |
187+
| 3 | **Dispatcher** | `lib/core/Dispatcher.php` |
188+
| 4 | **Controller** | `lib/controller/*` |
189+
| 5 | **Service** | `lib/service/*` |
190+
| 6 | **DAO** | `lib/dao/*` |
191+
| 7 | **View** | `lib/core/View.php` |
192+
193+
### Adding New Features
101194

102-
### Architecture Pattern
103195
When adding features, follow the layered implementation pattern:
104-
1. **DAO:** `lib/dao/` (Database interactions)
105-
2. **Service:** `lib/service/` (Business logic)
106-
3. **Controller:** `lib/controller/` (Request handling)
196+
1. **Database Table:** Add to `install/include/dbtable.php`
197+
2. **DAO:** Create in `lib/dao/` (Database interactions)
198+
3. **Service:** Create in `lib/service/` (Business logic)
199+
4. **Controller:** Create in `lib/controller/` (Request handling)
200+
5. **Routes:** Add to `lib/core/Bootstrap.php`
201+
202+
> **WARNING:** Never bypass the DAO layer when accessing the database. Always use prepared statements to prevent SQL injection.
203+
204+
### Key Commands
205+
- **Run Tests:** `vendor/bin/phpunit`
206+
- **Static Analysis:** `vendor/bin/phpstan` (see [TESTING_GUIDE.md](src/docs/TESTING_GUIDE.md))
107207

108208
## Security Features
109209

110-
- **Authentication:** Custom secure session handler (`SessionMaker`).
111-
- **CSRF:** Protected via `CSRFGuard` and `csrf_defender`.
112-
- **XSS:** Multi-layered prevention using `Anti-XSS` and `HTMLPurifier`.
113-
- **Encryption:** Sensitive data encrypted using `defuse/php-encryption`.
210+
- **Authentication:** Custom secure session handler (`SessionMaker`) with remember-me tokens and session fingerprinting.
211+
- **CSRF:** Protected via `csrf_defender` and form security utilities.
212+
- **XSS:** Multi-layered prevention using `Anti-XSS` (voku) and `HTMLPurifier`.
213+
- **Encryption:** Sensitive data encrypted using `defuse/php-encryption` with auto-generated keys.
214+
- **Password Hashing:** Uses PHP's built-in `password_hash()` with bcrypt.
215+
- **Access Control:** Role-based user levels with granular permissions.
216+
217+
### User Levels
218+
219+
| Level | Permissions |
220+
|-------|-------------|
221+
| **administrator** | Full access - PRIVACY, USERS, IMPORT, PLUGINS, THEMES, CONFIGURATION, PAGES, NAVIGATION, TOPICS, COMMENTS, MEDIALIB, REPLY, POSTS, DASHBOARD |
222+
| **manager** | PLUGINS, THEMES, CONFIGURATION, PAGES, NAVIGATION, TOPICS, COMMENTS, MEDIALIB, REPLY, POSTS, DASHBOARD |
223+
| **editor** | TOPICS, COMMENTS, MEDIALIB, REPLY, POSTS, DASHBOARD |
224+
| **author** | COMMENTS, MEDIALIB, REPLY, POSTS, DASHBOARD |
225+
| **contributor** | POSTS, DASHBOARD |
226+
| **subscriber** | DASHBOARD only |
114227

115228
## Contributing
116229

0 commit comments

Comments
 (0)