System Setup FAQ

Quick Start

For New Apps

```bash

1. Create app directory

mkdir -p /Users/rbutare/websites/apps/myapp

2. Create app manifest (scans directory for files)

php /Users/rbutare/websites/system/php/create.manifest.php -n myapp --scan

3. Create .env file

cat > /Users/rbutare/websites/apps/myapp/.env << 'EOF'
APP_NAME=myapp
BASE_URL=/myapp
AUTH_REQUIRE_LOGIN=1
CACHE=OFF
DEFAULT_APP_VERSION=v1.0.0
EOF

4. Test database connection (if applicable)

php /Users/rbutare/websites/system/php/testdb.php myapp

5. Verify manifest matches disk

php /Users/rbutare/websites/system/php/diff.manifest.php -n myapp
```

For System Setup

```bash

1. Ensure system paths.php exists

ls -la /Users/rbutare/websites/system/php/paths.php

2. Create system .env

cat > /Users/rbutare/websites/system/.env << 'EOF'

System-wide defaults

APP_NAME=system
AUTH_REQUIRE_LOGIN=1
CACHE=OFF
DEFAULT_APP_VERSION=v1.8.0

Database (shared by all apps)

DB_HOST=localhost
DB_NAME=mydb
DB_USER=myuser
DB_PASS=mypassword
DB_CHARSET=utf8mb4

Paths (used by all scripts)

BASE_URL=/
PROJECT_ROOT=/Users/rbutare/websites/apps
EOF

3. Create system manifest

php /Users/rbutare/websites/system/php/create.manifest.php -n system --scan

4. Regenerate project registry

php /Users/rbutare/websites/system/php/create.manifest.php -g
```

---

Table of Contents

1. [Architecture Overview](#architecture-overview)
2. [Directory Structure](#directory-structure)
3. [Configuration Files](#configuration-files)
4. [Bootstrap System](#bootstrap-system)
5. [Creating New Apps](#creating-new-apps)
6. [System Utilities](#system-utilities)
7. [Manifest System](#manifest-system)
8. [Troubleshooting](#troubleshooting)

---

Architecture Overview

Two-Tier Configuration

- System-level (`/system/.env`): Shared defaults for all apps
- App-level (`/apps/{name}/.env`): App-specific overrides

Merge order: App values override system values.

Single Source of Truth

All paths and configuration flow from `paths.php`:

```
paths.php (loads .env files)
↓
APP_ROOT, SYSTEM_ROOT, APP_URL, etc.
↓
All other scripts include paths.php
```

Rule #1: Never hardcode paths. Always use constants from `paths.php`.

---

Directory Structure

```
/Users/rbutare/websites/
├── system/
│ ├── .env # System-wide defaults
│ ├── php/
│ │ ├── paths.php # Bootstrap loader (authoritative)
│ │ ├── auth.php # Authentication guard
│ │ ├── testdb.php # Database test utility
│ │ ├── create.manifest.php # Manifest generator
│ │ └── diff.manifest.php # Manifest diff tool
│ └── system.manifest # System manifest
│
└── apps/
├── myapp/
│ ├── .env # App-specific config
│ ├── myapp.manifest # App manifest
│ ├── index.php # App entry point
│ └── ...
│
└── voice/
├── .env
├── voice.manifest
└── voice.index.php
```

---

Configuration Files

`/system/.env` (System Defaults)

```dotenv

Authentication

AUTH_REQUIRE_LOGIN=1

Cache

CACHE=OFF

Database (shared)

DB_HOST=localhost
DB_NAME=mydb
DB_USER=myuser
DB_PASS=secret
DB_CHARSET=utf8mb4

URLs

BASE_URL=/
SYSTEM_URL=/system

Paths

PROJECT_ROOT=/Users/rbutare/websites/apps
APPS_BASE=/Users/rbutare/websites/apps
```

`/apps/{name}/.env` (App Overrides)

```dotenv

App identity

APP_NAME=voice
DEFAULT_APP_VERSION=v1.0.0

URLs (override system defaults)

BASE_URL=/voice
APP_URL=/voice

Auth (override system default)

AUTH_REQUIRE_LOGIN=0

Cache

CACHE=OFF

Optional diagnostics

PATHS_WRITE_JSON=false
```

---

Bootstrap System

How `paths.php` Works

1. Defines system paths (`SYSTEM_ROOT`, `APPS_BASE`)
2. Loads `.env` files (system first, then app)
3. Merges settings (app overrides system)
4. Defines constants (`APP_ROOT`, `APP_URL`, `DB_HOST`, etc.)
5. Sets `$GLOBALS['APP_ENV']` (array access to all settings)
6. Defines `BOOTSTRAP_LOADED` (security marker)

App Entry Point Pattern

```php
<?php
declare(strict_types=1);

// 1. Define app name BEFORE including paths.php
define('APP_NAME', 'voice');

// 2. Load bootstrap (silent, no output)
require_once __DIR__ . '/../../system/php/paths.php';

// 3. Load auth guard (checks BOOTSTRAP_LOADED)
require_once SYSTEM_ROOT . '/php/auth.php';

// 4. Your app logic continues...
echo "App root: " . APP_ROOT . "\n";
echo "Cache: " . (APP_CACHE_ENABLED ? 'ON' : 'OFF') . "\n";
```

Key Constants Available After Bootstrap

| Constant | Description |
|----------|-------------|
| `APP_NAME` | App directory name (e.g., `voice`) |
| `APP_ROOT` | Full filesystem path to app |
| `SYSTEM_ROOT` | Full filesystem path to system |
| `BASE_URL` | Base URL for the app |
| `APP_URL` | Full URL to the app |
| `APP_CACHE_ENABLED` | Boolean from `CACHE` setting |
| `APP_VERSION` | From `DEFAULT_APP_VERSION` |
| `DB_HOST`, `DB_NAME`, `DB_USER`, `DB_PASS` | Database credentials |
| `BOOTSTRAP_LOADED` | Security marker (always `true`) |

---

Creating New Apps

Step 1: Create Directory

```bash
mkdir -p /Users/rbutare/websites/apps/myapp
```

Step 2: Create `.env`

```bash
cat > /Users/rbutare/websites/apps/myapp/.env << 'EOF'
APP_NAME=myapp
BASE_URL=/myapp
AUTH_REQUIRE_LOGIN=1
CACHE=OFF
DEFAULT_APP_VERSION=v1.0.0
EOF
```

Step 3: Create Manifest

```bash

Scan directory and create manifest

php /Users/rbutare/websites/system/php/create.manifest.php -n myapp --scan
```

Step 4: Create Entry Point

```php
<?php
declare(strict_types=1);

define('APP_NAME', 'myapp');
require_once __DIR__ . '/../../system/php/paths.php';
require_once SYSTEM_ROOT . '/php/auth.php';
?>
<!DOCTYPE html>
<html>
<head><title>My App</title></head>
<body>
<h1>My App is running</h1>
<p>Version: <?= APP_VERSION ?></p>
</body>
</html>
```

Step 5: Test

```bash

Test database connection

php /Users/rbutare/websites/system/php/testdb.php myapp

Verify manifest

php /Users/rbutare/websites/system/php/diff.manifest.php -n myapp

Access in browser

open http://localhost:8000/apps/myapp/index.php
```

---

System Utilities

`testdb.php` — Database Connection Test

```bash

Test specific app's database config

php testdb.php voice

Test from web

/system/php/testdb.php?app=voice
```

`create.manifest.php` — Manifest Generator

```bash

Create new manifest

php create.manifest.php -n voice

Scan and populate files array

php create.manifest.php -n voice --scan

Force overwrite existing

php create.manifest.php -n voice --force

Regenerate project registry

php create.manifest.php -g
```

`diff.manifest.php` — Manifest Diff Tool

```bash

Compare manifest vs disk

php diff.manifest.php -n voice

Show only missing files

php diff.manifest.php -n voice --missing

Show only additional files

php diff.manifest.php -n voice --additional
```

---

Manifest System

What Is a Manifest?

A `.manifest` file is a JSON metadata file for each app:

```json
{
"appname": "voice",
"role": null,
"skeleton_version": "v2",
"path": "/Users/rbutare/websites/apps/voice",
"env_file": ".env",
"extensions": ["api", "assets"],
"notes": null,
"date_created": "2026-09-09",
"date_updated": "2026-09-09",
"files": [
"index.php",
"app.main.php",
"config/settings.cfg"
]
}
```

Purpose

- Authoritative file list for each app
- Version tracking (`skeleton_version`)
- Extension declaration (capabilities)
- Registry generation (project-wide index)

Project Registry

Auto-generated from all manifests:

```bash
php create.manifest.php -g
```

Output: `project.registry.json`

```json
{
"_generated_note": "AUTO-GENERATED...",
"_generated_at": "2026-09-09T12:34:56Z",
"system": { ... },
"apps": [
{ "appname": "voice", ... },
{ "appname": "myapp", ... }
]
}
```

---

Troubleshooting

"Cannot find paths.php"

Error: `Error: Cannot find paths.php at /path/to/paths.php`

Fix: Ensure `paths.php` exists in `system/php/`:

```bash
ls -la /Users/rbutare/websites/system/php/paths.php
```

"Undefined constant DB_HOST"

Error: `Fatal error: Uncaught Error: Undefined constant "DB_HOST"`

Fix: Add DB constants to `paths.php` or access via `$GLOBALS['APP_ENV']`:

```php
// Option 1: Use constant (if defined in paths.php)
echo DB_HOST;

// Option 2: Use global array
echo $GLOBALS['APP_ENV']['DB_HOST'];
```

"BOOTSTRAP_LOADED not defined"

Error: `auth.php was loaded before paths.php completed`

Fix: Always include `paths.php` before `auth.php`:

```php
require_once __DIR__ . '/../../system/php/paths.php';
require_once SYSTEM_ROOT . '/php/auth.php';
```

"App path does not exist"

Error: `Error: /Users/rbutare/websites/apps/myapp does not exist`

Fix: Create the directory first:

```bash
mkdir -p /Users/rbutare/websites/apps/myapp
```

"Manifest already exists"

Error: `voice.manifest already exists. Use -f/--force to overwrite`

Fix: Use `--scan` to update files, or `--force` to overwrite:

```bash

Update files array

php create.manifest.php -n voice --scan

Force overwrite

php create.manifest.php -n voice --force
```

"Invalid APP_NAME"

Error: `Invalid APP_NAME: ../system`

Fix: App names must be alphanumeric (security):

```bash

Valid

php create.manifest.php -n voice
php create.manifest.php -n myapp123

Invalid

php create.manifest.php -n ../system # Directory traversal
php create.manifest.php -n my-app # Hyphens not allowed in some contexts
```

---

Quick Reference

Common Commands

```bash

Create app

php create.manifest.php -n myapp --scan

Update manifest

php create.manifest.php -n myapp --scan

Check manifest vs disk

php diff.manifest.php -n myapp

Test database

php testdb.php myapp

Regenerate registry

php create.manifest.php -g
```

File Locations

| File | Purpose |
|------|---------|
| `/system/php/paths.php` | Bootstrap loader |
| `/system/php/auth.php` | Auth guard |
| `/system/php/testdb.php` | DB test utility |
| `/system/php/create.manifest.php` | Manifest generator |
| `/system/php/diff.manifest.php` | Manifest diff |
| `/apps/{name}/.env` | App config |
| `/apps/{name}/{name}.manifest` | App manifest |
| `/project.registry.json` | Project index |

Environment Variables

| Variable | Scope | Default | Description |
|----------|-------|---------|-------------|
| `APP_NAME` | App | `myapp` | App directory name |
| `BASE_URL` | Both | `/` | Base URL path |
| `AUTH_REQUIRE_LOGIN` | Both | `1` | Require authentication |
| `CACHE` | Both | `OFF` | Enable caching |
| `DB_HOST` | System | `localhost` | Database host |
| `DB_NAME` | System | — | Database name |
| `DB_USER` | System | — | Database user |
| `DB_PASS` | System | — | Database password |
| `PATHS_WRITE_JSON` | App | `false` | Write diagnostics |

---

Support

For issues or questions:

1. Check this FAQ first
2. Review `paths.php` source code
3. Run diagnostic tools:
```bash
php testdb.php {appname}
php diff.manifest.php {appname}
```
4. Check PHP error log:
```bash
tail -f /usr/local/var/log/php_error.log
```