JOBcard & Client Management System

Portable PHP/MariaDB implementation of the JOBcard & Client Management System. The application does not require Docker and is designed to run on shared hosting, Virtualmin, cPanel, or a conventional PHP-FPM/Apache/Nginx server.

Requirements

PHP 8.2+ (PHP 8.4 is recommended)
MariaDB 10.6+ or MySQL 8+
PHP extensions: pdo_mysql, mbstring, openssl, json, fileinfo
Apache with mod_rewrite, or Nginx with an equivalent front-controller rule
CLI PHP access for the initial database installation

Installation on a standard host

Create a MariaDB/MySQL database and database user.
Upload the repository outside the public web root.
Set the virtual host/document root to the public/ directory.
Copy .env.example to .env and replace every placeholder with production values.
Restrict .env permissions, for example chmod 600 .env.
Install the schema and initial Administrator account:

php bin/install.php

The installer must be run once against a new database. It creates the schema and bootstraps the Administrator using ADMIN_EMAIL and ADMIN_PASSWORD; the password is hashed with PHP's password API.

Visit the domain over HTTPS and sign in.

Virtualmin setup

Create a Virtualmin virtual server and MariaDB database/user.
Set the virtual server PHP version to PHP 8.2+ and use PHP-FPM.
Set the document root to jobcard-system/public.
Enable Apache mod_rewrite and permit AllowOverride FileInfo (or configure equivalent virtual-host rewrite rules); the included public/.htaccess routes requests to public/index.php.
Enable HTTPS with Virtualmin/Let's Encrypt.
Run php bin/install.php from the application directory using the same PHP version configured for the domain.
The public/ directory is mandatory as the virtual server document root. Never configure the repository root as the document root; public/.htaccess cannot protect files located in parent directories.
Schedule database and upload backups using the hosting provider's backup system or cron.

Nginx alternative

Use public/ as the root and route all non-file requests to public/index.php. PHP requests should be passed to the selected PHP-FPM socket. Do not expose the repository root as the web root.

Verification

php -v
php -m | grep -E 'pdo_mysql|mbstring|openssl|json|fileinfo'
php bin/install.php
for f in tests/*Test.php tests/smoke.php; do php -d assert.exception=1 "$f"; done
for f in $(find app config public bin -type f -name '*.php'); do php -l "$f"; done

Current increment

The repository currently includes the secure foundation, role/permission schema, client and contact domain validation, client detail/search views, jobcard creation/listing, time/SLA calculations, and safe report data contracts. Remaining scope modules are being implemented incrementally, including complete credential management, technician workflows, exports, attachments, notifications and production UAT.

Security notes

Never commit .env or production credentials.
Use a long random APP_KEY stored outside source control.
Use HTTPS in production.
The initial bootstrap schema is intended for a new database and should be replaced by versioned migrations in later releases.

3.2 KiB Raw Blame History