PHP Scripting Framework

Overview

This framework is built to give you the ergonomics of a full-stack framework (routing, ORM, CLI, validation, template inheritance) without the weight. Every component is replaceable and the codebase stays small enough to read in an afternoon.

Installation

Requirements

# 1. Clone and install
git clone https://github.com/yourname/scripting.git
cd scripting && composer install

# 2. Create database
mysql -u root -p -e "CREATE DATABASE scripting CHARACTER SET utf8mb4"

# 3. Edit config/db.php, then run migrations
php bin/artisan migrate

Project Structure

Configuration

Database — config/db.php

return [
    'schema'   => 'mysql',
    'host'     => 'localhost',
    'dbname'   => 'scripting',
    'username' => 'admin',
    'password' => 'secret',
];

App — config/app.php

return [
    'app_name'    => 'My App',
    'base_url'    => '/scripting/public',
    'timezone'    => 'Asia/Dhaka',
    'app_mode'    => 'development',   // or 'production'
    'view_folder' => __DIR__ . '/../htmls/views',
];

Routing

Routes are declared on controller methods using PHP 8 attributes — no separate route file needed.

use Src\Attributes\Route;

class PostController extends Controller
{
    #[Route('GET', '/posts')]
    public function index() { ... }

    #[Route('GET', '/posts/{id}', 'post.show')]
    public function show($id) { ... }

    #[Route('POST', '/posts', 'post.store')]
    public function store() { ... }
}

Named Routes

$url = router()->route('post.show', ['id' => 42]);
// → /scripting/public/posts/42

Controllers

Controllers live in src/Controllers/, extend Controller, and are auto-discovered on boot.

namespace Src\Controllers;

class ArticleController extends Controller
{
    #[Route('GET', '/articles')]
    public function index()
    {
        $articles = $this->db()->from('articles')->latest()->paginate(10);
        $this->render('articles/index', compact('articles'));
    }
}

Base Controller Methods

Access Control

#[Auth]   // default "user" guard, redirect to /login if not authenticated
#[Guest]  // default "user" guard, redirect to / if already logged in
#[Route('GET', '/dashboard')]
public function dashboard() { ... }

For admin, staff, vendor, or other areas, use a named guard: #[Auth('admin', '/admin/login')].

Scaffold

php bin/artisan make:controller ArticleController
php bin/artisan make:controller ArticleController --resource

Authentication Guards

Authentication is guard-aware. Each guard stores its own session ID, so a client app can keep user, admin, staff, or any other login area separate.

Guard API

// Default "user" guard
auth()->login($user);
$user = user();                 // same as auth('user')->user()
auth()->logout();

// Named "admin" guard
auth('admin')->login($admin);
$admin = user('admin');       // same as auth('admin')->user()
auth('admin')->check();
auth('admin')->logout();

\Src\Auth::logoutAll();       // logout every active guard

Protected Routes

#[Auth('admin', '/admin/login')]
#[Route('GET', '/admin/dashboard')]
public function dashboard()
{
    $admin = user('admin');
}

#[Guest('admin', '/admin/dashboard')]
#[Route('GET', '/admin/login')]
public function adminLogin() { ... }

Example Admin Login

#[Guest('admin', '/admin/dashboard')]
#[Route('POST', '/admin/login')]
public function postAdminLogin()
{
    $email = $this->post('email');
    $admin = $this->db()->from('admins')->where('email', '=', $email)->first();

    if (!$admin) {
        flash('error', 'Invalid credentials');
        redirect('/admin/login');
    }

    auth('admin')->login($admin);
    redirect('/admin/dashboard');
}

Middleware

php bin/artisan make:middleware RateLimitMiddleware

class RateLimitMiddleware
{
    public function handle(): void
    {
        // inspect, abort or continue
    }
}

Request & Response

$name  = $this->post('name', 'required|min:3');
$page  = $this->get('page');

$this->json(['ok' => true]);
redirect('/dashboard');

Query Builder

Src\Database is a fluent PDO query builder. Get the instance via Database::getInstance() or $this->db() in a controller.

// Read
$user = $db->from('users')
           ->where('email', '=', 'alice@example.com')
           ->first();

$result = $db->from('users')->whereLike('first_name', 'ali')->paginate(15);
// $result->data, ->total, ->pages, ->links

// Write
$db->insert('posts', ['title' => $t, 'body' => $b]);
$db->update('posts', ['title' => 'New'], ['id' => 1]);
$db->delete('posts', ['id' => 1]);

Schema Builder

The Src\Database\Schema facade and Blueprint builder let you define your database structure in expressive PHP — no raw SQL required in migrations. Every method returns a fluent ColumnDefinition so modifiers can be chained indefinitely.

Creating a Table

use Src\Database\Schema;
use Src\Database\Blueprint;

Schema::create('posts', function (Blueprint $table) {
    $table->id();                                   // INT UNSIGNED NOT NULL AUTO_INCREMENT PK
    $table->foreignId('user_id');                  // BIGINT UNSIGNED NOT NULL
    $table->string('title');                        // VARCHAR(255) NOT NULL
    $table->string('slug')->unique();              // + UNIQUE KEY
    $table->text('body')->nullable();              // TEXT NULL
    $table->boolean('published')->default(false);  // TINYINT(1) DEFAULT 0
    $table->tinyInteger('priority')->unsigned()->default(1);
    $table->enum('status', ['draft', 'published', 'archived'])->default('draft');
    $table->json('meta')->nullable();
    $table->timestamps();                          // created_at + updated_at
    $table->softDeletes();                         // deleted_at TIMESTAMP NULL

    // Composite indexes
    $table->index(['user_id', 'status']);
    $table->unique(['user_id', 'slug']);

    // Foreign key constraint
    $table->foreign('user_id')
          ->references('id')->on('users')
          ->cascadeOnDelete();
});

Altering a Table

Schema::table('users', function (Blueprint $table) {
    // Add columns
    $table->string('avatar')->nullable()->after('email');
    $table->boolean('verified')->default(false)->after('avatar');

    // Modify existing column (append ->change())
    $table->string('phone', 50)->nullable()->change();

    // Drop / rename
    $table->dropColumn('old_field');
    $table->renameColumn('bio', 'about');
});

Drop & Introspection

Schema::drop('posts');
Schema::dropIfExists('posts');
Schema::rename('old_name', 'new_name');

Schema::hasTable('users');              // bool
Schema::hasColumn('users', 'email');    // bool
Schema::getColumns('users');            // string[]
Schema::getTables();                     // string[]

Schema::disableForeignKeyChecks();       // before truncate / refresh
Schema::enableForeignKeyChecks();

Blueprint — Column Type Reference

ColumnDefinition — Modifier Chain

Every column type method returns a ColumnDefinition. Chain any modifiers in any order:

Foreign Keys

$table->foreignId('user_id');   // BIGINT UNSIGNED NOT NULL

$table->foreign('user_id')
      ->references('id')
      ->on('users')
      ->cascadeOnDelete();    // ON DELETE CASCADE ON UPDATE RESTRICT

// Aliases for onDelete:
->cascadeOnDelete()   // CASCADE
->nullOnDelete()      // SET NULL
->restrictOnDelete()  // RESTRICT (default)

// Full control:
->onDelete('CASCADE')->onUpdate('SET NULL')
->name('fk_custom_name')         // override auto-generated constraint name

Composite & Full-text Indexes

$table->primary(['order_id', 'product_id']);   // composite PK
$table->unique(['user_id', 'slug']);           // composite unique
$table->index(['status', 'created_at']);       // composite index
$table->fulltext(['title', 'body']);            // FULLTEXT index

Table Options

Schema::create('logs', function (Blueprint $table) {
    $table->engine('MyISAM');
    $table->charset('latin1');
    $table->collation('latin1_swedish_ci');
    $table->id();
    $table->text('message');
});

Models

php bin/artisan make:model Post
php bin/artisan make:model Post --migration   # also creates migration

class Post extends Model
{
    protected $table    = 'posts';
    protected $fillable = ['title', 'body', 'user_id'];
    protected $hidden   = ['password'];
}

Migrations

Migrations live in database/migrations/ as timestamped PHP classes tracked in the migrations table. All generated stubs use the Schema builder.

php bin/artisan make:migration create_posts_table

Generated file:

use Src\Database\Schema;
use Src\Database\Blueprint;

class CreatePostsTable
{
    public function up(): void
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->string('title');
            $table->text('body')->nullable();
            $table->boolean('published')->default(false);
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
}

Commands

• php bin/artisan migrate Run all pending migrations
• php bin/artisan migrate:status Show ran / pending status for every file
• php bin/artisan migrate:rollback Roll back the last batch
• php bin/artisan migrate:refresh Roll back ALL then re-run — ⚠️ clears data

Views & Templating

Views use Plates (native PHP templates). View files live in the path set by config/app.php → view_folder.

<!-- layouts/main.php -->
<html><body>
  <?= $this->section('content') ?>
  <?= $this->section('scripts') ?>
</body></html>

<!-- posts/index.php -->
<?php $this->layout('layouts/main', ['title' => $pageTitle]) ?>

<?php foreach ($posts->data as $post): ?>
  <h2><?= $post->title ?></h2>
<?php endforeach ?>

<?php $this->push('scripts'); ?>
  <script> console.log('loaded'); </script>
<?php $this->end(); ?>

$this->render('posts/index', compact('posts', 'pageTitle'));

Unpoly Frontend

Unpoly is loaded from public/vendor/unpoly and enhances server-rendered PHP views into a smooth single-page experience without a build step.

Built-in Conventions

Helpers

up()->isRequest();
up()->target();
up()->setTarget('#page');
up()->acceptLayer(['id' => 1]);
up()->emit('user:saved');

up_link_attrs();
up_form_attrs();
up_modal_attrs();

Helper Functions

Artisan Console

php bin/artisan <command> [arguments]

Custom Commands

namespace Src\Console\Commands;
use Src\Console\Command;

class SendNewsletterCommand extends Command
{
    protected string $name        = 'newsletter:send';
    protected string $description = 'Send the weekly newsletter';

    public function handle(array $args): int
    {
        $dry = in_array('--dry-run', $args);
        $users = $this->db->from('users')->get();

        foreach ($users as $u) {
            $this->line("  → {$u->email}");
            if (!$dry) { /* mail($u->email, ...) */ }
        }

        $this->success(count($users) . ' emails dispatched');
        return 0;
    }
}

Register in src/Console/Kernel.php → registerCommands():

$this->register(new SendNewsletterCommand());

Session & Cache

// Flash messages
flash('success', 'Saved!');
flash('error',   'Something went wrong');

// Cache
use Src\Cache;
Cache::set("user_{$id}", $user);
$user = Cache::get("user_{$id}");
Cache::delete("user_{$id}");

Validation

$name  = $this->post('name',  'required|min:3|max:100');
$email = $this->post('email', 'required|email');
$age   = $this->post('age',   'required|numeric');

if ($this->validation()) {
    flash('error', $this->renderErrors());
    redirect('/form');
}

Dependency Injection

Powered by Pimple. Bind services in Application::registerServices() or a Service Provider.

$this->container['mailer'] = fn() => new Mailer(app()->getConfig('mail'));

// Resolve anywhere
$mailer = app()->getContainer()['mailer'];

Logging

$log = app()->getContainer()['logger'];   // Monolog instance
$log->info('User login', ['id' => $id]);
$log->error('Payment failed', ['order' => $orderId]);

Default handler writes to logs/request_time.log. Add extra handlers in Application::registerServices().

Error Handling

use Src\Exceptions\AppException;
throw new AppException('Not found', 404);
throw new AppException('Forbidden', 403);

Service Providers

Any class in src/Providers/ extending ServiceProvider with a register(Container $c) method is auto-loaded at boot.

class MailServiceProvider extends ServiceProvider
{
    public function register(Container $c): void
    {
        $c['mailer'] = fn() => new Mailer(app()->getConfig('mail'));
    }
}

PHP Attributes

#[Auth]
#[Route('GET', '/settings')]
public function settings() { ... }

#[Auth('admin', '/admin/login')]
#[Route('GET', '/admin/settings')]
public function adminSettings() { ... }