B
Official Documentation · v2.0.0

BillCraft Pro 2026 — Enterprise SaaS Suite

Installation, Configuration (config/config.local.php & Env), Admin Setup, Authentication & Usage Manual

🚀 1-Click Installer 🔐 Sign In Open Workspace (index.php) →

1. Server Requirements & Package Directory Structure

Technical Requirements (Verified by Installer)

  • PHP Version: PHP 8.0 or newer (8.0, 8.1, 8.2, 8.3, 8.4)
  • PHP Extensions: pdo, pdo_mysql, json, mbstring
  • Session Support: PHP native sessions enabled (session_start)
  • Database Engine: MySQL 5.7+ / 8.0+ or MariaDB 10.3+ (utf8mb4_unicode_ci)
  • Web Server: Apache, Nginx, LiteSpeed, cPanel, Plesk, XAMPP, WAMP, MAMP, Laragon, or Docker
  • Folder Permissions: Writable /config directory (chmod 755 or 775) so the installer can write config/config.local.php and config/installed.lock

Package File Structure

billcraft-pro/
├── api/v1/
│   ├── auth.php               # Session API (?action=me, ?action=logout)
│   └── documents.php          # Auth + CSRF REST API (GET/POST/PATCH/DELETE)
├── config/
│   ├── .htaccess              # Denies direct HTTP access
│   ├── Database.php           # PDO Singleton MySQL Connector
│   ├── config.local.php       # (Generated) Local DB credentials array
│   └── installed.lock         # (Generated) Locks installer after setup
├── includes/
│   ├── .htaccess              # Denies direct HTTP access
│   ├── Auth.php               # Bcrypt Auth, RBAC & Brute-Force Guard
│   └── bootstrap.php          # Session (BCSESSID), CSRF & API Guard
├── install/
│   └── index.php              # 1-Click Installer + Admin Account Wizard
├── sql/
│   ├── .htaccess              # Denies direct HTTP access
│   └── billcraft_schema.sql   # 7 InnoDB MySQL Tables & Seed Data
├── views/
│   ├── .htaccess              # Denies direct HTTP access
│   └── dashboard.php          # Protected 5-Module Workspace View
├── index.php                  # Main Entry (routes to install/login/app)
├── login.php                  # Sign-In Page (Bcrypt + CSRF + Throttling)
├── DOCUMENTATION.html         # This Interactive Browser Manual
└── README.md                  # Complete Markdown Manual

2. Installation, Configuration & Admin Account Setup

Method A: 1-Click Visual Auto-Installer Wizard (Recommended — 60 Seconds)

  1. Extract & Upload: Extract the ZIP archive and upload all files to your web server root (e.g., public_html/, htdocs/billcraft-pro/, or /var/www/html/).
  2. Prepare a MySQL Database: On shared hosting (cPanel/Plesk), create an empty MySQL database and user with ALL PRIVILEGES via MySQL® Database Wizard. On local environments (XAMPP/WAMP/MAMP/Laragon), the installer creates the database automatically.
  3. Open the Application: Navigate to http://your-domain.com/index.php (which automatically redirects to install/ before setup) or open http://your-domain.com/install/index.php directly.
  4. Verify Requirements Checklist: Confirm all 6 items under Server Requirements show ✓ OK.
  5. Complete Section 1 · MySQL Database:
    • MySQL Database Host: localhost (or 127.0.0.1)
    • Database Name: billcraft_pro (letters, numbers, and underscores only)
    • Database Username: Your MySQL username (e.g., root)
    • Database Password: Your MySQL password
  6. Complete Section 2 · Administrator Account:
    • Full Name: Your administrator display name (e.g., Alex Mercer)
    • Admin Email (used to sign in): Valid email address (e.g., admin@yourdomain.com)
    • Password (min. 8): Strong password (at least 8 characters)
    • Confirm Password: Repeat the administrator password
  7. Run Installation: Click "🚀 Run 1-Click Installation". The wizard automatically:
    • Creates the database if needed and imports /sql/billcraft_schema.sql (creating all 7 InnoDB tables: bc_users, bc_login_attempts, bc_settings, bc_clients, bc_catalog, bc_documents, bc_document_items + seed records).
    • Hashes your administrator password on your server using password_hash($adminPass, PASSWORD_DEFAULT) (Bcrypt) and inserts your admin account into bc_users.
    • Generates /config/config.local.php (chmod 0640) with your database credentials.
    • Creates /config/installed.lock to lock the installer against unauthorized re-runs.
  8. Sign In: Click "Sign In to BillCraft Pro →" to open login.php and sign in with the administrator email and password you created. (Recommended for production servers: delete the /install directory after setup).

Method B: Manual Installation (config/config.local.php or Environment Variables)

If you prefer manual setup without running /install/index.php, follow these 4 steps. Note: You never need to edit /config/Database.php directly.

Step 1: Import the SQL Schema

In phpMyAdmin (or MySQL CLI), create a database named billcraft_pro (collation utf8mb4_unicode_ci) and import /sql/billcraft_schema.sql.

Step 2: Configure Database Credentials (config/config.local.php or Environment Variables)

BillCraft\Config\Database::credentials() resolves database settings in this order: (1) Environment variables DB_HOST, DB_NAME, DB_USER, DB_PASS, (2) /config/config.local.php, and (3) built-in fallback defaults. Create /config/config.local.php with the following structure:

<?php
// config/config.local.php
return [
    'host' => 'localhost',
    'name' => 'billcraft_pro',
    'user' => 'your_mysql_username',
    'pass' => 'your_mysql_password',
];

Alternatively, set DB_HOST, DB_NAME, DB_USER, and DB_PASS as server environment variables (Apache SetEnv, Nginx fastcgi_param, or Docker environment).

Step 3: Create Your Administrator Account in bc_users

For security, no hardcoded default admin account is shipped in billcraft_schema.sql. Generate a Bcrypt hash with PHP CLI and insert your admin user:

# 1. Generate Bcrypt password hash in terminal:
php -r "echo password_hash('YourStrongPassword123!', PASSWORD_DEFAULT) . PHP_EOL;"

-- 2. Insert administrator row in MySQL / phpMyAdmin:
INSERT INTO `bc_users` (`full_name`, `email`, `password_hash`, `role`, `language`)
VALUES ('Administrator', 'admin@yourdomain.com', '$2y$10$REPLACE_WITH_YOUR_BCRYPT_HASH', 'admin', 'en');
Step 4: Create /config/installed.lock

Create the file /config/installed.lock (e.g., containing Installed manually - v2.0.0). Until config/installed.lock is present, index.php and login.php automatically redirect to /install/.

3. Authentication, Workspace Access & Security Architecture

Entry Routing (index.php)

index.php is the main entry point. It checks bc_is_installed() (config/installed.lock) and redirects to install/ if not installed, checks Auth::user() and redirects unauthenticated visitors to login.php, or loads the protected workspace (views/dashboard.php).

Sign-In & Brute-Force Guard (login.php)

Authenticates users against bc_users with password_verify() (Bcrypt) and CSRF protection. Failed attempts are logged in bc_login_attempts; after 5 failed attempts within 15 minutes from the same IP, login is throttled with HTTP 429.

Sessions, CSRF & RBAC

Uses hardened cookie sessions (BCSESSID, HttpOnly, SameSite=Lax). State-changing API calls require the X-CSRF-Token header. Roles supported: admin, manager, staff (deleting documents requires admin or manager).

4. Basic Usage & Verifying MySQL Synchronization

After signing in at login.php, you are directed to the authenticated workspace at index.php. BillCraft Pro synchronizes all documents with MySQL via api/v1/documents.php while maintaining a fast browser cache.

Step 1: Verify Connection

Sign in to index.php, click "Company & SQL API" in the left sidebar, and click "🔄 Test & Sync MySQL Database Now". The status box calls GET api/v1/documents.php and displays: ✅ MySQL Connected! Synced X records from bc_documents table.

Step 2: Create & Save Documents

In A4 Document Studio, choose Invoice, Price Quote, or Service Contract, add line items, sign the canvas, and click "💾 Save to CRM". A transactional POST (with X-CSRF-Token) saves the record in bc_documents and bc_document_items.

Step 3: Toggle Status, Export & Delete

In Client CRM & Ledger, click Pending ↻ / Paid ✓ to send a PATCH request, click Delete (admin/manager) to send a DELETE request, or export to A4 PDF, CSV (Excel), or JSON Backup.

5. Authenticated RESTful JSON API Reference

All endpoints require an authenticated session cookie (BCSESSID). Mutating requests (POST, PATCH, DELETE) also require the per-session X-CSRF-Token header.

Method Endpoint CSRF Header Action
GET /api/v1/auth.php?action=me No Returns current authenticated user profile (id, full_name, email, role, can_delete) and csrf_token.
POST /api/v1/auth.php?action=logout X-CSRF-Token Destroys the active PHP session and redirects to login.php?logged_out=1.
GET /api/v1/documents.php No Fetches up to 250 documents with line items and SQL aggregate KPIs (total_pipeline, total_paid, total_pending, total_count).
POST /api/v1/documents.php X-CSRF-Token Creates or updates an Invoice, Proposal, or Contract + line items inside a PDO SQL Transaction.
PATCH /api/v1/documents.php?id={id} X-CSRF-Token Toggles document payment status between Paid and Pending in MySQL.
DELETE /api/v1/documents.php?id={id} X-CSRF-Token Deletes the document (requires admin or manager role) and cascades to bc_document_items.