# **Chapter 10: SartajPHP Permission System Architecture**
## SartajPHP Permission System Architecture
Security in SartajPHP is not an afterthought, a plugin, or a middleware layer.
It is a **first-class application concern**, designed to work naturally with the App, Event, and FrontFile lifecycle.
This chapter explains **how the SartajPHP Permission System actually works**, why it is designed this way, and how developers must use it correctly.
---
## 10.1 Authentication vs Authorization (Critical Distinction)
SartajPHP clearly separates **authentication** from **authorization**.
| Layer | Purpose | Question Answered |
| -------------------------- | ---------- | ------------------------------- |
| Authentication | Identity | Who is the user? |
| Authorization (Permission) | Capability | What is the user allowed to do? |
This separation allows:
* Simple apps without permissions
* Advanced enterprise apps with dynamic permissions
* Runtime permission updates without code changes
---
## 10.2 Authentication Layer (Recap)
Authentication is handled primarily by the **Signin App** and project configuration (`comp.php`).
Authentication determines:
* Is the user logged in?
* What role does the user belong to?
Typical roles:
* `GUEST`
* `MEMBER`
* `ADMIN`
Apps can restrict access using:
```php
$this->getAuthenticate("GUEST,MEMBER,ADMIN");
```
This check:
* Controls **who may access the App**
* Does **not** control what actions are allowed inside the App
That responsibility belongs to the Permission system.
---
## 10.3 Permission System Philosophy
The SartajPHP Permission System is:
* **App-centric**
* **Event-aware**
* **Database-driven**
* **Explicit, not implicit**
Permissions are **never inferred automatically**.
If a developer does not check a permission, **no permission is enforced**.
This design:
* Avoids hidden behavior
* Prevents unexpected access denial
* Keeps Apps predictable and debuggable
---
## 10.4 Permission Identifier Format
Permissions in SartajPHP follow a strict naming rule:
```
<AppName>-<PermissionName>
```
Example:
```
mebProfile-view
mebProfile-add
mebProfile-delete
```
Important rules:
* Developers only use the **short permission name** (`view`, `add`, `delete`)
* The framework automatically prefixes the Gate name
* Permission names are **case-sensitive**
---
## 10.5 Registering Permissions for an App
Permissions are declared **at Gate registration time**, usually inside `reg.php`.
Example:
```php
uuregisterGate(
"mebProfile",
".../uumebProfileGate.php",
"",
"Member Profile",
[
["view", "View Profile"],
["add", "Add Record"],
["update", "Update Record"],
["delete", "Delete Record"]
]
);
```
### What This Does
* Registers the App
* Declares available permissions
* Makes permissions visible to:
* Permission Profile App
* Menu system
* UI permission assignment
No database records are created at this stage.
This is **permission definition**, not permission assignment.
---
## 10.6 Where Permissions Are Stored
Permissions are stored **per profile**, not per user.
Typical flow:
* User → assigned to a profile
* Profile → assigned permissions
* User inherits permissions from profile
This design:
* Simplifies permission management
* Prevents permission duplication
* Allows bulk permission changes
---
## 10.7 Permission Enforcement Inside an App
Permissions are enforced **explicitly** inside Gate logic.
### Event-Level Enforcement
```php
$this->page->getAuthenticatePerm("view");
```
If permission is missing:
* Execution stops
* Gate falls back to safe behavior
* Unauthorized action is blocked
---
### Conditional Permission Checks
```php
if ($this->page->hasPermission("add")) {
// allow action
}
```
This is commonly used for:
* Showing or hiding buttons
* Enabling or disabling features
* Conditional logic in FrontFiles
---
## 10.8 Role of `PermisApp` (Parent App)
`PermisApp` is a **permission-aware base App**.
When an Gate extends `PermisApp`, it automatically gains:
* Permission checking helpers
* Consistent permission lifecycle
* Standardized enforcement behavior
Typical usage:
```php
class mebProfile extends PermisGate {
...
}
```
### Why `PermisApp` Exists
* Prevents duplicated permission logic
* Centralizes security behavior
* Ensures consistency across Apps
* Integrates seamlessly with Menu system
Using `PermisApp` is **strongly recommended** for all secure Apps.
---
## 10.9 Permission Enforcement vs Menu Visibility
A critical rule in SartajPHP:
> **Menu visibility does NOT equal permission enforcement**
Even if:
* A menu item is hidden
* A link is not visible
The Gate **must still check permissions**.
Menus are a **UI convenience**, not a security boundary.
---
## 10.10 Menu System and Permissions
Menus in SartajPHP are **permission-aware**.
Example:
```php
$this->sphp_api->addMenuLink("Users",getGateURL('mebProfile'),"fa fa-users","User",false,"mebProfile-view");
```
This means:
* Menu link appears only if:
* User role matches
* User has the `mebProfile-view` permission
Menu filtering is done:
* At render time
* Based on logged-in user permissions
This prevents:
* Confusing UI
* Broken navigation
* Unauthorized access attempts
---
## 10.11 Why Menu Permissions Depend on Gate Permissions
Menus do **not define permissions**.
They only **reference existing Gate permissions**.
This ensures:
* Single source of truth
* No permission duplication
* App-driven security model
If an Gate does not register permissions, the menu cannot reference them.
---
## 10.12 Permission Checks in Front Files
FrontFiles can conditionally render elements using server-bound logic.
Typical pattern:
* Permission check in App
* Flag passed to FrontFile
* Conditional rendering using `runat="server"`
FrontFiles themselves contain:
* No direct permission logic
* No SQL
* No authentication code
They are **presentation-only**, by design.
---
## 10.13 Admin Privileges
The `ADMIN` role:
* Automatically bypasses permission checks
* Has access to all Apps and events
* Is intended for system administrators only
This behavior:
* Is enforced centrally
* Should never be overridden casually
---
## 10.14 Common Permission Mistakes (Avoid These)
* Assuming menu hiding is security
* Forgetting to enforce permission in Gate logic
* Using permissions without registering them
* Hardcoding permission strings incorrectly
* Skipping `PermisApp` for secure Apps
---
## 10.15 Summary
The SartajPHP Permission System is:
* Explicit
* Predictable
* App-centric
* Database-driven
* UI-aware but not UI-dependent
Correct usage requires:
* Proper permission registration
* Explicit permission checks
* Consistent use of `PermisApp`
* Clear separation of Gate logic and FrontFiles
---
## 10.16 What Comes Next
In **Chapter 11**, we will cover:
* Required database tables
* Mandatory fields (`id`, `parentid`, `permission_id`)
* SQL schema rules
* Why `id` is critical for components
* How permissions are stored and resolved internally