# **Chapter 11: PermisGate Architecture & Database Design** This chapter explains **PermisApp**, its role in SartajPHP, and the **database structure required** to use it effectively. PermisGate is **not mandatory**. It is a **shared parent Application** provided by SartajPHP to **reduce repetitive work** when building authentication-, user-, and permission-based systems. --- ## 11.1 What PermisGate Really Is (And Is Not) PermisApp: - ✅ Is a **helper parent App** - ✅ Is aligned with **Signin / Signup / User Management Apps** - ✅ Provides **prebuilt CRUD behaviors** - ✅ Enforces **permission-aware operations** PermisGate is **NOT**: - ❌ The core of SartajPHP - ❌ Required to build permission-based Apps - ❌ A replacement for `BasicGate` - ❌ A restriction on developer freedom > **Important:** > The true root Application class in SartajPHP is always `BasicGate`. > `PermisApp` simply extends it with shared logic. --- ## 11.2 Why PermisGate Exists In real-world projects, developers repeatedly need: - Signin / logout logic - User record ownership - Parent-child user relationships - Profile & permission handling - Standard insert / update / delete flows - Permission validation before database actions Writing this **again and again** leads to: - Code duplication - Inconsistent permission checks - Security bugs PermisGate solves this by providing a **common, reusable foundation**. --- ## 11.3 When You Should Use PermisApp Use PermisGate when your project includes: - Login system - User hierarchy - Profiles & permissions - Admin / staff / user roles - Multi-user data ownership - Large or growing applications Do **not** use PermisGate when: - Your app is small - No authentication is needed - No permission logic is required SartajPHP leaves the decision **entirely to the developer**. --- ## 11.4 Core Database Philosophy Behind PermisApp PermisGate assumes that **every record belongs to a user context**. That context is defined using **mandatory structural fields**. These fields allow PermisGate to: - Track ownership - Enforce permissions - Support hierarchical users - Enable multi-company separation - Provide recovery and debugging --- ## 11.5 Mandatory Fields for PermisApp-Compatible Tables Any database table used with PermisGate **must include** the following fields. ### 11.5.1 `id` — Record Identity (Required) ```sql id INT PRIMARY KEY AUTO_INCREMENT ```` * Unique identifier of the record * Used by: * Page events * Components * Pagination * Edit / delete operations * Must be numeric * Must be unique This field is **non-negotiable**. --- ### 11.5.2 `userid` — Owner User Record ID ```sql userid INT NOT NULL ``` * Stores the **RecID of the logged-in user** * Retrieved from Signin App * Used to: * Restrict record access * Filter list results * Enforce ownership rules PermisGate automatically fills this field during insert. --- ### 11.5.3 `parentid` — Parent User Record ID ```sql parentid INT DEFAULT 0 ``` * Stores the **RecID of the parent user** * Used for: * Admin → staff → user hierarchies * Delegated permissions * Group-based visibility This enables **multi-level user control** without complex joins. --- ### 11.5.4 `spcmpid` — Company / Project Identifier ```sql spcmpid VARCHAR(50) ``` * Text-based company or project identifier * No spaces allowed * Defined in `comp.php` * Optional for small projects * Essential for large or multi-tenant systems Use case: * Multiple companies share one website * Data must remain logically separated * Same user structure, different company data PermisGate filters records by `spcmpid` automatically when enabled. --- ### 11.5.5 `submit_timestamp` — Record Creation Time ```sql submit_timestamp DATETIME ``` * Automatically set during insert * Used for: * Debugging * Logging * Auditing * Recycle Gate integration --- ### 11.5.6 `update_timestamp` — Record Update Time ```sql update_timestamp DATETIME ``` * Updated on each modification * Helps track: * Who changed what * When data was modified * Failed update attempts --- ## 11.6 Canonical PermisApp-Compatible Table Example ```sql CREATE TABLE meb_profile ( id INT PRIMARY KEY AUTO_INCREMENT, userid INT NOT NULL, parentid INT DEFAULT 0, spcmpid VARCHAR(50), profile_name VARCHAR(100), status TINYINT DEFAULT 1, submit_timestamp DATETIME, update_timestamp DATETIME ); ``` This structure allows: * Secure CRUD * Permission enforcement * Multi-company isolation * Recovery support --- ## 11.7 Built-in CRUD Support Provided by PermisApp PermisGate already implements: * View logic * Insert logic * Update logic * Delete logic * Permission checks before execution As a result: * You **do not rewrite** CRUD code * You **do not duplicate permission checks** * You **only focus on business logic** --- ## 11.8 Overriding PermisGate Behavior (Advanced) PermisGate is **fully overridable**. If you need custom behavior: ```php class mebProfile extends PermisGate { protected function beforeInsert(&$data) { // custom validation } protected function afterUpdate($id) { // logging or notifications } } ``` This follows pure OOP principles: * Extend * Override * Customize only what you need --- ## 11.9 Recycle Gate & Failure Recovery The timestamp fields enable integration with a **Recycle App**: * Deleted records can be stored instead of destroyed * Failed SQL inserts can be logged * Accidental deletions can be restored This is especially useful in: * Financial systems * HR systems * Enterprise projects --- ## 11.10 Important Clarification (Very Important) > PermisGate is **optional**. If you: * Understand SartajPHP API * Know how to implement permissions manually * Want a custom architecture You can: * Extend `BasicGate` * Build your own permission-aware system SartajPHP **never restricts you**. PermisGate exists to **save time**, not to enforce rules. --- ## 11.11 Summary * `BasicGate` is the true root App * `PermisApp` is a productivity layer * Database compatibility is required *only if you use PermisApp* * Required fields enable ownership, hierarchy, and safety * Developers retain full freedom and control --- ## 11.12 What Comes Next In **Chapter 12**, we will cover: * How Signin Gate feeds PermisApp * Login lifecycle * Session identity * How permissions are resolved at runtime * Secure PageEvent execution ---