Miguel Angel Delgado

Posted on May 5 • Originally published at dev.to

I built a modern PHP 8.2 MVC template with full tooling and AI agent support

#php #opensource #webdev #tooling

A few months ago I started with a simple goal: have a solid, reusable base for my PHP projects without pulling in a full framework every time. What I ended up with is something I'm genuinely proud of, and today I'm making it public.

php-template is a PHP 8.2 MVC starter template with serious tooling, full testing stack, and something I haven't seen in other PHP templates: native support for AI agent development.

composer create-project miguelex/php-template my-project

Why not just use Laravel or Symfony?

Fair question. I use frameworks when projects need them. But a lot of the work I do involves specific business modules, integrations with legacy systems, or projects where the overhead of a full framework isn't justified.

The goal here wasn't to replace Laravel. It was to have a clean, well-structured starting point for projects where you want full control over every layer — without starting from scratch every single time.

What's inside

MVC Core

The architecture is built from scratch on PHP 8.2 with strict types throughout.

Router — supports GET, POST, PUT, PATCH, DELETE, _method override for HTML forms, global middleware, and clean 404/500 handling via exceptions.

$router->get('/', [HomeController::class, 'index']);
$router->post('/users', [UserController::class, 'store']);

// Protect routes with middleware
$router->use(AuthMiddleware::check(...));

Two data access patterns — because one size doesn't fit all:

ActiveRecord for simple/medium projects:

final class Post extends ActiveRecord {
    protected static string $table = 'posts';
    protected static array $columns = ['id', 'title', 'body', 'created_at'];
}

$post = Post::find(1);
$post->title = 'Updated title';
$post->save();

Repository pattern for complex domains:

final class PostRepository extends BaseRepository {
    protected string $table = 'posts';

    public function findPublished(): array {
        return $this->findWhere(['published' => 1], 'created_at DESC');
    }

    protected function hydrate(array $row): Post { ... }
    protected function extract(object $entity): array { ... }
}

$repo  = new PostRepository(Database::connect());
$posts = $repo->paginate(page: 1, perPage: 15);

Both patterns can coexist in the same project.

Migration system — no Doctrine, no Eloquent. A clean up()/down() base class with state tracking:

php bin/console migrate
php bin/console migrate:status
php bin/console migrate:rollback 2

AuthMiddleware — session-based auth with session fixation protection, check(), require(), and guest() helpers.

Paginator, JsonResponse, Html helper — common utilities that get reimplemented in every project, included and ready to use.

PHP Code Quality

This is where I spent a lot of time getting the configuration right.

PHPStan level 6 — not level 9 (too many false positives in real projects), not level 0 (pointless). Level 6 catches the important stuff without noise.

PHP-CS-Fixer + PHP_CodeSniffer — PSR-12 enforced. One command to check, one to auto-fix:

composer lint        # detect issues
composer lint:fix    # auto-correct
composer stan        # static analysis
composer qa          # everything at once

PHPUnit 11 + Pest 3 — both, because they serve different purposes. PHPUnit for unit and integration tests, Pest for feature tests with its more expressive syntax.

// PHPUnit style
public function test_throws_when_user_not_found(): void {
    $this->expectException(UserNotFoundException::class);
    $this->service->findById(999);
}

// Pest style
it('throws when user not found', function () {
    expect(fn() => $this->service->findById(999))
        ->toThrow(UserNotFoundException::class);
});

Frontend — two bundler options

Not every PHP project needs React. Most of mine don't. So the template ships with two options:

Gulp 5 — SCSS → CSS, JS bundle, image optimization to WebP and AVIF, BrowserSync. Simple pipeline, zero module bundling complexity.

Vite 6 — for when you start using import/export, need instant HMR, or expect the frontend to grow. Proxy to PHP dev server included.

You choose at project creation time. The init-project.sh script sets everything up.

Generated image formats: original (optimized) + WebP (quality 80) + AVIF (quality 50).

Full testing stack

Vitest — JS unit tests, shared config with Vite
Playwright — E2E tests, auto-starts the PHP server before running

// tests/front/e2e/example.spec.js
test('loads successfully', async ({ page }) => {
    await page.goto('/');
    await expect(page).toHaveTitle(/.+/);
});

CI/CD with GitHub Actions

Two parallel jobs on every push:

PHP QA — PHPCS + PHPStan + PHPUnit + Pest, on PHP 8.2 and 8.3
Front QA — ESLint + Stylelint + Vitest + Playwright

Green on both before any merge.

AI Agent support

This is the part I'm most excited about. The template ships with a .agent/ directory that AI coding agents (Claude Code, Cursor, GitHub Copilot in agent mode) read automatically:

.agent/
├── AGENTS.md       ← entry point: permissions, commands, what NOT to do
├── WORKFLOW.md     ← how to act: plan first, surgical changes, verify before done
├── CONVENTIONS.md  ← coding standards: PHP, JS, SCSS, Git
├── PROJECT.md      ← business context (fill in per project)
└── TASKS.md        ← strategic backlog

tasks/
├── todo.md         ← active task: plan + checkboxes + review
└── lessons.md      ← past mistakes + rules to avoid repeating them

The WORKFLOW.md in particular encodes the behaviors that make AI agents actually useful: plan before acting, touch only what's necessary, verify before marking done, and learn from corrections via lessons.md.

The AGENTS.md explicitly lists what the agent cannot do — no direct edits to generated assets, no lowering PHPStan below level 6, no raw SQL string interpolation, no committing .env.

This turns the template into something that works well with both human developers and AI agents from day one.

CLI tool

php bin/console help

# Migrations
php bin/console migrate
php bin/console migrate:fresh

# Code generators
php bin/console make:controller Post
php bin/console make:model Post
php bin/console make:repository Post
php bin/console make:migration create_posts_table

# Other
php bin/console cache:clear

Makefile

Because nobody should have to remember all the commands:

make dev        # PHP + Gulp (concurrently)
make dev-vite   # PHP + Vite (concurrently)
make qa         # full PHP quality check
make test-all   # PHP + JS + E2E
make migrate    # run pending migrations
make help       # list everything

Starting a new project

# Clone and run the init script
git clone https://github.com/miguelex/php-template.git
cd php-template
./init-project.sh

# Or via Composer
composer create-project miguelex/php-template my-project

The script asks for a project name and mode (backend-only or fullstack), removes what isn't needed, personalizes the config files, and initializes a clean Git repo with a first commit.

Design decisions worth explaining

No framework dependency — the core MVC is ~600 lines of PHP total. You can read it in an afternoon and understand every line. That's intentional.

PHPStan level 6, not 9 — level 9 on a real project with external integrations generates noise. Level 6 catches the important stuff. It can be raised gradually as the codebase matures.

Both Gulp and Vite — not a hedge, a deliberate choice. Gulp is better for projects with simple JS. Vite is better when the frontend grows. Having both available means the template fits more projects.

composer.lock committed — the template has "type": "project", so yes, the lockfile belongs in the repo.

DEV Community