# **Chapter 1: Gate-Driven Event Architecture - The Core Foundation**
> **File Extension Reference:**
> - Gate Files: `*.gate.php` (e.g., `Index.gate.php`)
> - Front Files: `*.front` (e.g., `index_main.front`)
> - Master Files: `*.mast.php` (e.g., `default/master.mast.php`)
> - Front Places: `*.place.front` or `*.place.php`
---
## **1.1 What is Gate-Driven Event Architecture?**
SartajPhp uses a **Gate-Driven Event Architecture (GDEA)** where an Application can have multiple **Gates**, and each browser request is handled by a specific Gate through a **Page Event**.
### **Understanding Gate vs Application**
Think of it this way:
- **Application** = Your complete software system (the whole website/app)
- **Gate** = An entry point within the Application (like a door/gate) that handles requests for a specific area
- **Page Event** = An Event Trigger by Browser URL and handle by a method in your Gate Class
- **URL** = Maps to Gate + Event + Parameters
```
Application (Your Website)
│
├── Gate: index → handles index.html, index-view-5.html
├── Gate: blog → handles blog.html, blog-search-php.html
├── Gate: admin → handles admin.html, admin-users.html
└── Gate: shop → handles shop.html, shop-products.html
```
**A Gate is the Application's Gate** - it allows user requests to enter into specific parts of your application, processes those requests, and sends responses back to the user. One Application can have multiple Gates, each reserved by a unique "request-word" (the gate name in the URL).
### **How a Gate Works**
```
Browser Request: blog-view-5.html
↓
Gate: blog (reserved word "blog")
↓
Event: view (maps to page_view())
Parameter: 5 (available via $this->page->evtp)
↓
Output: HTML rendered from Front File + Master File
```
The URL segment before the first hyphen (or before .html) is the "request-word" that maps to a specific Gate class.
## **1.2 Why Not MVC?**
Traditional MVC has issues as applications grow:
- Routes become complex and hard to maintain
- Controllers get bloated with too many responsibilities
- URL changes break existing code
SartajPhp solves this with events:
- **No routing configuration needed** - URL directly maps to method
- **Natural organization** - Related functionality groups in events
- **Easy to extend** - Add new events without changing existing code
## **1.3 The Three Types of Gates**
SartajPhp provides different Gate types for different purposes:
| Gate Type | Use Case | Extension |
|-----------|----------|-----------|
| **BasicGate** | Standard web applications | `*.gate.php` |
| **NativeGate** | WebSocket/real-time apps | `*.gate.php` |
| **ConsoleGate** | CLI applications | `*.gate.php` |
For web development, we use `BasicGate`.
## **1.4 BasicGate Structure**
Here's what a basic Gate class looks like:
```php
<?php
// apps/Index.gate.php
use Sphp\tools\BasicGate;
class Index extends BasicGate
{
// Your application code goes here
}
```
This simple class becomes your web application entry point.
## **1.5 Understanding Page Events**
Page Events are methods in your Gate class that handle browser requests. There are two types:
### **Built-in Page Events**
These are automatically triggered based on URL and Post Data. They do NOT receive the event parameter directly - access it via `$this->page->evtp` or `$this->getEventParameter()`:
```php
// URL: blog-view-5.html → calls page_view() (NO parameter passed)
// Access parameter via $this->page->evtp
public function page_view()
{
$recordId = $this->page->evtp; // Returns "5"
// Or use: $this->getEventParameter()
}
```
| Page Event | URL Pattern | Parameter Access | Triggered When |
|------------|-------------|-------------------|----------------|
| `page_new()` | `gate.html` | `$this->page->evtp` | Browser loads page (GET) |
| `page_submit()` | `gate.html` | `$this->page->evtp` | Form is submitted (POST) |
| `page_insert()` | `gate.html` | `$this->page->evtp` | Auto-triggered after `page_submit()` for new records |
| `page_update()` | `gate.html` | `$this->page->evtp` | Auto-triggered after `page_submit()` for existing records |
| `page_view()` | `gate-view-123.html` | `$this->page->evtp` returns "123" | Browser requests specific record |
| `page_delete()` | `gate-delete-123.html` | `$this->page->evtp` returns "123" | Browser requests deletion |
### **Custom Page Events**
You can create custom events by naming method `page_event_*` - these DO take `$evtp` directly as a parameter:
```php
// URL: gate-login.html → calls page_event_login("") (empty evtp)
public function page_event_login($evtp) { }
// URL: gate-search-laptop.html → calls page_event_search("laptop")
public function page_event_search($evtp) { }
// URL: gate-export-pdf.html → calls page_event_export("pdf")
public function page_event_export($evtp) { }
```
| Custom Event | URL Pattern | Parameter |
|--------------|-------------|-----------|
| `page_event_login()` | `gate-login.html` | `$evtp = ""` |
| `page_event_search($evtp)` | `gate-search-keyword.html` | `$evtp = "keyword"` |
| `page_event_export($evtp)` | `gate-export-format.html` | `$evtp = "format"` |
The `$evtp` parameter contains everything after the event name in the URL.
### **Generic Event Handler (Advanced)**
For complete control over events, you can override the `page_event($event, $evtp)` method which catches all unmatched events:
```php
// Catches any event that doesn't match built-in or custom page_event_*
public function page_event($event, $evtp)
{
// $event = "custom", $evtp = "value"
if ($event == "custom") {
// handle custom event
}
}
```
### **Getting Event Parameter in Your Gate**
There are multiple ways to access the event parameter:
```php
public function page_view()
{
// Method 1: Direct access to page property
$id = $this->page->evtp;
// Method 2: Using Gate helper method
$id = $this->getEventParameter();
// Method 3: Using Page helper method
$id = $this->page->getEventParameter();
}
```
## **1.6 URL Translation in Action**
Let's see how URLs translate to events:
```
URL: index.html
↓
Gate: index (maps to Index.gate.php)
Event: new (maps to page_new())
↓
Executes: Index::page_new()
URL: blog-view-5.html
↓
Gate: blog (maps to Blog.gate.php)
Event: view (maps to page_view())
Parameter: 5 (available via $this->page->evtp)
↓
Executes: Blog::page_view() → $this->page->evtp returns "5"
URL: shop-search-laptop.html
↓
Gate: shop (maps to Shop.gate.php)
Event: search (maps to page_event_search())
Parameter: laptop (passed as $evtp)
↓
Executes: Shop::page_event_search("laptop")
```
**Important:** Built-in page events (`page_new`, `page_view`, `page_delete`, etc.) do NOT receive parameters directly in the method signature. Custom events (`page_event_*`) DO receive `$evtp` as a parameter.
## **1.7 The Request Flow Diagram**
Here's the complete flow when a browser makes a request:
```
┌─────────────────────────────────────────────────────────┐
│ Browser Request │
│ (index.html) │
└───────────────────────────┬───────────────────────────────┘
↓
┌───────────────────────────▼───────────────────────────────┐
│ URL Translation Layer │
│ (gate = "index", event = "new") │
└───────────────────────────┬───────────────────────────────┘
↓
┌───────────────────────────▼───────────────────────────────┐
│ Gate Loader │
│ (Loads Index.gate.php from reg.php) │
└───────────────────────────┬───────────────────────────────┘
↓
┌───────────────────────────▼───────────────────────────────┐
│ Gate Instantiation │
│ (Creates new Index object) │
└───────────────────────────┬───────────────────────────────┘
↓
┌───────────────────────────▼───────────────────────────────┐
│ Gate Lifecycle Events │
│ onstart() → onready() → onrun() │
└───────────────────────────┬───────────────────────────────┘
↓
┌───────────────────────────▼───────────────────────────────┐
│ Page Event Execution │
│ (page_new()) │
└───────────────────────────┬───────────────────────────────┘
↓
┌───────────────────────────▼───────────────────────────────┐
│ FrontFile Processing │
│ (If setFrontFile is called) │
└───────────────────────────┬───────────────────────────────┘
↓
┌───────────────────────────▼───────────────────────────────┐
│ MasterFile Merge │
│ (Layout template applied) │
└───────────────────────────┬───────────────────────────────┘
↓
┌───────────────────────────▼───────────────────────────────┐
│ HTML Response │
└───────────────────────────────────────────────────────────┘
```
## **1.8 Key Concepts Summary**
1. **Gate** - Your application's Gate class that extends BasicGate
2. **Page Event** - Methods in Gate that handle browser requests
3. **URL Pattern** - `<gate>-<event>-<parameter>.html`
4. **No Routing** - URL directly maps to Gate + Event method
## **1.9 What's Next?**
Now you understand the core architecture. In the next chapter, you'll learn:
- How to register your Gate in `reg.php`
- How to create your first Gate class
- How the URL maps to your Gate's events
---
*Next: Chapter 2 - Registering Your First Gate*