Getting Started

Getting Started

This guide walks you through setting up a new StackCTL project from scratch — from cloning the framework to having a working app running locally.

Requirements

Before you begin, make sure your environment has the following:

• PHP 8.1+
• MySQL 5.7+ (or MariaDB equivalent)
• Composer
• A local server — Apache or Nginx (WAMP, MAMP, Laragon, or similar)

Step 1 — Place the Framework

Copy or clone the StackCTL framework into your web server's document root (or a virtual host directory). The folder structure should look like this:

your-project/
├── app/
│   ├── Controllers/
│   ├── Core/
│   ├── Helpers/
│   ├── Services/
│   └── Support/
├── bootstrap/
├── build/
│   └── database/
├── config/
├── public/
├── resources/
│   └── views/
├── routes/
├── composer.json
└── index.php

Step 2 — Install Dependencies

From the project root, run Composer to install required packages:

composer install

This will generate the vendor/ directory and set up the autoloader.

Step 3 — Configure the Database

Open config/database.php and update it with your local database credentials:

return [
    'engine'   => 'mysql',
    'host'     => 'localhost',
    'port'     => '3306',
    'dbname'   => 'your_database',
    'user'     => 'your_user',
    'password' => 'your_password',
];

Create the database in MySQL if it doesn't already exist:

CREATE DATABASE your_database CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Step 4 — Configure the App

Open config/app.php and set your application name, environment, and timezone:

return [
    'name'     => 'My App',
    'env'      => 'local',       // Change to 'production' when live
    'timezone' => 'America/Chicago',
    'url'      => '',
];

Tip: When env is set to local, StackCTL will display detailed error messages and throw exceptions for undefined middleware and missing routes. Set it to production before going live.

Step 5 — Run the Migrations

StackCTL comes with built-in migrations for the user authentication system. Run them using the Stack CLI:

php stack db:apply

This will create the following tables automatically:

• users
• password_resets
• email_verifications
• mfa_methods
• mfa_challenges
• trusted_browsers

You can check migration status at any time with:

php stack db:status

Step 6 — Configure Your Web Server

Point your web server's document root to the project root (where index.php lives). StackCTL's index.php at the root simply forwards to public/index.php, which boots the framework.

Apache (.htaccess)

If you're using Apache, make sure mod_rewrite is enabled and add an .htaccess file at the project root:

Options -Indexes
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.php [L]

Nginx

Add this to your server block:

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

Step 7 — Visit Your App

Open your browser and navigate to your local URL (e.g. http://localhost/your-project). You should see the StackCTL welcome screen.

From here, you can register a user account and begin building.

What's Next?

Now that your environment is running, you're ready to start building. Here are a few good next steps:

• Routing — Define routes in routes/web.php
• Controllers — Use php stack create:controller MyController to scaffold one
• Resources — Use php stack create:resource articles to scaffold a full CRUD feature in one command
• Stack CLI — Run php stack help to see all available commands