One Laravel onelaravel

One Laravel

📖 Giới thiệu

One Laravel là một framework Laravel SPA (Single Page Application) tiên tiến với kiến trúc Modular + Multi-Context, sử dụng Blade to JavaScript compiler độc đáo để tạo ra các ứng dụng web hiện đại, reactive và hiệu suất cao.

Dự án này kết hợp sức mạnh của Laravel backend với trải nghiệm người dùng mượt mà của SPA, đồng thời giữ được sự đơn giản và quen thuộc của Blade templates.

✨ Tính năng nổi bật

🎯 Kiến trúc Modular

Tổ chức code theo module: Mỗi module là một đơn vị độc lập, dễ bảo trì và mở rộng
Hot reload: Tự động reload khi code thay đổi
Dependency management: Quản lý phụ thuộc giữa các module
Lazy loading: Tải module theo nhu cầu để tối ưu hiệu suất

🔄 Multi-Context System

Hỗ trợ nhiều context khác nhau trong cùng một ứng dụng:

Web Context: Giao diện người dùng chính
Admin Context: Trang quản trị
API Context: RESTful API endpoints
Custom Context: Tạo context riêng theo nhu cầu

⚡ Blade to JavaScript Compiler

Công nghệ độc quyền biên dịch Blade templates thành JavaScript:

Viết view bằng Blade syntax quen thuộc
Tự động compile thành JavaScript reactive components
Hỗ trợ tất cả Blade directives (@if, @foreach, @component, etc.)
Custom directives (@val, @bind, @subscribe, @yieldattr, etc.)
Server-Side Rendering (SSR) và Client-Side Hydration

🚀 Reactive System

Hệ thống reactive mạnh mẽ giống Vue.js:

Observable data: Tự động cập nhật UI khi data thay đổi
Two-way binding: @bind directive cho form inputs
Computed properties: Tính toán tự động dựa trên data
Watchers: Theo dõi sự thay đổi của data
Event system: Pub/Sub pattern cho component communication

📦 Component-Based Architecture

Tạo và tái sử dụng components dễ dàng
Props và slots system
Component lifecycle hooks
Scoped styles và isolated state

🎨 Developer Experience

TypeScript support: Type-safe JavaScript code
Hot Module Replacement (HMR): Cập nhật code không reload page
DevTools: Debug tools cho reactive system
Comprehensive documentation: Tài liệu chi tiết và ví dụ

🏗️ Kiến trúc hệ thống

onelaravel/
├── src/                      # Core source code
│   ├── core/                 # Core framework files
│   │   ├── Blade/           # Blade compiler engine
│   │   ├── Observable/      # Reactive system
│   │   └── View/            # View rendering engine
│   ├── contexts/            # Multi-context system
│   │   ├── Web/
│   │   ├── Admin/
│   │   └── Api/
│   ├── modules/             # Application modules
│   ├── templates/           # Base templates
│   └── shared/              # Shared utilities
├── resources/
│   ├── views/               # Blade templates
│   └── js/                  # JavaScript files
├── scripts/                 # Build scripts
│   ├── compiler/            # Python-based compiler
│   └── node/                # Node.js build tools
├── public/
│   └── static/              # Compiled static assets
└── docs/                    # Documentation

🚀 Cài đặt

Yêu cầu hệ thống

PHP >= 8.2
Composer
Node.js >= 18.x
MySQL >= 8.0 hoặc PostgreSQL >= 13
Redis (optional, cho caching)

Các bước cài đặt

Clone repository

git clone git@github.com:onelaravel/onelaravel.git
cd onelaravel

Cài đặt PHP dependencies

composer install

Cài đặt Node.js dependencies

npm install

Cấu hình môi trường

cp .env.example .env
php artisan key:generate

Cấu hình database trong .env

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=onelaravel
DB_USERNAME=root
DB_PASSWORD=

Chạy migrations

php artisan migrate

Compile Blade templates

php artisan blade:compile
# hoặc
npm run compile

Start development server

# Terminal 1: Laravel server
php artisan serve

# Terminal 2: Asset watcher
npm run dev

Truy cập ứng dụng

http://localhost:8000

🛠️ Sử dụng

Tạo Component mới

Tạo Blade component

{{-- resources/views/components/counter.blade.php --}}
<div>
    <h2>Counter: {{$count}}</h2>
    <button @click(increment())>Increment</button>
    <button @click(decrement())>Decrement</button>
</div>

@script
export default {
    data() {
        return {
            count: 0
        }
    },
    methods: {
        increment() {
            this.count++
        },
        decrement() {
            this.count--
        }
    }
}
@endscript

Compile component

php artisan blade:compile

Sử dụng component

@component('components.counter')
@endcomponent

Custom Directives

Declaration Directives

Khai báo variables và state MỘT LẦN ở đầu file template.

@vars - Khai báo variables nhận từ controller (SSR) hoặc API data (client):

{{-- Khai báo MỘT LẦN ở đầu file --}}
@vars($user, $posts = [], $count = 0)

{{-- Variables được destructure từ data được truyền vào view --}}
{{-- Từ controller: return view('profile')->with(['user' => $user, 'posts' => $posts]); --}}
{{-- Từ client: ViewEngine.render('profile', {user: userData, posts: postsList}); --}}

<div>
    <h1>Welcome {{$user->name ?? 'Guest'}}</h1>
    <p>Posts: {{count($posts)}}</p>
    <p>Count: {{$count}}</p>
</div>

@let - Khai báo variables local (React useState style):

@let([$count, $setCount] = useState(0))
@let([$user, $setUser] = useState(null))

<button @click($setCount($count + 1))>
    Increment: {{$count}}
</button>

@const - Khai báo constants:

@const($MAX_ITEMS = 10)
@const($API_URL = 'https://api.example.com')

<p>Max items: {{$MAX_ITEMS}}</p>

Event Directives

Xử lý các sự kiện DOM với syntax: @event(handler(...))

{{-- Click event --}}
<button @click(handleClick())>Click Me</button>

{{-- Event với tham số --}}
<button @click(deleteItem($item->id))>Delete</button>

{{-- Multiple events --}}
<input 
    @input(handleInput($event))
    @blur(validateField())
    @keyup(checkEnter($event))
/>

{{-- Các event khác --}}
<form @submit(handleSubmit($event))>
    <input @change(updateValue($event.target.value)) />
    <div @mouseenter(showTooltip()) @mouseleave(hideTooltip())>
        Hover me
    </div>
</form>

Data Binding Directives

@bind - Two-way data binding cho form inputs:

<input type="text" @bind($username) />
<input type="email" @bind($email) />
<textarea @bind($description)></textarea>
<select @bind($category)>
    <option value="1">Category 1</option>
    <option value="2">Category 2</option>
</select>

{{-- Hiển thị giá trị --}}
<p>Username: {{$username}}</p>
<p>Email: {{$email}}</p>

@val - Render reactive value (chỉ hiển thị):

<div>Count: @val($count)</div>
<span>Total: @val($total)</span>

Subscription Configuration

Cấu hình subscription behavior MỘT LẦN ở đầu file để điều khiển auto re-render.

@subscribe - Config subscription cho toàn bộ view:

{{-- Khai báo MỘT LẦN ở đầu file, ngay sau @vars --}}

{{-- 1. Subscribe tất cả states (mặc định nếu có @vars hoặc @let/@useState) --}}
@subscribe(@all)
{{-- hoặc --}}
@subscribe(true)

{{-- 2. Subscribe một state cụ thể --}}
@subscribe($count)
{{-- View chỉ re-render khi $count thay đổi --}}

{{-- 3. Subscribe nhiều states cụ thể --}}
@subscribe($count, $name)
{{-- hoặc --}}
@subscribe([$count, $name, $email])
{{-- View chỉ re-render khi một trong các state này thay đổi --}}

{{-- 4. KHÔNG subscribe (view sẽ không tự động re-render) --}}
@subscribe(false)
{{-- hoặc --}}
@dontsubscribe

{{-- Ví dụ đầy đủ --}}
@vars($user, $count = 0)
@subscribe($count)
{{-- View này CHỈ re-render khi $count thay đổi, không re-render khi $user thay đổi --}}

<div>
    <h1>{{$user->name}}</h1>
    <p>Count: {{$count}}</p>
</div>

Lưu ý:

Nếu không khai báo @subscribe: mặc định subscribe tất cả nếu có @vars/@let/@useState
@dontsubscribe có độ ưu tiên cao nhất
Chỉ khai báo một lần ở đầu file, không phải ở từng element

@yieldattr - Dynamic attributes:

<button @yieldattr('disabled', $isLoading)>Submit</button>
<input @yieldattr('readonly', $isReadOnly) />
<div @yieldattr('class', $dynamicClass)>Content</div>

Conditional & Loop Directives

{{-- Conditional rendering --}}
@if($isLoggedIn)
    <p>Welcome back!</p>
@else
    <p>Please login</p>
@endif

{{-- Loops --}}
@foreach($items as $item)
    <div @click(selectItem($item->id))>
        {{$item->name}}
    </div>
@endforeach

Tạo Module mới

php artisan make:module Blog

Structure của module:

src/modules/Blog/
├── Controllers/
├── Models/
├── Views/
├── Routes/
└── Providers/

📚 Tài liệu

Tài liệu chi tiết được lưu trong thư mục docs/. Dưới đây là các tài liệu quan trọng nhất:

🏗️ Kiến trúc & Tổng quan

Architecture Overview - Tổng quan kiến trúc hệ thống
System Overview - Cập nhật tổng quan hệ thống
Project Structure - Cấu trúc thư mục và tổ chức code
SPA Laravel Overview - Tổng quan về SPA Laravel
Module Architecture - Kiến trúc module

⚡ Core Systems

Blade Compiler - Tổng quan Blade to JavaScript compiler
Blade to JS Compiler Requirements - Yêu cầu và chi tiết compiler
Views Compiler README - Hướng dẫn views compiler
Observable System - Hệ thống reactive/observable (Quick Start)
Observable Documentation - Tài liệu chi tiết Observable API
Data Observer System - Hệ thống quan sát dữ liệu (Quick Start)
Data Observer Documentation - Tài liệu chi tiết Data Observer API
View Context System - Hệ thống multi-context
View Context Diagrams - Sơ đồ View Context
SPA Scope Configuration - Cấu hình SPA scope

📝 Directives & Syntax

Custom Directives - Tài liệu đầy đủ về tất cả custom directives
Directives Status - Trạng thái implementation các directives
Blade Compiler Command - Hướng dẫn sử dụng compiler command

🚀 Performance & Optimization

Performance Analysis - Phân tích và kế hoạch tối ưu
View JS Render Optimization - Tối ưu rendering
ViewEngine Scan Optimization - Tối ưu ViewEngine scan

🔄 Routing & Flow

Route Flow Diagram - Sơ đồ luồng routing
Route Flow Examples - Ví dụ về route flow

📊 Development & Status

Directives Status - Trạng thái implementation các directives
Performance Analysis - Phân tích và kế hoạch tối ưu

🧪 Testing

# Chạy tất cả tests
php artisan test

# hoặc dùng Pest
./vendor/bin/pest

# Test một file cụ thể
php artisan test --filter=TestClassName

🐳 Docker Support

Project có sẵn Docker configuration:

# Start containers
docker-compose up -d

# Stop containers
docker-compose down

# View logs
docker-compose logs -f

Services:

app: Laravel application (PHP 8.2)
mysql: MySQL 8.0
redis: Redis 7.x

📊 Performance

First Load: < 2s (với cache)
Subsequent Navigation: < 100ms (SPA routing)
Build Time: < 30s (full compile)
Bundle Size: ~ 150KB (gzipped)

🔒 Security

CSRF Protection
XSS Prevention
SQL Injection Protection (Eloquent ORM)
Authentication & Authorization (Laravel Sanctum)
Rate Limiting
Secure Headers

🤝 Đóng góp

Chúng tôi rất hoan nghênh mọi đóng góp! Vui lòng:

Fork repository
Tạo branch mới (git checkout -b feature/AmazingFeature)
Commit changes (git commit -m 'Add some AmazingFeature')
Push to branch (git push origin feature/AmazingFeature)
Mở Pull Request

📝 Changelog

Xem CHANGELOG.md để biết lịch sử thay đổi.

📄 License

The Laravel framework is open-sourced software licensed under the MIT license.

One Laravel is also open-source software licensed under the MIT license.

👥 Team

Creator & Lead Developer: Lê Ngọc Doãn
Contributors: See CONTRIBUTORS.md

🙏 Acknowledgments

Cảm ơn tới:

Laravel - The PHP Framework
Vue.js - Inspiration for reactive system
Alpine.js - Lightweight reactive framework
Tất cả contributors và supporters

📞 Liên hệ

Website: https://onelaravel.com
GitHub: https://github.com/onelaravel/onelaravel
Email: oneaicoder@gmail.com

⭐ Show your support

Nếu bạn thấy project này hữu ích, hãy cho chúng tôi một ⭐ trên GitHub!

Made with ❤️ by One Laravel Team