PHPackages                             roy404/framework - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. roy404/framework

ActiveProject[Database & ORM](/categories/database)

roy404/framework
================

A lightweight PHP framework by Robroy Canales

2.8.1(5mo ago)369MITPHPPHP ^8.1

Since Feb 11Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/roycanales17/Reduced-Framework)[ Packagist](https://packagist.org/packages/roy404/framework)[ RSS](/packages/roy404-framework/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (4)Versions (111)Used By (0)

PHP Framework Documentation
===========================

[](#php-framework-documentation)

Welcome to the official documentation for the **PHP Framework** — a modern, lightweight, and developer-friendly web application framework designed for speed, simplicity, and scalability.

This guide will walk you through installation, configuration, and usage of the framework, along with its key components and features.

### Core Services & Technologies

[](#core-services--technologies)

This project uses a modern containerized architecture powered by Docker, combining application code, databases, caching, queues, and local AWS emulation.

**Languages & Frameworks**

[![PHP](https://camo.githubusercontent.com/c88eeeae90c8ec44c4a684f5f58336140afff72ec5da24eb368fab83d4cf15d2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d3838393242463f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/c88eeeae90c8ec44c4a684f5f58336140afff72ec5da24eb368fab83d4cf15d2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d3838393242463f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)[![Blade](https://camo.githubusercontent.com/8e3512a7fd0c2502a7597855aa92762b788cbdc9bf5d6121adb166d4bee5c439/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f426c6164652d4646324432303f6c6f676f3d6c61726176656c266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/8e3512a7fd0c2502a7597855aa92762b788cbdc9bf5d6121adb166d4bee5c439/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f426c6164652d4646324432303f6c6f676f3d6c61726176656c266c6f676f436f6c6f723d7768697465)[![SCSS](https://camo.githubusercontent.com/16b42eee8e5384a8fcd7bbcc1b326b079dc6e47f5f18abe4c2226156dc43a064/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f534353532d4343363639393f6c6f676f3d73617373266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/16b42eee8e5384a8fcd7bbcc1b326b079dc6e47f5f18abe4c2226156dc43a064/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f534353532d4343363639393f6c6f676f3d73617373266c6f676f436f6c6f723d7768697465)[![TailwindCSS](https://camo.githubusercontent.com/0003b6024dd0f24e152cb79843add39b57ff2503485a195dc0535a63dab8be34/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5461696c77696e644353532d3338423241433f6c6f676f3d7461696c77696e642d637373266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/0003b6024dd0f24e152cb79843add39b57ff2503485a195dc0535a63dab8be34/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5461696c77696e644353532d3338423241433f6c6f676f3d7461696c77696e642d637373266c6f676f436f6c6f723d7768697465)[![Xdebug](https://camo.githubusercontent.com/1f8327a98f28095f7bab2428cc3c6d2c9a237c92aa4ef67d8d0104bd338948ef/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5864656275672d3243383733463f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/1f8327a98f28095f7bab2428cc3c6d2c9a237c92aa4ef67d8d0104bd338948ef/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5864656275672d3243383733463f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)[![Socket.IO](https://camo.githubusercontent.com/47dd3e6a2db62ba9d05b0ee91b0255490883836a69bffd036e4cabf0fb6d5b64/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f536f636b65742e494f2d3031303130313f6c6f676f3d736f636b65742e696f266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/47dd3e6a2db62ba9d05b0ee91b0255490883836a69bffd036e4cabf0fb6d5b64/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f536f636b65742e494f2d3031303130313f6c6f676f3d736f636b65742e696f266c6f676f436f6c6f723d7768697465)[![Docker](https://camo.githubusercontent.com/4b874cd254b289c13ea335c76183785cb5727464b89fee0fb58fa8fd8134fe6e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f446f636b65722d3234393645443f6c6f676f3d646f636b6572266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/4b874cd254b289c13ea335c76183785cb5727464b89fee0fb58fa8fd8134fe6e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f446f636b65722d3234393645443f6c6f676f3d646f636b6572266c6f676f436f6c6f723d7768697465)

**Infrastructure & Services**

- **MySQL 8** – Relational database
- **phpMyAdmin** – Database management UI
- **Redis (Alpine)** – Cache & queue driver
- **Memcached (Alpine)** – Alternative caching layer
- **Mailhog** – Local email testing (SMTP + Web UI)
- **Cron** – Scheduled tasks runner
- **LocalStack** – Local AWS services (S3, SQS, SNS, Lambda, DynamoDB)

This setup provides a full-featured development environment that mirrors production as closely as possible, while staying lightweight and developer-friendly.

---

Table of Contents
-----------------

[](#table-of-contents)

- [Getting Started](#getting-started)
    - [Installation](#installation)
    - [Server Requirements](#1-server-requirements)
- [Configuration](#%EF%B8%8F-configuration)
    - [Environment File](#2-environment-file-env)
    - [Docker Setup](#3-docker-setup)
    - [Available Services](#available-services)
- [Framework Overview](#-framework-overview)
    - [Routing](#1-routing)
    - [Cron](#2-cron-scheduler)
    - [Middleware](#3-middleware)
    - [Controllers](#4-controllers)
    - [Models & ORM](#5-model)
    - [Schema Builder](#6-schema-builder)
    - [Views & Blade Templates](#7-views--blade-templates)
    - [Artisan CLI](#8-artisan-cli)
    - [StreamWire](#9-streamwire)
- [Advanced Topics](#-advanced-topics)
    - [Real-Time Communication (Socket.IO)](#1-real-time-communication-socketio)
    - [Cron Jobs & Scheduler](#2-cron-jobs--scheduler)
    - [LocalStack & AWS Integration](#3-localstack--aws-integration)
- [Contributing](#-contributing)
- [License](#-license)

---

Getting Started
---------------

[](#getting-started)

### Installation

[](#installation)

Install the framework using Composer:

```
composer create-project roy404/framework project-name
```

Once installed, navigate to your project root directory and start the local development server:

```
php artisan serve
```

---

⚙️ Configuration
----------------

[](#️-configuration)

### 1. Server Requirements

[](#1-server-requirements)

Make sure your system meets the following minimum requirements:

- **PHP** ≥ 8.2
- **Composer** (for dependency management)
- **Docker** & **Docker Compose** (for containerized development)

If PHP or Composer are not installed yet, follow these steps:

#### Install PHP (Mac / Linux)

[](#install-php-mac--linux)

```
sudo apt install php php-cli php-mbstring unzip curl -y
```

or on macOS:

```
brew install php
```

Install Composer

```
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
```

Verify installation:

```
php -v
composer -V
```

#### Windows

[](#windows)

1. Download PHP from:
2. Add the PHP folder to your system PATH.
3. Download Composer from:
4. Run the installer and follow the prompts.

After installation, open Command Prompt or PowerShell and verify:

```
php -v
composer -V
```

If these commands return version numbers, both are installed correctly.

Additionally, If you want to use Docker just install it here:

---

### 2. Environment File (.env)

[](#2-environment-file-env)

Before running the project, configure your environment settings.

1. Copy the example file if needed:
    **cp .env.example .env**
2. Update the values as needed — especially:

    - **APP\_URL** (e.g. )
    - **Database credentials**
    - **Mail settings**
    - **AWS or LocalStack credentials** (if applicable)
    - **PROJECT\_ID** — make sure this value is **unique for each project** to avoid Docker container name conflicts.
        Example:
        - Project 1 → `PROJECT_ID=myproject1`
        - Project 2 → `PROJECT_ID=myproject2`

---

### 3. Docker Setup

[](#3-docker-setup)

Start the development environment using Docker:

```
docker-compose up --build -d
```

Once all containers are running, you can access the following services:

ServiceURLDescription🧱 **App (PHP)**Main application🐘 **phpMyAdmin**MySQL database manager💌 **MailHog UI**View test emails sent from the app🧠 **Redis**localhost:6379In-memory cache database🧰 **Memcached**localhost:11211Caching service☁️ **LocalStack**Local AWS cloud service emulatorTip: You can check logs for any service using
**docker-compose logs -f <service\_name>**

Example:

```
docker-compose logs -f app
```

---

### Stop and Clean Up

[](#stop-and-clean-up)

To stop and remove all running containers:

```
docker-compose down
```

If you also want to remove associated volumes and networks (fresh start):

```
docker-compose down -v
```

---

### Troubleshooting (quick)

[](#troubleshooting-quick)

- **Mailer / SMTP errors**: Ensure MAIL\_HOST is set to `mailhog` (not container\_name) when used inside Docker.
- **DB connection issues**: Ensure DB\_HOST is `mysql` and the MySQL container is healthy (`docker-compose ps` / `docker-compose logs mysql`).
- **Ports already in use**: Another project may be using the same host ports (e.g., 8000, 8080, 8025).
    → Change `APP_PORT`, `PMA_PORT`, or other port values in `.env`.

---

### 🧰 Common Commands

[](#-common-commands)

- Rebuild & recreate containers:
    **docker-compose up --build -d**
- Stop & remove containers:
    **docker-compose down**
- Stop, remove containers + volumes:
    **docker-compose down -v**
- Follow logs:
    **docker-compose logs -f**
- Run a shell inside the app container:
    **docker-compose exec app sh**
- Connect to MySQL (from host):
    **mysql -h 127.0.0.1 -P 3306 -u -p**

---

✅ **Tip for multiple projects:**
If you run multiple Docker projects at once, always give each one a **unique `PROJECT_ID`** and different **port numbers** to avoid conflicts.
Example:

- Project A → `PROJECT_ID=framework1`, `APP_PORT=8000`, `PMA_PORT=8080`
- Project B → `PROJECT_ID=framework2`, `APP_PORT=8100`, `PMA_PORT=8180`

---

### Available Services

[](#available-services)

Your development environment comes preconfigured with the following services:

- **app** → The main PHP application container (`/var/www/html`).
- **mysql** → MySQL database service.
- **phpmyadmin** → Web interface for managing MySQL (`http://localhost:8080`).
- **memcached** → Caching service to speed up application performance.
- **mailhog** → SMTP testing tool with a web UI at (`http://localhost:8025`).
- **redis** → In-memory data store for caching, queues, and sessions.
- **cron** → Dedicated service for running scheduled tasks.
- **localstack** → Local AWS cloud emulator (S3, SNS, SQS, etc).
- **xdebug** → Debugging and profiling extension for PHP, integrated into the `app` container.
- **socket** → Real-time communication service powered by **Node.js** and **Socket.IO**, running on port `3000` (`http://localhost:3000`).

---

🏗 Framework Overview
--------------------

[](#-framework-overview)

The framework provides a modular architecture with the following core components.

1. Routing
----------

[](#1-routing)

Routes are the entry points of your application. They define how incoming HTTP requests (such as `GET`, `POST`, `PUT`, or `DELETE`) are mapped to specific actions in your code — usually a function or a controller method.

Think of them as a **map**:

- The **URL** (e.g., `/users/5`)
- The **HTTP method** (e.g., `GET`)
- The **action** (what your app should do, like showing a user profile)

Define routes in the `routes/web.php` file:

```
use App\Routes\Route;
use Handler\Controller\UserController;

Route::get('/', function () {
    return view('welcome');
});

Route::get('/users/{id}', [UserController::class, 'show']);
```

#### Available Routing Methods:

[](#available-routing-methods)

The framework provides a fluent, expressive API for defining routes.
Below are the available static methods for configuring routes:

MethodDescription`put`(string $uri, string|array|Closure $action = \[\])Defines a `PUT` route.`patch`(string $uri, string|array|Closure $action = \[\])Defines a `PATCH` route.`delete`(string $uri, string|array|Closure $action = \[\])Defines a `DELETE` route.`get`(string $uri, string|array|Closure $action = \[\])Defines a `GET` route.`post`(string $uri, string|array|Closure $action = \[\])Defines a `POST` route.`group`(array $attributes, Closure $action)Registers a group of routes with shared configurations and middleware, enhancing route organization and reusability.`controller`(string $className)Registers a controller to handle the route actions.`middleware`(string|array $action)Assigns middleware to the route for request filtering.`prefix`(string $prefix)Adds a URI prefix to all routes in the group.`name`(string $name)Assigns a name to the route, useful for generating URLs.`domain`(string|array $domain)Binds the route to a specific domain or subdomain.`where`(string $key, string $expression)Defines a regular expression constraint for a route parameter.2. Cron Scheduler
-----------------

[](#2-cron-scheduler)

The **Scheduler** provides a route-like API for defining and managing recurring tasks using cron expressions.

Instead of handling raw cron jobs directly, you define schedules in a clean and expressive way — similar to defining routes.

All schedules are defined in the `routes/cron.php` file:

### Sample Schedules

[](#sample-schedules)

```
use App\Console\Schedule;

Schedule::command('clear:logs')->daily();
Schedule::command('emails:send')->everyFiveMinutes();
Schedule::command('report:generate')->at('14:30');
```

### Available Frequency Methods

[](#available-frequency-methods)

The scheduler provides expressive helpers for defining task frequency:

MethodDescription`everyMinute()`Run the task every minute.`everyFiveMinutes()`Run the task every 5 minutes.`hourly()`Run the task every hour.`daily()`Run the task daily at midnight.`weekly()`Run the task weekly on Sunday at midnight.`monthly()`Run the task monthly on the 1st at midnight.`yearly()`Run the task yearly on January 1st at midnight.`cron($expression)`Use a custom cron expression (e.g., `0 6 * * 1-5`).`at('HH:MM')`Run the task daily at a specific time.3. Middleware
-------------

[](#3-middleware)

Middlewares are responsible for filtering and processing HTTP requests before they reach your controllers or route logic. They can be used for authentication, authorization, input validation, logging, or modifying responses.

You can define your middleware in the `Handler/Middleware` directory:

```
namespace Handler\Middleware;

use App\Utilities\Request;

class Account
{
    /**
     * Handle an incoming request.
     *
     * This method is automatically invoked before a route or controller is executed.
     * You can perform validation, authentication, or any pre/post request logic here.
     *
     * @param  Request $request
     * @return mixed
     */
    public function handle(Request $request)
    {
        // Example pre-processing: authentication/validation
        if (!$this->authorize($request)) {
            return redirect('/unauthorized', 403);
        }

        $response = 'ok!';

        // Example post-processing: logging, response modification
        $this->log($request, $response);

        // Return true to continue request processing
        return true;
    }

    /**
     * Perform authorization/validation logic.
     */
    protected function authorize(Request $request): bool
    {
        // Default: allow all requests
        return true;
    }

    /**
     * Example logging or post-processing.
     */
    protected function log(Request $request, mixed $response): void
    {
        // You could log request details here
    }
}
```

**Example Usage**
To register your middleware, open `app/Routes.php` and attach it to a route group:

```
'web' => [
    'middleware' => [
        Handler\Middleware\Account::class
    ]
],
```

This ensures that every request under the web group passes through the `Account` middleware before rendering the final page.

4. Controllers
--------------

[](#4-controllers)

Controllers are responsible for handling **request/response logic**. They act as an intermediary between your routes and your business logic, keeping your code organized and maintainable.

You can define controllers in the `Handler/Controllers` directory:

```
namespace Handler\Controller;

use App\Http\Controller;
use App\Utilities\Request;

class UserController extends Controller
{
    public function show(Request $request, int $id)
    {
        return view('users.show', ['user' => User::find($id)]);
    }
}
```

Example Usage:

```
Route::get('/users/{id}', [Handler\Controller\UserController::class, 'show']);
```

---

5. Model
--------

[](#5-model)

Models represent your database tables and provide an abstraction layer for querying and manipulating records.
Each model maps to a database table and defines the structure of its data.

**Example Model:**

```
namespace Handler\Model;

use App\Databases\Facade\Model;

class User extends Model
{
    public string $primary_key = 'id';
    public string $table = 'users';
    public array $fillable = ['id', 'name', 'email'];
}
```

---

### Querying with Models

[](#querying-with-models)

Models provide a simple, expressive interface for database operations.

**Insert a new record:**

```
$newUser = Handler\Model\User::create([
    'name'  => 'John Doe',
    'email' => 'john.doe@test.com',
    'status' => 1
]);
```

**Fetch active users:**

```
$users = Handler\Model\User::where('active', 1)->fetch();
```

**Check if a record exists:**

```
$isExist = Handler\Model\User::where('id', $userId)->exists();
```

**Fetch a single column (by primary key):**

```
$email = Handler\Model\User::_($userId)->email;
```

---

### Using the Database Facade Directly

[](#using-the-database-facade-directly)

For advanced queries, you can use the `Database` facade directly.

**Insert a record:**

```
App\Databases\Database::create('users', [
    'name'  => 'John Doe',
    'email' => 'john.doe@test.com',
    'status' => 1
]);
```

**Run a raw query:**

```
$users = App\Databases\Database::query("SELECT * FROM users");
```

**Count total records:**

```
$total = App\Databases\Database::table('users')->count();
```

**Query from a specific connection:**

```
$users = App\Databases\Database::server('master')
    ->query("SELECT * FROM users")
    ->fetch();
```

---

6. Schema Builder
-----------------

[](#6-schema-builder)

The **Schema Builder** provides a programmatic way to create, modify, and manage database tables.

It works with closures to define table blueprints and runs SQL queries under the hood.

---

### Creating Tables

[](#creating-tables)

```
use App\Databases\Schema;
use App\Databases\Handler\Blueprints\Table;

Schema::create('users', function (Table $table) {
    $table->id();
    $table->string('name');
    $table->string('email')->unique();
    $table->timestamps();
});
```

---

### Modifying Tables

[](#modifying-tables)

```
use App\Databases\Schema;
use App\Databases\Handler\Blueprints\Table;

Schema::table('users', function (Table $table) {
    $table->string('phone')->nullable();
});
```

---

### Renaming and Dropping Tables

[](#renaming-and-dropping-tables)

```
use App\Databases\Schema;

// Rename table
Schema::renameTable('users', 'members');

// Drop table if it exists
Schema::dropIfExists('sessions');

// Drop table permanently
Schema::drop('logs');
```

---

### Columns Management

[](#columns-management)

```
use App\Databases\Schema;

// Check if table exists
Schema::hasTable('users');

// Get column info
Schema::column('users', 'email');

// Fetch all columns
Schema::fetchColumns('users');

// Drop a column
Schema::dropColumn('users', 'phone');

// Rename a column
Schema::renameColumn('users', 'fullname', 'name', 'VARCHAR(255)');
```

---

### Indexes and Keys

[](#indexes-and-keys)

```
use App\Databases\Schema;

// Add index
Schema::addIndex('users', 'email');

// Drop index
Schema::dropIndex('users', 'email_index');

// Fetch index details
Schema::index('users', 'email_index');
```

---

### Table Options

[](#table-options)

```
use App\Databases\Schema;

// Change storage engine
Schema::setEngine('users', 'InnoDB');

// Change character set and collation
Schema::setCharset('users', 'utf8mb4', 'utf8mb4_unicode_ci');

// Truncate a table
Schema::truncate('users');
```

---

### Export Table Definition

[](#export-table-definition)

```
// Get CREATE TABLE statement for export/backup
$definition = App\Databases\Schema::exportTable('users');
```

✅ With `Schema`, you can define migrations, manage schema changes, and keep your database structure consistent across environments.

---

7. Views & Blade Templates
------------------------------

[](#7-views--blade-templates)

The framework uses the Blade templating engine, which provides a clean and expressive syntax for building your views. Blade templates are compiled into plain PHP and cached for optimal performance.

```
{{-- Escaped output (HTML is escaped) --}}
{{ 'This will not render as bold' }}

{{-- Unescaped output (HTML will render) --}}
{!! 'This will render as bold text' !!}

{{-- Conditional statements --}}
@if($isAdmin)
    You have admin access.
@elseif($isUser)
    You are logged in as a regular user.
@else
    Please log in to continue.
@endif

{{-- Loops --}}

    @foreach($tasks as $task)
        {{ $loop->iteration }}. {{ $task }}
    @endforeach

{{-- Including other templates --}}
@include('partials.footer')

{{-- Components --}}

```

### Common Blade Directives

[](#common-blade-directives)

DirectivesDescriptionExample`{{ $var }}`Escaped output`{{ $user->name }}``{!! $html !!}`Unescaped output (renders HTML)`{!! $post->content !!}``@if / @elseif / @else / @endif`Conditional logic`@if($user)` ... `@endif``@foreach / @endforeach`Loop through an array or collection`@foreach($items as $item)` ... `@endforeach``@for / @endfor`Basic for loop`@for($i = 0; $i < 5; $i++)` ... `@endfor``@include('layout')`Include the path content`@include('header')``@csrf`Insert a CSRF token for forms`@csrf``@php / @endphp`PHP Tags`@php` $test = "foo"; `@endphp``@post`Grab the POST Global Variable`@post('email')`---

8. Artisan CLI
--------------

[](#8-artisan-cli)

The framework includes a powerful command-line interface called Artisan, designed to help you perform common development tasks quickly — such as running servers, managing migrations, creating files, and clearing caches.

You can run Artisan commands using:

```
php artisan [command]
```

### Common Commands

[](#common-commands)

```
# Start the local development server
php artisan serve
```

```
# Display a list of all available commands
php artisan list
```

---

9. StreamWire
-------------

[](#9-streamwire)

Build reactive, stateful UI components with **StreamWire** — without writing any JavaScript.

StreamWire integrates seamlessly with Blade templates, allowing you to render dynamic components directly in your views.

```
namespace Components;

use App\Utilities\Handler\Component;

class Counter extends Component
{
    public $count = 0;

    public function increment()
    {
        $this->count++;
    }

    /**
     * @see ./views/components/counter.blade.php
     */
    public function render()
    {
        return $this->compile([
            'count' => $this->count
        ]);
    }
}
```

Example content `./views/components/counter.blade.php`:

```

    {{ $count }}
    +

```

You can embed reactive components directly inside your Blade views.
Simply call the `stream()` helper function and pass the component class.

**Example:**

```

    {!! stream(Components\Counter::class) !!}

```

This will render the **Counter** component and make it fully interactive without writing any JavaScript.

### Common Stream-Wire Element Attributes Action

[](#common-stream-wire-element-attributes-action)

DirectivesDescriptionExample`wire:model`Two-way data binding between input fields and component properties```wire:click`Trigger an action method on click`Save``wire:submit`Listen for form submission and call a method`...``wire:keydown.keypress`Trigger a method on a specific keypress event```wire:keydown.enter`Trigger an action method when Enter is pressed```wire:keydown.escape`Run a method when Escape is pressed```wire:loader`Show or hide elements or more while a request is processing`Loading...`---

🔧 Advanced Topics
-----------------

[](#-advanced-topics)

### 1. Real-Time Communication (Socket.IO)

[](#1-real-time-communication-socketio)

To support real-time updates such as live notifications, chat, or dashboard syncing, this project includes a dedicated **Socket.IO** microservice built with **Node.js** and integrated into the Docker environment.

---

#### **Core Features**

[](#core-features)

- Real-time bi-directional communication
- WebSocket-based events (auto fallback to polling)
- JSON-based event messaging
- Centralized logging for connections and events

---

#### **Technologies**

[](#technologies)

[![Node.js](https://camo.githubusercontent.com/bad65ddcea7f640d2424b82f0f665fd32a805b70bbcd0590b1490369a7fbf74a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4e6f64652e6a732d31382532422d3333393933333f6c6f676f3d6e6f64652e6a73266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/bad65ddcea7f640d2424b82f0f665fd32a805b70bbcd0590b1490369a7fbf74a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4e6f64652e6a732d31382532422d3333393933333f6c6f676f3d6e6f64652e6a73266c6f676f436f6c6f723d7768697465)[![Socket.IO](https://camo.githubusercontent.com/47dd3e6a2db62ba9d05b0ee91b0255490883836a69bffd036e4cabf0fb6d5b64/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f536f636b65742e494f2d3031303130313f6c6f676f3d736f636b65742e696f266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/47dd3e6a2db62ba9d05b0ee91b0255490883836a69bffd036e4cabf0fb6d5b64/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f536f636b65742e494f2d3031303130313f6c6f676f3d736f636b65742e696f266c6f676f436f6c6f723d7768697465)[![Express](https://camo.githubusercontent.com/0b63d7c93454dec92ad25defd92a8bad94a5e8cedda9aee3660e94b119506300/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f457870726573732d3030303030303f6c6f676f3d65787072657373266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/0b63d7c93454dec92ad25defd92a8bad94a5e8cedda9aee3660e94b119506300/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f457870726573732d3030303030303f6c6f676f3d65787072657373266c6f676f436f6c6f723d7768697465)[![Docker](https://camo.githubusercontent.com/4b874cd254b289c13ea335c76183785cb5727464b89fee0fb58fa8fd8134fe6e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f446f636b65722d3234393645443f6c6f676f3d646f636b6572266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/4b874cd254b289c13ea335c76183785cb5727464b89fee0fb58fa8fd8134fe6e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f446f636b65722d3234393645443f6c6f676f3d646f636b6572266c6f676f436f6c6f723d7768697465)

---

#### **Docker Service Definition**

[](#docker-service-definition)

To scaffold a ready-made Socket.IO service within your project, run:

```
php artisan make:socket
```

This command generates a preconfigured Node.js Socket.IO setup inside your project directory (`/node` by default).

---

Next, register the Socket service in your `docker-compose.yml` file:

```
  node:
      build:
          context: ./node
          dockerfile: Dockerfile
      container_name: ${PROJECT_ID}_socket
      restart: unless-stopped
      ports:
          - "${SOCKET_PORT:-3000}:3000"
      volumes:
          - "./storage/logs/node:/usr/src/app/logs"
      networks:
          - project_network
      env_file:
          - .env
```

Once added, rebuild and start your containers:

```
docker-compose up --build -d
```

This will build and launch the Socket.IO container, making it accessible at 👉 `http://localhost:3000`

---

#### **Quick Frontend Test**

[](#quick-frontend-test)

You can verify the socket connection by embedding the following script in your Blade or HTML view:

```
(function () {
    const script = document.createElement("script");
    script.src = "https://cdn.socket.io/4.7.5/socket.io.min.js";
    script.onload = () => {
        const socket = io("http://localhost:3000");

        socket.on("connect", () => {
            console.log("✅ Connected:", socket.id);
            socket.emit("message", "Hello from frontend");
        });

        socket.on("message", (msg) => {
            console.log("💬 From server:", msg);
        });
    };
    document.head.appendChild(script);
})();
```

When you reload the page, open your browser console — you should see messages confirming a successful connection between the frontend and the Socket.IO server.

---

### 2. Cron Jobs &amp; Scheduler

[](#2-cron-jobs--scheduler)

The project includes a built-in task scheduler for handling automated and recurring jobs (e.g., queue processing, cleanups, reports).

In a **Docker environment**, the scheduler container runs automatically — no additional configuration is required.

However, in a **production environment**, you’ll need to register the scheduler manually in your system crontab to ensure it runs every minute:

```
* * * * * /usr/bin/php /var/www/html/artisan cron:scheduler >> /dev/null 2>&1
```

### Explanation

[](#explanation)

- `* * * * *` → Run every minute.
- `/usr/bin/php` → Path to your PHP binary (check with `which php`).
- `/var/www/html/artisan` → Path to your project's `artisan` file.
- `>> /dev/null 2>&1` → Silences all output (keeps system logs clean).

---

### 3. LocalStack &amp; AWS Integration

[](#3-localstack--aws-integration)

Use LocalStack to emulate AWS services locally during development. This allows you to test S3 storage and other AWS features without connecting to a real AWS account.

Create a new bucket:

```
docker exec -it localstack_container awslocal s3 mb s3://my-bucket
```

List existing buckets:

```
docker exec -it localstack_container awslocal s3 ls
```

💡 Note: LocalStack is intended only for local development and testing. On a production server, you must configure real AWS credentials and services (e.g., using IAM roles, S3 buckets, etc.).

---

🤝 Contributing
--------------

[](#-contributing)

Contributions are welcome! Please fork the repository and submit a pull request.

---

📜 License
---------

[](#-license)

This framework is open-source software licensed under the [MIT license](./LICENSE).

###  Health Score

43

—

FairBetter than 90% of packages

Maintenance74

Regular maintenance activity

Popularity12

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~6 days

Recently: every ~1 days

Total

109

Last Release

171d ago

Major Versions

v1.2.4 → v2.5.02025-10-01

PHP version history (2 changes)1.0.0PHP ^8.0

v1.4.1PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/542567e23f273798a0a4a752804c792654fe6c3753b53752b1d00b7eff2b8b11?d=identicon)[roycanales](/maintainers/roycanales)

---

Top Contributors

[![roycanales17](https://avatars.githubusercontent.com/u/62797701?v=4)](https://github.com/roycanales17 "roycanales17 (450 commits)")

---

Tags

artisanbladescachedatabaseeloquentmiddlewaremvcphproutesschema

### Embed Badge

![Health badge](/badges/roy404-framework/health.svg)

```
[![Health](https://phpackages.com/badges/roy404-framework/health.svg)](https://phpackages.com/packages/roy404-framework)
```

###  Alternatives

[baopham/dynamodb

Eloquent syntax for DynamoDB

4975.7M6](/packages/baopham-dynamodb)[kitar/laravel-dynamodb

A DynamoDB based Eloquent model and Query builder for Laravel.

193675.3k1](/packages/kitar-laravel-dynamodb)[kettle/dynamodb-orm

A lightweight object-dynamodb mapper for PHP

49210.0k](/packages/kettle-dynamodb-orm)[swiftotter/driver

A database task-runner that helps you to turn production database into a staging/development database sandbox

6111.1k2](/packages/swiftotter-driver)[urbanindo/yii2-dynamodb

DynamoDB extensions for Yii2

1471.4k](/packages/urbanindo-yii2-dynamodb)[oryxcloud/laravel-dynamodb-session-driver

DynamoDB Session Driver for Laravel 5

1460.8k](/packages/oryxcloud-laravel-dynamodb-session-driver)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)