README

Intent Framework

A zero-boilerplate, AI-native, explicitly designed PHP micro-framework

~3,000 lines of core code. No magic. No facades. No providers.
Just PHP that reads like English.

Yes, most of this was written by AI. Yes, I'm not a PHP expert. No, I don't care.

⚠️ Early Development — Intent is functional and tested (220 tests, 393 assertions!), but it's still young. Perfect for side projects, learning, and experimentation. Not yet battle-tested in production. Bugs? Probably. PRs? Welcome.

⚡ Quick Look

// Route with middleware
Route::get('/dashboard', fn($req, $res) => $res->json([
    'user' => user(),
    'stats' => cache('dashboard_stats'),
]))->middleware(AuthMiddleware::class);

// Validation
$v = validate($request->json(), [
    'email' => 'required|email',
    'password' => 'required|min:8',
]);

if ($v->fails()) {
    return $response->json(['errors' => $v->errors()], 422);
}

// Database (v0.8+ helper syntax)
$users = db()->table('users')->get();

// Cache with remember pattern
$stats = cache()->remember('stats', 3600, fn() => 
    db()->table('stats')->first()
);

// Events
Event::listen('user.created', fn($user) => sendWelcomeEmail($user));
event('user.created', $newUser);

🤔 Why Intent Exists

I was tired of:

• Laravel's 100k+ lines and magic I couldn't trace
• Facades and containers that hide what's actually happening
• Convention over configuration that confused AI assistants
• Frameworks that require a PhD to understand the request lifecycle

I wanted something:

• Simple enough for AI to generate correct code consistently
• Explicit enough that I could read any file and understand it
• Small enough to learn in one sitting (~3k lines total)
• Powerful enough to build real apps without reaching for Laravel

Intent is that framework.

🔥 Addressing the Roasts

This project was posted on r/PHP and got absolutely flamed. Let me own that:

The whole point of Intent is that it's readable, predictable, and AI-friendly.
Whether a human or an AI writes the code, it should be obvious what it does.

🛡️ Quality Gates

| PHPUnit | 220 tests | ✅ Passing | | GitHub Actions | CI/CD | ✅ Automated |

All quality checks run automatically on every push and pull request.

✨ Key Features

🔄 Service Access Pattern (v0.8+)

All services are accessed via registry-backed helpers for consistency and testability:

// ✅ Canonical pattern (v0.8+)
db()->table('users')->where('id', 1)->first();
auth()->user();
cache('key', $value, 3600);
session('user_id');
logger()->info('Message');

// ❌ Deprecated (still works, avoid in new code)
DB::table('users')->get();  // Use db() instead
Cache::put('key', $value);  // Use cache() instead

Static facades will be removed in v2.0. Use helpers for new code.

📦 Installation

Option 1: Composer (Recommended)

composer create-project intent/framework my-app
cd my-app
php intent serve

Option 2: Clone

git clone https://github.com/aamirali51/Intent-Framework.git my-app
cd my-app
composer install

Option 3: Using as Library

If you want to use Intent Framework as a dependency in an existing project:

composer require intent/framework

Important Notes:

1. Define BASE_PATH first — Must be set before anything else
2. Let Core\App handle initialization — Don't load routes manually before App is constructed
3. Config uses flat dot-notation keys — e.g., 'app.name', not nested arrays

Example bootstrap:

<?php
declare(strict_types=1);

// Define BASE_PATH first (required)
define('BASE_PATH', __DIR__);

// Load autoloader
require BASE_PATH . '/vendor/autoload.php';

// App handles config/routes internally via Route::setRouter()
$app = new Core\App();
$app->run();

⚠️ The App constructor initializes the Router internally via Route::setRouter(). If you load routes before constructing App, the router won't be initialized.

🚀 Quick Start

# Start the development server
php intent serve

# Or manually
php -S localhost:8080 -t public

Visit http://localhost:8080 — you should see the welcome page.

🛠️ CLI Commands

php intent --help            # Show all available commands
php intent serve             # Start dev server (port 8080)
php intent serve 3000        # Custom port
php intent cache:clear       # Clear all cached data
php intent make:handler      # Create a handler class
php intent make:middleware   # Create a middleware class
php intent routes            # List registered routes

📚 Documentation

• API Reference — Complete API with input/output types for every method
• Architecture — Technical docs, directory structure, and internals

🧪 Testing

# Run all tests
composer test

# Or directly
vendor/bin/phpunit

Current coverage: 220 tests, 393 assertions

💡 Philosophy

┌─────────────────────────────────────────────────┐
│  Zero Boilerplate                               │
│  ───────────────                                │
│  No service containers. No providers.           │
│  No facades. No annotations.                    │
├─────────────────────────────────────────────────┤
│  Explicit Over Magic                            │
│  ──────────────────                             │
│  Every line does what it says.                  │
│  No hidden behavior. No surprises.              │
├─────────────────────────────────────────────────┤
│  AI-Native Patterns                             │
│  ─────────────────                              │
│  Consistent, predictable code that AI           │
│  assistants can read and extend correctly.      │
├─────────────────────────────────────────────────┤
│  Minimal Abstraction                            │
│  ───────────────────                            │
│  Thin wrappers over PHP. Not frameworks         │
│  on top of frameworks.                          │
└─────────────────────────────────────────────────┘

🗺️ Roadmap

• Route groups with shared middleware
• CSRF protection middleware
• Rate limiting middleware
• Logging system (Log class + helpers)
• Package auto-discovery bootstrap
• intent/auth package (API tokens, OAuth)
• Full CMS demo application
• Package ecosystem

🤝 Contributing

Contributions welcome! Especially if you want to prove it's not "slop" 😄

1. Fork the repo
2. Create a feature branch
3. Write tests for your changes
4. Submit a PR

Check out the ARCHITECTURE.md first to understand the codebase.

📄 License

MIT License. See LICENSE for details.

Built with AI assistance by a non-expert. Shipped anyway.

Roast me again on r/PHP if you want. I'll be here shipping v0.8.1.