README

FreeFrame is a lightweight, modular PHP framework inspired by Laravel and CakePHP, built for rapid development with minimal setup. It comes with its own powerful CLI tool named free, allowing you to scaffold components, manage your project structure, and streamline development.

🚀 Features

Custom CLI tool – free lets you create controllers, models, and run other useful commands.
Easy to use – Designed to be lightweight and modular, FreeFrame is perfect for building your own web applications.
Automatic routing – Route your requests easily to the correct controllers and methods.
Environment handling – Use .env files for configuration, making it easy to manage different environments.

System Compatibility

PHP 8.0
Composer 2.0
Apache (XAMPP, LAMP)
PDO Driver
MongoDB driver

🧱 Framework Structure

my-app/
├── App/
│   ├── Controllers/
|   |── Middlewares/ 
│   ├── Models/
│   ├── Services/
│   └── Helpers/
├── config/
├── core/
|   ├── bootstrap.php
|   |── Router.php
├── public/
│   └── index.php
├── resources/
│   ├── pages/
│   └── assets/
├── routes/
│   └── route.php
├── storage/
│   ├── Logs/
|   ├── Public/
│   └── Cache/
|   
├── .env
├── .env.example
├── free
├── Execute.sh
├── composer.json
└── README.md

Implemented Features

✔ CLI (php free)

✔ Routing system (routes/route.php)

✔ Controllers (make:controller)

✔ Services (make:service)

✔ Models (make:model)

✔ Middleware (make:middleware)

✔ Logging system (error.log)

✔ log:clear and storage:link commands

✔ Route listing (route:list)

✔ Auto exception logging

✔ Basic MySQL & MongoDB integration setup

✔ Custom command generator (make:command)

✔ Debugger placeholder

✔ CLI server (php free serve)

🏚️ Namespace or Class not found issue resolved

$ composer dump-autoload

Publish Framework

Tag latest commit with a semantic version:

$ git tag v1.0.0
$ git push origin v1.0.0

Submit Framework repo at Packagist https://packagist.org/packages, then click on Update
Create a blnak project $ composer create-project freeframe/freeframe my-app ^2.5
Specify version $ composer create-project freeframe/freeframe my-app "2.5"
Alter try $ composer create-project freeframe/freeframe my-app --stability=dev

✅ Install Symfony Console via Composer

Install

$ composer require symfony/console

Create CLI Entry File

framework/
    ├── ignite_file        ← this is CLI
    ├── composer.json
    ├── vendor/

🗂️ Create a Project

$ composer create-project freeframe/freeframe my-app --stability=dev

Start Server

$ php free serve

Open http://localhost:8000/

List of Commands

Check version

$ php free --version

FreeFrame CLI v1.0.0

Create Controller

$ php free make:controller HomeController

App\Controllers\New-Controller

Create Service Classes under App/Services

$ php free make:service UserService

Create Model

$ php free make:model User

Created at App/Models folder

Clear Error logs

$ php free log:clear

Create Storage link in public

$ php free storage:link

See Available commands

$ php free help

List of Routes

$ php free route:list

Create Middleware

$ php free make:middleware AuthMiddleware

Connect database (Default Support `Mysql` & `MongoDB`)

At Controller or Service Layer

use Core\Database;

$db = (new Database())->getConnection();

// Example RDB query
if ($db instanceof PDO) {
    $stmt = $db->query("SELECT * FROM users");
    $users = $stmt->fetchAll(PDO::FETCH_ASSOC);
}

// Example MongoDB query:
if ($db instanceof \MongoDB\Database) {
    $collection = $db->users;
    $users = $collection->find()->toArray();
}

Install Mongodb extension for PHP

Download extension for Windows from here according to PHP version: Click Check thread safety or not

$ php -i > phpinfo.txt

Search Thread Safety, 💡 If Thread Safety is enabled, you need the TS version of the MongoDB DLL. If it's disabled, download the NTS version. Place the downloaded .dll into: C:\xampp\php\ext Open your php.ini file (in C:\xampp\php) and add: extension=mongodb Restart Apache using the XAMPP control panel.

extension=php_mongodb.dll

Install Cassandra DB for PHP

Download and install cassndra dll (windows) file from here: Click

Unzip the Zip and take php_cassandra.dll file and then place it on C:\xampp\php\ext, after that Open Open your php.ini file (in C:\xampp\php) and add: extension=php_cassandra.dll

For linux

$ sudo pecl install cassandra

Add this extension at php.ini file (in C:\xampp\php)

extension=cassandra.so

Migrate Tables from RDB

$ php free migrate

Create Custom Request

$ php free make:request CommonRequest

use Core\Http\Request;
use Core\Http\Response;
use App\Requests\CommonRequest;

public function store()
{
    $request = new Request();
    $userRequest = new CommonRequest();

    if (!$userRequest->validate($request->all())) {
        return Response::json(['errors' => $userRequest->errors()], 422)->send();
    }

    // Proceed with storing user...

    return Response::json(['message' => 'User created successfully']);
}

👤 Auth Scaffolding feature (JWT Authentication)

$ php free auth:install

AuthController, AuthMiddleware will created JWT secret will append in .env

🏡 ORM Relationships

use App\Models\Profile;
use App\Models\Post;
use App\Models\User;

public function profileDetails()
{
    return $this->hasOnlyOne(Profile::class, 'user_id');
}

public function posts()
{
    return $this->hasManyMore(Post::class, 'user_id');
}

public function author()
{
    return $this->belongsToOnly(User::class, 'user_id');
}

⛯ Create Routes

At routes/route.php

use App\Controllers\HomeController;

$router->get('/', 'HomeController@index');

Define Routes with Prefixes

$router->group(['prefix' => '/api'], function ($router) {
    $router->get('/users', 'UserController@index');
    $router->post('/login', 'AuthController@login');
});

$router->group(['prefix' => '/admin'], function ($router) {
    $router->get('/dashboard', 'AdminController@dashboard');
    $router->post('/settings', 'AdminController@saveSettings');
});

This will shown as

/api/users

/api/login

/admin/dashboard

/admin/settings

📟 Session Manage

use Core\Facades\Session;

//Set a Key
Session::set($key, $value);
// Get a Key Value
Session::get($key);
//Remove Key
Session::forget($key);
//Check session has a particular key
Session::has($key);
//Clear all Session
Session::flush();

🖥️ PHP Curl Operation

use Core\Http\HttpRemote;

(array) $headers;
(array) $data;

$http = new HttpRemote();
//Fetch a remote URL
$http->get($url, $headers);
// Post data to Remote URL
$http->post($url, $data, $headers);
// Update to Remote URL
$http->put($url, $data, $headers);
//Delete request
$http->delete($url, $data, $headers);

🤺 Global Middlewares

App/Middleware/RateLimitMiddleware

// Maximum requests allowed per time window
protected int $maxRequests = 10;
// Time window duration in seconds (e.g., 60 seconds = 1 minute)
protected int $timeWindow = 60;

App/Middleware/AuthMiddleware

public function handle($request, Closure $next)
{
    // Add your logic here

    return $next($request);
}

🗄️ Json Resource Class

Create a Custom Json Resource file Ex: UserResource under App\Resources

namespace App\Resources;

use App\Resources\JsonResource;

class UserResource extends JsonResource
{
    public function toArray(): array
    {
        return [
            'user_id' => $this->resource['id'],
            'full_name' => $this->resource['name'],
            'email' => $this->resource['email'],
            // Add more formatted fields here
        ];
    }
}
// Use in Controller
$userResource = new UserResource($user);
$userResource->send();

🗃️ Maintain Migration file

Create a users table

$ php free make:migration create_users_table

Migrate the db

$ php free migrate

Drop a table

$ php free make:migration drop_orders_table

Language manage

Add language files at lang directory in array format, and then set the desired lang code at config/app.php

lang('lang_key_name');

📧 Mailing system

use Core\Mail\Mail;

$mailer = new Mail();
$mailer->to('recipient@example.com', 'John Doe')
     ->subject('Welcome to FreeFrame!')
     ->body('<h1>Hello from FreeFrame</h1><p>This is your welcome email.</p>')
     ->send();

📮 IMAP (Incoming Mail Access Protocol) Feature

Docuemntation:

Package used

$ composer require webklex/php-imap

Fill the .env

IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_ENCRYPTION=ssl
IMAP_VALIDATE_CERT=true
IMAP_USERNAME=your_email@gmail.com
IMAP_PASSWORD=your_password

Usage

use Core\Mail\ImapClient;

$client = new ImapClient();
$mailbox = $client->getFolders();
$mails = $client->getInboxMessages();
$spambox = $client->getSpamMessages();

💰 Payments supported

use Payments\PaymentManager;
use Payments\Gateways\StripeGateway;
use Payments\Gateways\PaypalGateway;
use Payments\Gateways\RazorpayGateway;
use Payments\Gateways\SquareGateway;

Define Payment gateway name at .env

DEFAULT_PAYMENT_GATEWAY=stripe #razorpay #paypal #square

Fill the details according to Payment Gateway

# Stripe
STRIPE_KEY=''
STRIPE_SECRET=''

# Razorpay
RAZORPAY_KEY=''
RAZORPAY_SECRET=''

# PayPal
PAYPAL_CLIENT_ID=''
PAYPAL_SECRET=''

# Square
SQUARE_ACCESS_TOKEN=''
SQUARE_ENV='sandbox'

🔁 Queue Worker & Queue Job

$ php free make:job JobClassName

Run Queue Job

$ php free queue:work

Base Queue class

\core\Jobs\BaseJob.php

AWS Services supported

SQS (Simple Queue Service)

\core\AWS\SQSService.php

use Core\AWS\SQSService;
$awsService = new SQSService();
$awsService->sendMessage($message);

SES (Simple Email Service)

\core\AWS\SESService.php

use Core\AWS\SESService;
$awsService = new SESService();
$awsService->sendEmail($to, $subject, $htmlBody);

S3 (Simple Storage Service)

\core\AWS\S3Service.php

use Core\AWS\S3Service;
$awsService = new S3Service();
$awsService->upload($key, $body, $contentType);
$awsService->fetch($key, $type); //$type = 'application/octet-stream'

SNS (Simple notification system)

\core\AWS\SNSService.php

use Core\AWS\SNSService;
$awsService = new SNSService();
$awsService->publish($message);
$awsService->event($eventName, $data);

EFS (Elastic File System)

\core\AWS\EFSService.php

use Core\AWS\EFSService;
$awsService = new EFSService();
$awsService->createFileSystem($creationToken);
$awsService->describeFileSystems($fileSystemId);
$awsService->deleteFileSystem($fileSystemId);

Fill the details at .env

AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=ap-south-1

AWS_S3_BUCKET=your-bucket-name
AWS_SQS_QUEUE_URL=https://sqs.ap-south-1.amazonaws.com/xxxx/your-queue
AWS_SNS_TOPIC_ARN=arn:aws:sns:ap-south-1:xxxx:your-topic
AWS_SES_EMAIL=verified@yourdomain.com

👏 Credit

Built with ❤️ by Sagnik Dey

I'm a self-taught programmer and I'm open to any kind of feedback/suggestions. This framework is a hobby project and I'm doing it in my free time. If you find any bug or something that you think should be improved please open an issue or make a pull request.

I'm also a big fan of the Laravel framework, and I've been inspired by it, so if you see something that looks like Laravel, is because I like how they do things. But, I'm not trying to copy them, I'm just trying to do something similar but with my own style.

💻 Tech Stack