Download the PHP package roy404/framework without Composer

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

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

Languages & Frameworks

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

• Getting Started
  • Installation
  • Server Requirements
• Configuration
  • Environment File
  • Docker Setup
  • Available Services
• Framework Overview
  • Routing
  • Cron
  • Middleware
  • Controllers
  • Models & ORM
  • Schema Builder
  • Views & Blade Templates
  • Artisan CLI
  • StreamWire
• Advanced Topics
  • Real-Time Communication (Socket.IO)
  • Cron Jobs & Scheduler
  • LocalStack & AWS Integration
• Contributing
• License

Getting Started

Installation

Install the framework using Composer:

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

⚙️ Configuration

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)

or on macOS:

Install Composer

Verify installation:

Windows

1. Download PHP from: https://windows.php.net/download/
2. Add the PHP folder to your system PATH.
3. Download Composer from: https://getcomposer.org/download/
4. Run the installer and follow the prompts.

After installation, open Command Prompt or PowerShell and verify:

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

Additionally, If you want to use Docker just install it here: https://www.docker.com/products/docker-desktop

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. http://localhost:8000)
   • 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

Start the development environment using Docker:

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

Tip: You can check logs for any service using
docker-compose logs -f

Example:

Stop and Clean Up

To stop and remove all running containers:

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

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

• 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

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

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

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:

Available Routing Methods:

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

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

Available Frequency Methods

The scheduler provides expressive helpers for defining task frequency:

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:

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

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

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:

Example Usage:

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:

Querying with Models

Models provide a simple, expressive interface for database operations.

Insert a new record:

Fetch active users:

`

Check if a record exists:

Fetch a single column (by primary key):

Using the Database Facade Directly

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

Insert a record:

Run a raw query:

Count total records:

Query from a specific connection:

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

`

Modifying Tables

Renaming and Dropping Tables

Columns Management

Indexes and Keys

Table Options

Export Table Definition

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

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.

Common Blade Directives

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:

Common Commands

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.

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

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

Example:

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

Common Stream-Wire Element Attributes Action

🔧 Advanced Topics

1. Real-Time Communication (Socket.IO)

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

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

Technologies

Docker Service Definition

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

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:

Once added, rebuild and start your containers:

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

Quick Frontend Test

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

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 & 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:

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 & 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:

List existing buckets:

💡 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

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

📜 License

This framework is open-source software licensed under the MIT license.