Documentation
Introduction
Welcome to the App documentation. This guide covers everything you need to get up and running.
Installation
Follow these steps to get the project set up on your local development environment. You'll need PHP 8.0+, MySQL 5.7+, Apache (with mod_rewrite enabled), and Composer.
Create the Project via Composer
Open your terminal, navigate to your local web server root directory (e.g., htdocs for XAMPP or www for Laragon), and create the project using Composer:
# Create the project using the mardev/starter-kit package (replace myphpapp with your desired directory name)
composer create-project mardev/starter-kit myphpapp
This command automatically creates the myphpapp folder, downloads all dependency packages, copies the configuration file, generates the encryption key, and builds the starter schema.
Configure Local URL and Environment
Copy .env.example to .env. Set your local site URL path under BASE_URL, and configure your MySQL database credentials.
# Copy environment example file
cp .env.example .env
# Edit your .env with the matching local server folder name
APP_NAME="Starter Kit"
BASE_URL="/myphpapp"
# Configure database credentials
DB_HOST=localhost
DB_NAME=starter
DB_USER=root
DB_PASS=
Setup Database & Keys
Create an empty database named starter (or the name you specified in .env). Then, generate a secure app key and seed the database using the CLI tool.
# Generate a secure application encryption key
php kit key:generate
# Seed the database with starter schema and default users
php kit db:seed
Alternatively, you can manually import the database using the SQL dump file located at database/starter.sql via phpMyAdmin.
Visit your Application
Open your web browser and navigate directly to your local server url:
http://localhost/myphpapp/
🚀 Local Development Server Support
The built-in dev server php kit serve is now fully supported and works perfectly! Even if your application is configured with a subfolder path in your .env's BASE_URL (e.g. http://localhost:8000/my-app), all static assets, authentication systems, and dynamic API/web routes will resolve flawlessly.
🧩 Setup Wizard Presets
The interactive setup wizard prompts you to select one of the three tailored modes during installation:
Full Stack Monolith
Classic server-side HTML views with frontend Alpine.js, cookies, and AJAX.
REST API + UI
Maintains HTML views alongside the Smart Controller that auto-switches `/api/` to pure JSON output.
Backend Only
Deletes all views and frontend folders completely, delivering a 100% stateless RESTful JSON API.
jQuery Stack
Alternative monolith setup preconfigured to use traditional jQuery integrations instead of Alpine.js.
Default accounts loaded by the seeder:
Configuration
All configuration is driven by the .env file. Never hardcode credentials — always use $_ENV['KEY'].
app/config/app.php
APP_NAME, BASE_URL, environment settings
app/config/database.php
DB_HOST, DB_NAME, DB_USER, DB_PASS — PDO connection
app/config/mail.php
MAIL_HOST, MAIL_USER, MAIL_PASS — SMTP for password reset
# Reading config values in PHP
$_ENV['APP_NAME']
$_ENV['DB_HOST']
$_ENV['MAIL_HOST']
CLI Commands
The framework features a custom command-line interface tool named kit to accelerate development tasks. Run it using php kit [command] from your project root.
Database Management
php kit db:seed
seed
Seeds the database using the SQL dump file located in database/starter.sql.
php kit db:fresh
fresh
Drops all existing tables inside the configured database and re-imports the initial schema from scratch.
php kit migrate
migrate
Runs all pending database migrations inside the database/migrations folder.
php kit migrate:rollback
rollback
Rolls back the last batch of database migrations.
Scaffolding (Code Generation)
php kit make:controller [Name] [--admin] [--superadmin] [--resource]
controller
Generates a new Controller class extending the base Controller. Options:
--admin: Places controller inapp/controllers/admin--superadmin: Places controller inapp/controllers/superadmin--resource: Generates CRUD action placeholders (index, create, update, delete)
php kit make:model [Name] [--resource]
model
Generates a new Model class extending the base Model. Pass --resource to prepopulate database querying helper skeletons.
php kit make:view [folder/name] [--resource]
view
Generates a view file inside the app/views directory. Pass --resource to generate CRUD view files (create.php, edit.php, index.php, show.php).
php kit make:middleware [Name]
middleware
Generates a middleware template class under the app/middleware directory.
php kit make:migration [Name]
migration
Generates a new database migration class with timestamp prefix inside database/migrations.
php kit make:auth
auth
Scaffolds full user authentication (views, controllers, models, and routes) automatically.
System Utilities
php kit route:list [filters]
routes
Lists all registered application routes. You can customize and filter the output using options:
- Filter by HTTP method:
php kit route:list GETor--method=POST - Filter by route prefix group:
php kit route:list adminor--group=ajax - Search URI or actions:
php kit route:list profileor--search=create
php kit route:test
api-test
Starts the **Interactive REST API Tester CLI**. This premium tool lets you test all your REST API endpoints directly from the console:
- Auto-resolves the target application URL.
- Interactive menus to browse and select endpoints grouped by category.
- Performs live HTTP requests (GET, POST, PUT, DELETE) right from your terminal.
- Maintains a persistent session using a dedicated cookie jar (test authenticated actions seamlessly).
- Pretty-prints colorized, structured JSON responses.
php kit key:generate
key
Generates a random secure key and sets it as the APP_KEY in your .env file for session validation and hashing encryption.
php kit tinker
tinker
Starts an interactive Read-Eval-Print Loop (REPL) shell where you can run arbitrary PHP code within your application environment.
php kit serve [host?] [port?]
serve
Starts the local PHP built-in development server (defaults to 127.0.0.1:8000).
php kit cache:clear
cache
Clears compiled application cache files.
php kit logs:clear
logs
Clears and empties all application log files.
php kit optimize:clear
clean
Clears all application caches and logs at once.
php kit security:check
security
Launches a Static Application Security Testing (SAST) suite that audits templates for XSS protection, database models for SQLi vulnerability patterns, controllers for active CSRF mitigations, variables for proper parameter type-casting, cryptographic hashes, and HTTP security headers.
Routing
Routes are split across traditional web files inside routes/web/ and the pure REST API routes inside routes/api.php.
client.php
/ — Public pages
admin.php
admin/ — Admin panel
app.php
app/ — Authenticated users
ajax.php
ajax/ — AJAX endpoints
jquery.php
jquery/ — jQuery Stack endpoints (Option 4)
api.php
api/ — REST API JSON endpoints
// GET route
Router::get('about', ['HomeController', 'about']);
// POST route (AJAX)
Router::post('ajax/login', ['AuthController', 'ajaxLogin']);
// GET or POST
Router::any('contact', ['HomeController', 'contact']);
// JSON response
Router::json(['success' => true]);
// Redirect
Router::redirect('login');
Controllers
Controllers live in app/controllers/, extend the base Controller class, and use panel render helpers to load views.
$this->client()
Renders a public client view
$this->app()
Renders an authenticated user view
$this->admin()
Renders an admin panel view
$this->auth()
Renders a login/register view
class PageController extends Controller {
public function index() {
// pass data to view
$this->client('client/page', [
'title' => 'Page Title',
]);
}
}
File naming convention: PascalCaseController.php
Models
Models live in app/models/ and extend the base Model class which provides PDO access.
class Post extends Model {
public function getAll() {
return $this->db->fetchAll("SELECT * FROM posts");
}
public function create(array $data) {
return $this->db->execute(
"INSERT INTO posts (title, body) VALUES (?, ?)",
[$data['title'], $data['body']]
);
}
}
DB logic stays in models — keep controllers thin.
Views
Views are plain PHP files in app/views/, organized by panel. Each panel has its own layout (header + footer) and components.
app/views/client/
Public pages
app/views/app/
Authenticated user pages
app/views/admin/
Admin panel pages
app/views/auth/
Login, register, reset
app/views/layouts/
Header & footer per panel
app/views/components/
Shared UI components
Always sanitize output with htmlspecialchars(). File naming: snake_case.php.
Authentication
Auth is session-based via app/core/Auth.php. Passwords are hashed with bcrypt.
// Check if logged in
Auth::check(); // returns bool
// Get session user
Session::get('user');
// Destroy session (logout)
Session::destroy();
/login
/register
/forgot-password
/reset-password
Admin Panel
The admin panel is accessible at /admin/dashboard and requires an admin session. It includes a collapsible sidebar, topbar with user menu, and data tables.
/admin/dashboard
/admin/users
/admin/profile
/admin/settings
AJAX
AJAX endpoints live under the ajax/ prefix in routes/web/ajax.php. All responses use Router::json(). No jQuery — use the built-in fetch helpers in assets/js/ajax.js.
// PHP — return JSON from a controller
Router::json(['success' => true, 'message' => 'Done']);
// JS — POST with fetch helper
Ajax.post('/ajax/my-endpoint', { key: 'value' })
.then(res => console.log(res));
Database
Database access goes through app/core/Database.php — a PDO singleton. Use it inside models via $this->db.
// Fetch single row
$this->db->fetch("SELECT * FROM users WHERE id = ?", [$id]);
// Fetch all rows
$this->db->fetchAll("SELECT * FROM users");
// Insert / Update / Delete
$this->db->execute("INSERT INTO users (name) VALUES (?)", [$name]);
users
admins
sessions
password_resets
activity_logs
Custom Routes
Add new routes to the appropriate file in routes/web/ based on who can access them.
// routes/web/client.php — public
Router::get('contact', ['HomeController', 'contact']);
// routes/web/app.php — auth required
Router::get('app/dashboard', ['AppController', 'dashboard']);
// routes/web/ajax.php — AJAX POST
Router::post('ajax/save', ['MyController', 'save']);
Deployment
The project ships with a deploy.yml GitHub Actions workflow that rsyncs to a remote server over SSH.
# Required GitHub secrets
SSH_HOST=your-server-ip
SSH_USER=your-ssh-user
SSH_PRIVATE_KEY=contents-of-id_rsa
DEPLOY_PATH=/var/www/html/project
Uncomment the push trigger in .github/workflows/deploy.yml to activate on every push to main.
⭐ Star History
If this project helped you, consider giving it a star on GitHub — it helps others discover it!