README

Saola Core — PHP/Laravel backend library của hệ sinh thái Saola, framework full-stack để xây dựng ứng dụng web reactive với Laravel + TypeScript + .sao templates.

Hệ sinh thái Saola

Tính năng chính

🔧 Core Engines

• ShortCode Engine: Hệ thống shortcode tương tự WordPress (Saola\Core\Engines\ShortCode)
• ViewContextManager: Quản lý đa context view state cho Saola client hydration
• Cache Engine: Cấu hình cache đa lớp với auto-invalidation
• DCrypt Engine: Mã hóa/giải mã dữ liệu an toàn

🎯 Magic Classes

• Arr: Array wrapper với magic methods và helper functions (Saola\Core\Magic\Arr)
• Str: String utilities với hỗ trợ tiếng Việt
• Any: Universal data wrapper cho mọi kiểu dữ liệu

🗂️ File Management

• Filemanager: Quản lý file và thư mục toàn diện
• Zip / File Methods: Nén, giải nén và chuyển đổi định dạng file

🌐 HTTP & API

• HTTP Client: Client với Promise support (Saola\Core\Http\Client)
• CURL Wrapper: Support async / curl multi requests

📊 Repository Pattern

• BaseRepository: CRUD, Filter, Search, Pagination và Cache integration (Saola\Core\Repositories\BaseRepository)
• RepositoryTap: Safe repository operations với error handling
• Support Databases: MySQL & PostgreSQL

🎨 Service Layer & Auto Response

• BaseService / ModuleService: Business logic & Module CRUD management (Saola\Core\Services\ModuleService)
• ResponseMethods: Tự động trả về View hoặc JSON dựa trên request headers (X-Saola-Response, Accept: application/json)
• ViewMethods: Integrated ViewContextManager rendering

🎯 Event System

• EventMethods: Class-based isolation, multi-listener support, magic method event triggering (Saola\Core\Events\EventMethods)

Yêu cầu hệ thống

• PHP: ^8.2
• Laravel: ^12.0 | ^13.0
• Laravel Octane: ^2.0 (tùy chọn)

Cài đặt

1. Cài đặt qua Composer

composer require saola/core

2. Đăng ký Service Provider & Publish Config

Service Provider Saola\Core\Providers\SaolaServiceProvider tự động đăng ký qua Laravel Auto-Discovery.

Publish configuration:

php artisan vendor:publish --tag=saola-config

Publish migrations (tùy chọn):

php artisan vendor:publish --tag=saola-migrations
php artisan migrate

Cấu trúc thư mục

src/
├── config/                  # Configuration files (saola.php)
├── core/                    # Saola\Core namespace root
│   ├── Async/               # Async/await utilities
│   ├── Concerns/            # Model traits (HasUuid, HasSlug, ...)
│   ├── Console/             # Artisan commands
│   ├── Contracts/           # Interfaces & contracts
│   ├── Crawlers/            # Web crawling utilities
│   ├── Database/            # DB utilities & query helpers
│   ├── Engines/             # ShortCode, Cache, DCrypt, ViewContextManager
│   ├── Events/              # Event system (EventMethods)
│   ├── Exceptions/          # Exception handlers
│   ├── Files/               # File management system
│   ├── Html/                # HTML, Form, Menu builders
│   ├── Http/                # HTTP client & utilities
│   ├── Languages/           # Locale management (i18n)
│   ├── Laravel/             # Laravel framework integrations
│   ├── Magic/               # Arr, Str, Any magic classes
│   ├── Mailer/              # Email alert & mailer system
│   ├── Masks/               # Data masking & transformation
│   ├── Models/              # Base Eloquent models
│   ├── Promise/             # Promise & async utilities
│   ├── Providers/           # SaolaServiceProvider
│   ├── Queues/              # Queue management
│   ├── Repositories/        # BaseRepository, Filter & CRUD actions
│   ├── Routing/             # Module routing system (Action, Module, Router)
│   ├── Services/            # BaseService, ModuleService, ViewService
│   ├── Support/             # Utility helpers & traits (Methods/ViewMethods, etc.)
│   ├── System/              # System utilities
│   └── Validators/          # Validation system
├── helpers/                 # Global helpers (__loader__.php, helpers.php)
└── templates/               # Default templates

Ví dụ sử dụng

ShortCode Engine

use Saola\Core\Engines\ShortCode;

// Đăng ký shortcode
ShortCode::addShortcode('hello', function($atts, $content, $tag) {
    return '<h2>Xin chào từ shortcode!</h2>';
});

// Sử dụng trong nội dung
$content = "Nội dung gốc. [hello] Nội dung sau.";
$result = ShortCode::do($content, false);

Magic Array

use Saola\Core\Magic\Arr;

$data = new Arr(['name' => 'Saola', 'version' => '2.0']);

echo $data->name; // Saola
echo $data->get('version'); // 2.0
$data->set('type', 'framework');

Repository Pattern

use Saola\Core\Repositories\BaseRepository;

class UserRepository extends BaseRepository
{
    protected $model = User::class;

    public function findByEmail($email)
    {
        return $this->model::where('email', $email)->first();
    }
}

Service Layer với Auto View/JSON Response

use Saola\Core\Services\ModuleService;
use Saola\Core\Support\Methods\ViewMethods;
use Saola\Core\Support\Methods\ResponseMethods;
use Illuminate\Http\Request;

class UserService extends ModuleService
{
    use ViewMethods, ResponseMethods;

    protected $context = 'web';
    protected $module = 'users';

    public function initUser()
    {
        $this->setRepositoryClass(UserRepository::class);
        $this->initView();
    }

    public function getUserList(Request $request)
    {
        $users = $this->repository->getResults($request);

        // Tự động trả về view hoặc JSON dựa trên request headers
        return $this->response([
            'users' => $users,
            'title' => 'Danh sách người dùng'
        ], 'users.index');
    }
}

Request Headers kiểm tra:

• X-Saola-Response: json hoặc X-Sao-Response: json → Trả về JSON
• Accept: application/json → Trả về JSON
• Request thông thường → Trả về Blade View

Event System

use Saola\Core\Events\EventMethods;

class UserService
{
    use EventMethods;

    public function createUser($data)
    {
        static::on('user.created', function($user) {
            // Gửi email hoặc log activity
        });

        $user = User::create($data);
        static::trigger('user.created', $user);

        return $user;
    }
}

Laravel Octane Support

Saola Core hỗ trợ tối ưu state management cho Laravel Octane qua contract Saola\Core\Contracts\OctaneCompatible:

use Saola\Core\Contracts\OctaneCompatible;

class MyService implements OctaneCompatible
{
    private static $cache = [];

    public static function resetStaticState(): void
    {
        self::$cache = [];
    }

    public function resetInstanceState(): void
    {
    }

    public static function getStaticProperties(): array
    {
        return ['cache'];
    }
}

Tài liệu chi tiết

• Kiến trúc hệ thống
• Tổng quan cấu trúc
• Quick Start Guide
• Recent Updates Guide
• Response Methods Usage
• View Context Manager Guide

Xem toàn bộ danh mục tài liệu trong thư mục docs/.

License

MIT © SaoLabs Team