Stackmint PHP Framework

Stackmint is the PHP application skeleton for Wayfinder.

Applications start from Stackmint and depend on Wayfinder Core for the reusable runtime pieces.

Stackmint is aimed at small SaaS and internal business apps with explicit architecture, model-first conventions, and AI-readable code.

At A Glance

• Wayfinder does routing + HTTP + minimal DI
• It does not include an ORM
• It includes a native queue system for sync, database, Redis, and Beanstalkd drivers
• Stackmint is the default starter application shape

Stackmint wires Wayfinder's native queue layer by default with the sync driver, so local development and tests can dispatch jobs without another service. Switch QUEUE_CONNECTION to database, redis, or beanstalkd when the app is ready for background workers.

Mental Model

• Model = entity behavior
• Query = complex read shape
• Service = workflow
• DB = low-level control
• DTO = explicit output shape

View Helpers

Use Wayfinder helpers in PHP views:

<?= e($title) ?>
<a href="<?= e(url('health')) ?>">Health</a>
<img src="<?= e(asset('img/photo.jpg')) ?>" alt="">

Prefer e() over htmlspecialchars(), url() over hard-coded internal links/forms, and asset()/assets() for public assets. See docs/view-helpers.md.

Path Helpers

Use path helpers after bootstrap for application filesystem paths:

storage_path('logs/stackmint.log')
database_path('migrations')
app_path('Controllers/HomeController.php')

See docs/path-helpers.md.

Quick Start

Clone the skeleton, install dependencies, then create a local environment file:

git clone git@github.com:Startermint/stackmint.git my-app
cd my-app
composer install
cp .env.example .env
php wayfinder key:generate
php wayfinder migrate
php -S localhost:8000 -t public

Then open http://localhost:8000.

Production Checklist

Before deploying a public app, set APP_ENV=production, APP_DEBUG=false, and generate a unique APP_KEY with php wayfinder key:generate.

For HTTPS deployments, set SESSION_SECURE=true, configure TRUSTED_HOSTS, configure TRUSTED_PROXIES only for proxies you control, and enable SECURITY_HSTS=true only after the app is served exclusively over HTTPS. Set SECURITY_CSP after verifying the app's frontend asset requirements.

Queues

The starter includes config/queue.php and registers queue() / Wayfinder\Queue\Queue during bootstrap. Use the database driver with:

php wayfinder make:queue-table
php wayfinder make:failed-jobs-table
php wayfinder migrate
php wayfinder queue:work --connection=database --queue=default

For local testing, keep QUEUE_CONNECTION=sync.

For production, run database, redis, or beanstalkd workers under Supervisor/systemd and include recycling controls such as --tries, --timeout, --memory, --max-jobs, and --max-time. See Wayfinder's docs/queue-workers.md for Supervisor examples.

Filesystems

The starter includes config/filesystems.php and registers Wayfinder\Filesystem\Storage during bootstrap. Use the local disk for private app files and the public disk for files served through public/storage:

php wayfinder storage:link

Documentation

Full documentation lives in stackmint-docs:

• GitHub: https://github.com/Startermint/stackmint-docs

Useful companion repositories:

• Wayfinder core: https://github.com/Startermint/wayfinder-core
• Sample application: https://github.com/Startermint/stackmint-task-app