Framework Structure

A PHPShift project has a well-defined directory layout. Understanding this structure helps you navigate the generated codebase and know what each part is responsible for.

Top-Level Directory Layout

my-project/
├── .assets/              # Public static assets served by Apache
│   ├── script.js         # Global jQook/jQuery app logic
│   ├── style.css         # Global base styles
│   ├── logo.png          # Project logo
│   ├── default.png       # Default image placeholder
│   ├── default.mp4       # Default video placeholder
│   ├── default.mp3       # Default audio placeholder
│   ├── robots.txt        # Search engine crawl rules
│   ├── sitemap.xml       # Auto-updated sitemap
│   └── background.webp   # Background asset
├── .system/              # PHP framework engine (internal, not public)
│   ├── app.php           # Router entry point (all requests route here via .htaccess)
│   ├── composer.json     # Composer dependency manifest
│   └── vendor/           # Composer-installed PHP packages
├── Apis/                 # PHP REST API files
│   └── v1.example.php
├── Crons/                # PHP cron job scripts
│   └── updateItems.php
├── Pages/                # Full-stack page units
│   ├── public.welcome/
│   │   ├── readme.md     # Page documentation
│   │   ├── page.html     # HTML structure
│   │   ├── style.css     # Page styles
│   │   ├── script.js     # Page JavaScript
│   │   └── code.php      # PHP business logic class
│   └── private.dashboard/
│       └── ...
├── Space/                # Project-level data files
│   ├── seo.html          # SEO meta tags (Open Graph, Twitter Card, etc.)
│   ├── lng.en.json       # English translation keys (auto-generated)
│   ├── lng.ka.json       # Georgian translation keys
│   └── *.log             # Application log files
├── .access               # PHP Access class - defines page access groups
├── .env                  # Environment configuration (never public)
├── .htaccess             # Apache routing, security headers, rate limiting
├── .gitignore            # Git ignore rules
├── .md                   # AI-readable project briefing (hidden file)
├── README.md             # Project readme (AI-generated or manual)
├── LICENSE               # Project license file
└── cron                  # PHP cron runner entry point

The .system/ Directory

This is the internal PHP framework engine. It is not editable by AI generation - it is the stable base that powers routing, authentication, database ORM, API dispatch, cron execution and the App helper class.

Key PHP method families available to generated code:

• App::env($key) - Read environment variable
• App::done($message, $data) - Return successful JSON response
• App::failed($message) - Return error JSON response
• App::info($message, $data) - Return informational JSON response
• App::error($message) - Log internal developer error
• App::lng($key, $text, $vars) - Translate a string
• App::redirect($url) - Not used in generated code (handled by JS instead)

All custom PHP classes in pages and APIs extend this surface through static method calls.

The Page Unit Structure

Each page lives in a folder named {group}.{name} inside Pages/. For example, a public dashboard page lives at Pages/public.dashboard/.

The group determines access control. The .access PHP class defines static methods named after groups:

class Access {
    public static function private() {
        // Return true if current user passes the 'private' group check
    }
}

PHPShift generates group methods automatically if a new group is detected during page creation.

URL Routing

All HTTP requests are routed through .htaccess to .system/app.php. The router maps:

• /welcome → Pages/public.welcome/code.php (PageWelcome class)
• /dashboard → Pages/private.dashboard/code.php (PageDashboard class)
• /assets/* → .assets/* (static files)
• API calls via App.call(url, method, data, callback) in JS → Apis/ PHP files

PHP Layer

The PHP layer is the server-side runtime for every PHPShift project. It is driven by a framework engine inside .system/ that handles routing, access control, database ORM, API dispatch and cron execution. Generated code lives on top of this engine.

Page Classes

Every page has a corresponding PHP class in its code.php file. Classes follow a strict naming convention:

• Page name: edititem → Class name: PageEditItem
• Page name: dashboard → Class name: PageDashboard

The class is a plain PHP class with public methods. Each public method is directly callable from the front-end via JavaScript's App.call():

class PageDashboard
{
    public function getStats($post = [], $get = [], $files = [])
    {
        $stats = DB::query("SELECT COUNT(*) as total FROM tasks WHERE user = :uid", [
            ':uid' => App::env('CURRENT_USER_ID')
        ]);
        return App::done('Stats loaded', ['stats' => $stats]);
    }

    private function validateAccess($userId)
    {
        // Private helper - not callable from front-end
    }
}

Method arguments are always ($post = [], $get = [], $files = []) - populated automatically by the framework from the incoming HTTP request.

API Files

API files live in Apis/ and follow a similar pattern, but declare their category and allowed HTTP method at the top:

<?php category('public', 'GET');

class ApiGetItems
{
    public function init($json = [], $post = [], $get = [])
    {
        // API entry point - always named 'init'
        return App::done('Items retrieved', ['items' => []]);
    }
}

Available API categories: - public - No authentication required - callback - Webhook/callback endpoint - systemApi - Internal system access - userApi - Authenticated user access - userWebhook - Authenticated user webhook

Cron Job Files

Cron files in Crons/ are PHP scripts executed by the PHPShift cron thread once per minute (or per schedule defined inside the file):

<?php

// Run at midnight
if (date('H:i') !== '00:00') exit;

// Cleanup expired sessions
DB::delete('sessions', 'expires_at < NOW()');

PHPShift manages cron execution through a Python background thread that calls php cron -auto every minute. You can start and stop cron processing from inside the skill menu under More > StartCrons and More > StopCrons.

The App Helper Class

App is a global PHP static utility class provided by the framework engine. Generated code uses it for all framework interactions:

| Method | Purpose | |--------|---------| | App::env($key) | Read .env variable | | App::done($msg, $data) | Return {"message": ..., "response": ..., "error": false} | | App::failed($msg) | Return {"message": ..., "error": true} | | App::info($msg, $data) | Return informational response | | App::error($msg) | Log a developer error | | App::lng($key, $text, $vars) | Return translated string |

All API responses follow the same JSON envelope so the front-end App.call() handler always knows what to expect.

Composer Plugins

Generated PHP code can require Composer packages. When PHPShift's AI detects a needed package (e.g., phpmailer/phpmailer), it includes it in config.json under composer-plugins. PHPShift then prompts you to confirm before running:

composer require phpmailer/phpmailer

The vendor/ directory and composer.json are both patch-tracked, so plugin installation can be rolled back if needed.

Environment Variables

All sensitive configuration is stored in .env and read via App::env(). Generated code uses this pattern to avoid hardcoding credentials:

$apiKey = App::env('STRIPE_API_KEY');

When the AI detects an App::env() call referencing a variable that doesn't exist in .env yet, PHPShift adds it automatically with an empty value and opens the file in VS Code for you to fill in.

AI Engine

The AI engine in PHPShift is the aisi Python module - a purpose-built skill runner that assembles context-rich prompts and communicates with AI models to generate structured file output.

How Skills Work

Each skill is a folder containing two files:

• prompt.md - The AI prompt template with [[placeholder]] injection points
• skill.py - The Python skill runner class that controls execution flow

Some skills also have a readme.md describing the skill's purpose for developers.

Prompt Templates

Prompt files use double-bracket placeholders that are replaced with live project data before the prompt is sent to the AI:

[[MESSAGE]]          → The developer's natural language task description
[[databaseSchema]]   → Current MySQL schema (tables, columns, types)
[[databaseVersion]]  → MySQL server version string
[[files]]            → List of all Pages/, Apis/, Crons/ file paths
[[phpMethods]]       → All PHP public static methods tagged with (AI-USE)
[[jsMethods]]        → All JavaScript App object methods tagged with (AI-USE)
[[styling]]          → CSS from a developer-selected existing page
[[pages]]            → readme.md content from all existing pages
[[codeBase]]         → Full file contents of a target page
[[logContent]]       → Content of a selected log file
[[frameworkStructure]] → .system/ PHP framework directory listing
[[frameworkCodebase]]  → Core framework PHP file contents
[[frameworkSolvedIssues]] → Resolved issue notes from solved.md

These placeholders are populated by the Collectors class at runtime, ensuring the AI always has accurate, current information.

The Collectors Class

Collectors is a Python class in .system/collectors.py where each method corresponds to a named placeholder. The aisi module calls the appropriate collector method based on which placeholders appear in the skill's prompt.

For example, [[phpMethods]] triggers Collectors.phpMethods(), which:

1. Walks every .php file in .system/
2. Finds methods with /** (AI-USE) doc comments
3. Extracts method signatures and documentation
4. Returns a formatted PHP code block

This ensures the AI knows exactly which methods exist and how to use them - without you having to document anything extra.

AI Response Parsing

The AI responds with named file blocks in markdown format:

[readme.md]
```md
## Goal
Create a user registration page...
```

[page.html]
```html
<div class="register-form">
  ...
</div>
```

[code.php]
```php
class PageRegister {
  public function register($post = [], ...) {
    ...
  }
}
```

aisi parses these blocks, extracts each filename and content pair and writes them to disk. Binary or special files are handled accordingly.

Model Selection

PHPShift supports multiple AI providers through the AISI.models() selector. During phpshift new or More > ChangeAIModel, you pick a model from an interactive list. The model identifier and API key are stored in .env:

PHPSHIFT_AIMODEL="claude-3-5-sonnet-20241022"
PHPSHIFT_AIKEY="sk-ant-..."

For Google Vertex AI, the PHPSHIFT_AIKEY value is a relative path to a service account JSON file:

PHPSHIFT_AIMODEL="vertex/gemini-1.5-pro"
PHPSHIFT_AIKEY="credentials/service-account.json"

Skill Execution Flow

Developer selects skill + types task description
         ↓
AISI loads prompt.md for the selected skill
         ↓
AISI calls Collectors for each [[placeholder]] found
         ↓
Full prompt assembled with live project context
         ↓
Prompt sent to AI model (via configured API)
         ↓
AI returns structured file blocks
         ↓
AISI parses response, writes files to disk
         ↓
PHPShift shows result, prompts for confirmation

Skill Discovery

The main CLI menu is built dynamically by scanning the Create/, Edit/, Delete/, Read/, Render/, More/ and PHPShift/ directories for skill.py files. The menu structure mirrors the directory tree and options are filtered based on project state (e.g., "Edit API" is hidden if no APIs exist yet).

Database Layer

PHPShift manages MySQL databases through two layers: a Python-side DB module for CLI operations (schema inspection, patch rollback, session management) and a PHP-side ORM provided by the .system/ framework engine for runtime query execution.

Python DB Module

The DB class (modules/database.py) is used by PHPShift's CLI during the development session - not by the running PHP project. Its responsibilities include:

• Connection management - Connects via SQLAlchemy + PyMySQL using .env credentials
• Schema inspection - Provides DB.schema() used by the [[databaseSchema]] collector, giving the AI an accurate picture of all existing tables
• Patch rollback - DB.reserve() snapshots pending changes; DB.rollback() reverts them if the developer rejects AI output
• Database creation - DB.new(name) runs setup.sql to initialize the database and create framework system tables
• Direct operations - DB.insert(), DB.update(), DB.delete(), DB.query() are available for CLI-side data operations

DB Patch System

Every time a skill is about to generate code that may run SQL, PHPShift calls DB.reserve() to begin a tracked transaction. If the developer accepts the changes, DB.clear() finalizes them. If they reject, DB.rollback() reverts all database mutations made during that skill run.

PHP Database ORM

At runtime, the PHP framework's .system/ engine provides a database abstraction layer accessed through static methods. Generated page and API code uses these exclusively - never raw PDO or mysqli.

Common patterns in generated PHP:

// Fetch records
$items = DB::select('SELECT * FROM tasks WHERE user = :uid', [':uid' => $userId]);

// Insert a record
$id = DB::insert('tasks', ['title' => $title, 'user' => $userId, 'created' => date('Y-m-d H:i:s')]);

// Update a record
DB::update('tasks', ['title' => $newTitle], 'id = :id', [':id' => $taskId]);

// Delete a record
DB::delete('tasks', 'id = :id', [':id' => $taskId]);

These methods are among the [[phpMethods]] collected by Collectors.phpMethods() and made available to the AI when generating code, ensuring correct usage every time.

System Tables

When a new project database is initialized, PHPShift runs setup.sql which creates these framework-level tables:

| Table | Purpose | |-------|---------| | user_files | Tracks user-uploaded file references (path, mime, token) | | user_keys | Stores named key-value pairs per user (sessions, tokens, settings) | | api | Manages registered API access tokens with expiry |

These tables are used by the framework engine itself. Your application tables are created by the db.sql files generated alongside your pages.

SQL Generation Rules

When PHPShift's AI generates SQL, it follows strict rules enforced in every prompt:

• No CREATE DATABASE statement (PHPShift handles database creation separately)
• Timestamps always use DEFAULT NULL or DEFAULT CURRENT_TIMESTAMP - never a fixed value
• Example records are included at the end of every schema file to make testing easy
• The MySQL version is passed to the AI via [[databaseVersion]] to prevent syntax incompatibilities

Read Skills for Database

The Read > Database skill lets you query your database using natural language during a development session. You describe what data you want and the AI generates a statement.sql and params.json which PHPShift then executes and displays inline. This is useful for debugging, inspecting data, or verifying that generated inserts worked correctly.