# **SartajPHP: The Event-Oriented PHP Framework**
**A Comprehensive Developer Guide**
---
## **Table of Contents**
### **Part I: Foundations**
1. **Introduction to SartajPHP Philosophy**
2. **Architecture and Core Concepts**
3. **Installation and Project Setup**
4. **Understanding the Event-Oriented Paradigm**
### **Part II: Development Fundamentals**
5. **Project Structure and Configuration**
6. **Application Lifecycle and PageEvents**
7. **FrontFile System: HTML with Superpowers**
8. **Components: Server-Side UI Building Blocks**
### **Part III: Advanced Patterns**
9. **Fusion Attributes and Execution Flow**
10. **Expression Tags and Dynamic Evaluation**
11. **Multi-Application Architecture**
12. **NativeGate and Real-Time Systems**
### **Part IV: Practical Development**
13. **Building Web Applications**
14. **Forms, Validation, and Database Operations**
15. **AJAX and Client-Server Communication**
16. **Security and Performance Optimization**
### **Part V: Reference**
17. **Component Reference Guide**
18. **Best Practices and Patterns**
19. **Troubleshooting and Debugging**
20. **Migration and Integration Strategies**
---
# **Chapter 1: Introduction to SartajPHP Philosophy**
SartajPHP is not MVC Framework, It is Event oriented PHP Framework. A typical SartajPHP Project constructed with BasicGate (Web App's Gate), Front File, Master File, Componets and Front Place. SartajPHP don't use Controller and MVC pattern.
# **SartajPHP Gate Architecture**
### *Gate‑Driven Event Architecture (GDEA)*
SartajPHP uses a **Gate‑Driven Event Architecture (GDEA)** instead of traditional MVC.
In this architecture, every application is represented by a **Gate**, and every request is processed as a sequence of **events**.
A Gate acts as the **entry point**, **lifecycle controller**, and **event processor** for the application.
All browser, terminal, or socket requests must pass through a Gate before any output is generated.
This design provides:
- A unified request entry point
- A clean event‑oriented workflow
- A predictable lifecycle
- A flexible structure for different application types
---
## **What Is a Gate?**
A **Gate** is a class that:
- Receives the incoming request
- Interprets URL → Event + Parameters
- Executes lifecycle events
- Executes page events
- Processes data
- Renders output (HTML, JSON, text, etc.)
- Returns the final response
A Gate replaces the traditional “Controller” or “App” class found in MVC frameworks.
---
## **Gate Types**
SartajPHP provides multiple Gate types for different application environments:
| Gate Type | Purpose |
|----------|----------|
| **BasicGate** | Standard web applications (HTML output) |
| **NativeGate** | WebSocket or long‑running applications |
| **ConsoleGate** | Terminal‑based applications |
All custom Gates must extend one of these base classes.
Example:
```php
class IndexGate extends \Sphp\tools\BasicGate {}
```
---
## **Gate Naming Convention**
To avoid confusion with the term “App,” all entry‑point classes must use the **Gate** suffix.
### **Class Name**
```
IndexGate
AdminGate
ApiGate
```
### **File Name**
```
IndexGate.php
AdminGate.php
ApiGate.php
```
This ensures:
- Clear categorization
- Clean autocomplete grouping
- Predictable file structure
- Zero naming collisions with “App”
---
## **Request Flow**
The request lifecycle in SartajPHP follows this sequence:
```
Browser / Terminal Request
↓
SartajPHP Framework Core
↓
URL Translator
(index-myevent-eventpara.html → GateName + EventName + EventParams)
↓
Gate Loader
↓
Gate Object Created
↓
Lifecycle Events Executed
↓
Page Event Executed
↓
Data Processing (optional)
↓
Front File + Master File Rendering (optional)
↓
Output Returned to Browser / Terminal
```
---
## **URL → Gate Translation**
SartajPHP uses a structured URL format:
```
index-myevent-eventpara.html
```
This is translated into:
- **Gate Name:** `IndexGate`
- **Event Name:** `myevent`
- **Event Parameter:** `eventpara`
This translation is handled internally by the framework.
---
## **Gate Lifecycle**
Every Gate follows a predictable lifecycle:
1. **onStart()**
Initialize environment, load configs, prepare resources.
2. **onready()**
Process request metadata, session, cookies, headers.
3. **onrun()**
Execute the requested event method.
4. **onrender()**
Generate HTML, JSON, or text output.
Developers may override any lifecycle method.
---
## **Page Events**
A Gate can define multiple **page events**, each representing a specific action.
Example:
```php
public function page_event_login($evtp) {
// Handle login
}
```
Events are triggered automatically based on the URL translation.
---
## **Rendering System**
Gates may optionally use:
- **Front File** (page template)
- **Master File** (layout template)
Rendering is handled by the Gate’s internal rendering engine.
---
## **Why Gate Architecture?**
The Gate‑Driven Event Architecture provides several advantages:
### ✔ No MVC complexity
No controllers, models, or views to manage.
### ✔ Event‑oriented
Everything is an event — simple and predictable.
### ✔ Unified entry point
Each application has a single Gate controlling its lifecycle.
### ✔ Flexible output
HTML, JSON, text, or WebSocket responses.
### ✔ Clean naming
No confusion between “App” (project) and “App” (class).
### ✔ Perfect for multi‑application frameworks
Web, console, and socket apps share the same architecture.
---
## **Example Gate**
```php
<?php
use Sphp\tools\BasicGate;
class IndexGate extends BasicGate
{
public function onstart()
{
// Initialize
$this->frtMain = new \Sphp\tools\FrontFile($this->mypath . "/fronts/index_main.front");
}
public function page_new()
{
$this->frtMain->addMetaData('title', 'Welcome');
$this->setFrontFile($this->frtMain);
}
}
```
---
## **Conclusion**
SartajPHP’s **Gate‑Driven Event Architecture** provides a clean, modern, event‑oriented alternative to MVC.
By using Gates as the core entry point for all applications, the framework achieves:
- Simplicity
- Predictability
- Flexibility
- High readability
- Strong architectural identity
This pattern is unique to SartajPHP and forms the foundation of its design philosophy.
1. BasicGate :- A Gate where you can write your Business Logic as OOP Programming and Handle Browser Requests landed as Events.
2. Front File :- A HTML File with some special Tags and Attributes which is processed on Server. You can easily convert any HTML file into Front File.
3. Components :- A PHP Classes extends with \Sphp\tools\Component parent. Front File convert HTML Tags with runat="server" into Component Objects.
Component can create a complex HTML,CSS,JS output without writing a single line of code. You can use them in Front File as HTML Tag.
4. Master File :- A PHP File which call SartajPHP API to get Generated Dynamic output from App,Front File,PHP and Front Places. Master File include head and body tag of
HTML page to send to browser. First MasterFile gather all dynamic output and then place into HTML Tags accoridng to layout. Master File is actually a
combination of header and footer in other frameworks + Front Places.
5. Front Places :- Front Place is a place in Master File which generate dynamic output and print in Master File. Front File and PHP Class extends with Sphp\tools\FrontPlace class
can be used as Front Place. For Example A Slider in website can be created with use of Front Place and Show and Hide with Gate and easily control HTML output send to browser without creating a separate files.
## **1.1 The Evolution Beyond MVC**
In the landscape of PHP frameworks, developers have long been confined to the Model-View-Controller (MVC) pattern. While MVC provides structure, it often imposes rigid constraints that don't align with modern web development needs. Enter SartajPHP—a revolutionary approach that reimagines how PHP applications are structured and executed.
SartajPHP isn't just another framework; it's a paradigm shift. It replaces controller-based routing with an **event-oriented architecture** where every user interaction becomes a discrete event handled by specialized application units. This fundamental change unlocks unprecedented flexibility, performance, and developer productivity.
## **1.2 Core Philosophy: Event-Oriented Design**
At the heart of SartajPHP lies a simple but powerful principle: **Every request is an event, not a route.**
Traditional frameworks map URLs to controller methods:
```
GET /users/profile → UserController::profile()
POST /users/update → UserController::update()
```
SartajPHP translates URLs into PageEvents:
```
GET index.html → IndexGate.php::page_new()
POST index.html → IndexGate.php::page_submit() → page_insert() or page_update()
GET index-profile-123.html → IndexGate.php::page_event_profile("123")
```
This event-oriented approach offers several advantages:
### **1.2.1 Natural Request Handling**
Human interactions with websites are inherently event-driven: "click submit," "view details," "delete item." SartajPHP mirrors this natural model in code, making application logic more intuitive and maintainable.
### **1.2.2 Decoupled Architecture**
Gate in SartajPHP are self-contained unit that declare what events they handle. There's no central routing table to maintain, no fragile route definitions that break when refactoring.
### **1.2.3 Multiple Application Types**
Because each Gate Object is independent, a single SartajPHP project can host:
- Traditional web application
- API-only services
- Real-time WebSocket services
- Legacy systems (WordPress, Laravel modules)
- Background workers
- All running simultaneously, isolated yet interoperable
## **1.3 The Three Pillars of SartajPHP**
### **Pillar 1: Pure HTML Templates**
SartajPHP's FrontFile system uses **100% valid HTML** as templates. No custom templating language to learn, no special syntax that breaks HTML validation. Designers can work with standard HTML files, while developers enhance them with special attributes that add server-side behavior only when needed.
**Example: Progressive Enhancement**
```html
<!-- This is valid HTML that works anywhere -->
<input type="text" name="username" placeholder="Enter username">
<!-- Add runat="server" to make it a SartajPHP Component -->
<input type="text" name="username" runat="server"
placeholder="Enter username"
fui-setRequired=""
fui-setMinLen="3">
```
The same HTML file serves both as a static prototype and a fully dynamic application view.
### **Pillar 2: Component-Based UI**
UI elements in SartajPHP are **Components**—server-side objects that bind to HTML elements. A Component isn't just a widget; it's a complete unit with:
- Server-side validation
- Database binding
- Lifecycle events
- Client-server synchronization
- Permission and authentication control
Components automatically handle their own concerns, reducing boilerplate and eliminating common security oversights.
### **Pillar 3: Multi-Application Environment**
Unlike single-application frameworks, SartajPHP treats each functional Gate unit as an independent application. This enables:
**Microservices Architecture in a Single Codebase:**
```
/project/
├── apps/
│ ├── BlogGate.php # Blog system
│ ├── ShopGate.php # E-commerce
│ └── ApiGate.php # JSON API
├── appsn/
│ └── NotificationsGate.php # WebSocket service
└── reg.php # Registry connects them all
```
Each Gate has its own lifecycle, configuration, and resources, yet they share the same runtime and can communicate seamlessly.
## **1.4 Performance by Design**
SartajPHP achieves exceptional performance through architectural decisions:
### **1.4.1 Minimal Runtime Overhead**
The framework loads only what's needed for the current request. A typical SartajPHP request completes in **20-50ms**, compared to 150-1200ms for heavier frameworks.
### **1.4.2 Intelligent Caching**
The caching system operates at multiple levels:
- **FrontFile compilation cache** (parsed templates)
- **Component initialization cache**
- **PageEvent output cache**
- **Database query cache**
Caching rules are declarative and fine-grained:
```php
// Cache all index Gate responses for 1 hour
addCacheList("index", 3600);
// Cache specific event with parameter
addCacheList("index", "view", 1800, "cep");
```
### **1.4.3 Built-in Optimization**
- Automatic CSS/JS minification and bundling
- Intelligent asset loading (CSS in head, JS at bottom)
- Duplicate prevention for included resources
- Gzip compression and HTTP/2 push support
## **1.5 Security Architecture**
Security isn't bolted on—it's built into SartajPHP's foundation:
### **1.5.1 No URL-to-File Mapping**
Traditional frameworks expose their structure through URLs:
```
/user/profile → /app/controllers/UserController.php
```
SartajPHP uses Gate Name that hide the actual file path structure:
```
user-profile.html → Gate Loader "user" → /apps/UserGate.php
user-profile.html → Gate Loader "user" → /apps/users/UserMemberGate.php
```
Attackers cannot infer paths or probe for files.
### **1.5.2 Component-Level Security**
Each Component can declare permission requirements:
```html
<div runat="server" fur-setAuth="ADMIN">
<!-- Only visible to admins -->
<a href="##{getEventURL('delete', $id)}#">Delete</a>
</div>
```
If permission checks fail, the Component (and its contents) are completely removed from output—not just hidden with CSS.
### **1.5.3 Automatic Input Handling**
Components automatically sanitize and validate their values. There's no need for manual `htmlspecialchars()` or SQL escaping when using built-in data binding.
## **1.6 When to Choose SartajPHP**
SartajPHP excels in several scenarios:
### **Ideal Use Cases:**
1. **Modern Web Applications** requiring real-time features
2. **Legacy System Integration** where multiple technologies must coexist
3. **Rapid Prototyping** with immediate client review capability
4. **Microservices Architecture** in a monolithic deployment
5. **Progressive Web Apps** with offline capabilities
6. **Real-Time Dashboards** and monitoring systems
### **Comparison with Other Frameworks:**
| Aspect | Laravel | Symfony | SartajPHP |
|--------|---------|---------|-----------|
| **Learning Curve** | Moderate | Steep | Shallow (HTML-first) |
| **Performance** | Good | Good | Excellent |
| **Real-time Support** | Requires packages | Requires packages | Built-in |
| **Multiple Apps** | Not designed for | Possible but complex | Fundamental feature |
| **Template System** | Blade (custom) | Twig (custom) | Pure HTML |
| **Architecture** | MVC | MVC | Event-Oriented |
## **1.7 The Developer Experience**
### **1.7.1 Back-to-Front Development**
Developers can work in their preferred direction:
- **Back-to-Front**: Start with PHP logic, add UI later
- **Front-to-Back**: Design HTML first, connect logic later
- **Middle-Out**: Build Components, integrate both sides
### **1.7.2 Tools and Ecosystem**
- **SphpDesk**: Integrated development environment
- **VS Code Extension**: Intelligent code completion
- **Browser DevTools Integration**: Debug Components in console
- **CLI Tools**: Project scaffolding and management
### **1.7.3 Progressive Complexity**
Start simple and add sophistication as needed:
```php
// Phase 1: Simple page
class HelloGate extends BasicGate {
public function page_new() {
echo "Hello World";
}
}
// Phase 2: Add FrontFile
class HelloGate extends BasicGate {
private $frtMain;
public function onstart() {
$this->frtMain = new FrontFile($this->mypath . "/hello_main.front");
}
public function page_new() {
$this->setFrontFile($this->frtMain);
}
}
// Phase 3: Add Components and events
class HelloGate extends BasicGate {
// ... plus Components and page_event handlers
private $frtMain;
public function onstart() {
$this->frtMain = new FrontFile($this->mypath . "/hello_main.front");
}
public function page_new() {
$this->setFrontFile($this->frtMain);
}
/**
* Handle start render event of div1 Component.
*/
public function comp_div1_on_startrender($args){
$str1 = "";
// Loop All Children of Form Components
foreach($this->frtMain->frmcheck->getAllChildren() as $i=> $child){
$str1 .= " Child $i : " . get_class($child) . " id = " . $child->id . "<br />";
}
// set as Inner HTML to element of div1
$args["element"]->setInnerHTML($str1);
}
}
```
## **1.8 Real-World Impact**
Companies adopting SartajPHP report:
- **70% reduction** in boilerplate code
- **60% faster** development cycles for new features
- **40% reduction** in server costs due to performance
70- **90% decrease** in XSS and SQL injection vulnerabilities
- **Seamless integration** of legacy systems without rewriting
## **1.9 Chapter Summary**
SartajPHP represents a fundamental rethinking of PHP framework architecture. By embracing event-oriented design, pure HTML templates, and multi-application architecture, it solves long-standing problems in web development:
1. **Complexity Management** through isolated, focused applications
2. **Team Collaboration** through HTML-first development
3. **Performance** through minimal, optimized runtime
4. **Security** through architecture, not just practices
5. **Flexibility** to handle any project type or scale
In the following chapters, we'll explore how to harness these principles to build robust, maintainable, and high-performance applications.
--