ramphor / rake
Rake 2.0 core crawling/migration library
Requires
- php: >=7.4
- guzzlehttp/psr7: ^2.7.0
- nesbot/carbon: ^2.73|^3.9.0
- php-extended/php-html-object: ^6.1|^8.0
- php-http/httplug: ^2.1
- psr/log: ^1.0.1
- ramphor/httplug-guzzle6-adapter: ^2.0.2
- ramphor/php-html-parser: ^3.1.0
- ramphor/sql: 1.0.0
README
Phiên bản: 3.0 Ngày tạo: 2025 Tác giả: Development Team
📋 MỤC LỤC
- Tổng quan Rake Core
- Triết lý thiết kế
- Kiến trúc Framework
- Các thành phần cốt lõi
- Tài liệu kỹ thuật
- Development Guidelines
🎯 TỔNG QUAN RAKE CORE
Mục tiêu dự án
Rake Core là framework tổng quát cho việc xây dựng ứng dụng, không phụ thuộc vào platform cụ thể nào. Framework này cung cấp:
- Platform Agnostic: Không phụ thuộc vào WordPress, Laravel, hay platform cụ thể nào
- Modular Architecture: Kiến trúc module hóa với các thành phần độc lập
- Flow-based Design: Mọi thứ phải thấy được luồng xử lý và có thể visualize
- Dependency Injection: Container pattern cho quản lý dependencies
- Event-driven: Hệ thống event-driven với logging toàn diện
- Extensible: Dễ dàng mở rộng và tùy chỉnh
Vai trò trong hệ sinh thái
┌─────────────────────────────────────────────────────────────┐
│ RAKE ECOSYSTEM │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────┐ │
│ │ RAKE CORE │ │ RAKE WORDPRESS│ │ RAKE │ │
│ │ FRAMEWORK │◄───┤ ADAPTER │ │ OTHER │ │
│ │ │ │ │ │ ADAPTERS│ │
│ │ • Container │ │ • WP Database │ │ • Laravel│ │
│ │ • Kernel │ │ • WP Hooks │ │ • Symfony│ │
│ │ • Bootstrapper │ │ • WP Admin │ │ • Custom │ │
│ │ • Facade │ │ • WP Security │ │ • Platform│ │
│ │ • Migration │ │ • WP Cache │ │ • Specific│ │
│ │ • Logging │ │ • WP Config │ │ • Adapters│ │
│ └─────────────────┘ └─────────────────┘ └─────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────┐ │
│ │ CRAWFLOW │ │ CRAWFLOW CLI │ │ CRAWFLOW│ │
│ │ PLUGIN │ │ TOOL │ │ CORE │ │
│ │ │ │ │ │ │ │
│ │ • WordPress UI │ │ • Command Line │ │ • Engine│ │
│ │ • Visual Editor │ │ • Batch Process │ │ • API │ │
│ │ • Admin Panel │ │ • Scripts │ │ • Core │ │
│ └─────────────────┘ └─────────────────┘ └─────────┘ │
└─────────────────────────────────────────────────────────────┘
Công nghệ sử dụng
- PHP 8.1+: Ngôn ngữ chính
- PSR-4: Autoloading standard
- PSR-3: Logger interface
- PSR-11: Container interface
- Composer: Dependency management
- Monolog: Logging library
🎨 TRIẾT LÝ THIẾT KẾ
Platform Agnostic Philosophy
Rake Core được thiết kế theo triết lý "Platform Agnostic" - không phụ thuộc vào platform cụ thể nào:
┌─────────────────────────────────────────────────────────────┐
│ RAKE CORE FRAMEWORK │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
│ │ CONTAINER │ │ KERNEL │ │ BOOTSTRAPPER│ │
│ │ │ │ │ │ │ │
│ │ • DI Container │ │ • App Lifecycle │ │ • Service │ │
│ │ • Service Locator│ │ • Request Handle│ │ • Provider │ │
│ │ • Dependency Mgmt│ │ • Response Gen │ │ • Bootstrap │ │
│ │ • Singleton Mgmt│ │ • Error Handle │ │ • Register │ │
│ └─────────────────┘ └─────────────────┘ └─────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
│ │ FACADE │ │ MIGRATION │ │ LOGGING │ │
│ │ │ │ │ │ │ │
│ │ • Static Access │ │ • Schema Mgmt │ │ • PSR-3 │ │
│ │ • Service Proxy │ │ • Version Track │ │ • Monolog │ │
│ │ • Easy API │ │ • Auto Migrate │ │ • Daily Logs│ │
│ │ • Clean Interface│ │ • Rollback │ │ • CLI Output│ │
│ └─────────────────┘ └─────────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
Design Patterns Applied
- Dependency Injection: Container pattern cho quản lý dependencies
- Service Locator: Truy cập services thông qua container
- Factory Pattern: Service factory, component factory
- Builder Pattern: Configuration builder, service builder
- Chain of Responsibility: Middleware chain, processor chain
- Strategy Pattern: Service strategy, handler strategy
- Adapter Pattern: Platform adapter, service adapter
- Command Pattern: Console commands, queue commands
- State Pattern: Application state, service state
- Decorator Pattern: Service decorator, middleware decorator
- Observer/Event Bus: Event-driven architecture
Flow-based Architecture
Rake Core được xây dựng theo triết lý "Flow-based Architecture" - mọi thứ phải thấy được luồng xử lý:
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ REQUEST │───▶│ KERNEL │───▶│ RESPONSE │
│ │ │ │ │ │
│ • Input Data │ │ • Process │ │ • Output Data │
│ • Parameters │ │ • Transform │ │ • Status Code │
│ • Headers │ │ • Validate │ │ • Headers │
│ • Context │ │ • Execute │ │ • Body │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ VALIDATION │ │ EXECUTION │ │ LOGGING │ │
│ │ │ │ │ │ │
│ • Input Check │ │ • Service Call │ │ • Request Log │ │
│ • Schema Valid │ │ • Business Logic│ │ • Response Log │ │
│ • Security Check│ │ • Data Process │ │ • Error Log │ │
│ • Permission │ │ • State Change │ │ • Performance │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
🏗️ KIẾN TRÚC FRAMEWORK
Package Structure
rake/
├── src/
│ ├── Container/ # Dependency Injection
│ │ ├── Container.php # Main container
│ │ ├── ContainerInterface.php
│ │ └── ServiceProvider.php
│ ├── Kernel/ # Application Kernels
│ │ ├── AbstractKernel.php
│ │ ├── ConsoleKernel.php
│ │ ├── HttpKernel.php
│ │ └── KernelInterface.php
│ ├── Bootstrapper/ # Service Bootstrappers
│ │ ├── BootstrapperInterface.php
│ │ ├── CoreBootstrapper.php
│ │ └── ServiceBootstrapper.php
│ ├── Facade/ # Facade Pattern
│ │ ├── Facade.php
│ │ ├── Logger.php
│ │ └── Database.php
│ ├── Migration/ # Database Migration
│ │ ├── MigrationManager.php
│ │ ├── SchemaGenerator.php
│ │ └── MigrationInterface.php
│ ├── Logging/ # Logging System
│ │ ├── LoggerManager.php
│ │ ├── LogInterface.php
│ │ └── LogFormatter.php
│ └── Database/ # Database Abstraction
│ ├── DatabaseAdapterInterface.php
│ ├── DatabaseConfig.php
│ └── DatabaseDriverManager.php
├── schema_definitions/ # Database Schemas
├── composer.json
└── README.md
Core Components
1. Container (Dependency Injection)
// Main container for dependency management class Container { private array $services = []; private array $singletons = []; private array $resolved = []; public function bind(string $abstract, $concrete): void; public function singleton(string $abstract, $concrete): void; public function make(string $abstract): mixed; public function has(string $abstract): bool; public function resolve($concrete): mixed; }
2. Kernel (Application Lifecycle)
// Abstract kernel for application lifecycle abstract class AbstractKernel { protected Container $container; protected array $bootstrappers = []; abstract public function bootstrap(): void; abstract public function handle($request): mixed; abstract public function terminate($request, $response): void; }
3. Bootstrapper (Service Registration)
// Service bootstrapper interface interface BootstrapperInterface { public function bootstrap(Container $container): void; public function register(Container $container): void; public function boot(Container $container): void; }
4. Facade (Static Access)
// Base facade class abstract class Facade { protected static Container $container; public static function setContainer(Container $container): void; public static function getFacadeAccessor(): string; public static function __callStatic(string $method, array $arguments): mixed; }
5. Migration (Database Management)
// Migration manager class MigrationManager { private DatabaseAdapterInterface $adapter; private SchemaGenerator $generator; public function runMigrations(): array; public function rollbackMigrations(): array; public function getMigrationStatus(): array; public function createMigration(string $name): string; }
6. Logging (PSR-3 Implementation)
// Logger manager class LoggerManager { private LoggerInterface $logger; private array $config; public function log($level, string $message, array $context = []): void; public function emergency(string $message, array $context = []): void; public function alert(string $message, array $context = []): void; public function critical(string $message, array $context = []): void; public function error(string $message, array $context = []): void; public function warning(string $message, array $context = []): void; public function notice(string $message, array $context = []): void; public function info(string $message, array $context = []): void; public function debug(string $message, array $context = []): void; }
🔧 CÁC THÀNH PHẦN CỐT LÕI
1. Dependency Injection Container
Container Interface
interface ContainerInterface { public function bind(string $abstract, $concrete): void; public function singleton(string $abstract, $concrete): void; public function make(string $abstract): mixed; public function has(string $abstract): bool; public function resolve($concrete): mixed; public function call($callback, array $parameters = []): mixed; }
Service Registration
// Bind interface to implementation $container->bind(DatabaseInterface::class, MySQLDatabase::class); // Bind singleton $container->singleton(LoggerInterface::class, Logger::class); // Bind with closure $container->bind('config', function() { return new Config(['debug' => true]); });
Service Resolution
// Resolve service $logger = $container->make(LoggerInterface::class); // Resolve with parameters $service = $container->make(Service::class, ['param' => 'value']); // Call method with dependency injection $result = $container->call([$service, 'method'], ['param' => 'value']);
2. Kernel System
Abstract Kernel
abstract class AbstractKernel { protected Container $container; protected array $bootstrappers = []; protected array $middleware = []; public function __construct(Container $container) { $this->container = $container; $this->bootstrap(); } abstract public function bootstrap(): void; abstract public function handle($request): mixed; abstract public function terminate($request, $response): void; protected function runBootstrappers(): void { foreach ($this->bootstrappers as $bootstrapper) { $this->container->make($bootstrapper)->bootstrap($this->container); } } }
Console Kernel
class ConsoleKernel extends AbstractKernel { protected array $commands = []; public function handle($input, $output = null): int { // Handle console command $command = $this->resolveCommand($input); return $command->execute($input, $output); } protected function bootstrap(): void { $this->runBootstrappers(); $this->registerCommands(); } }
HTTP Kernel
class HttpKernel extends AbstractKernel { protected array $middleware = []; public function handle($request): Response { // Handle HTTP request $response = $this->sendRequestThroughRouter($request); return $this->prepareResponse($response); } protected function bootstrap(): void { $this->runBootstrappers(); $this->registerMiddleware(); } }
3. Bootstrapper System
Bootstrapper Interface
interface BootstrapperInterface { public function bootstrap(Container $container): void; public function register(Container $container): void; public function boot(Container $container): void; }
Core Bootstrapper
class CoreBootstrapper implements BootstrapperInterface { public function register(Container $container): void { // Register core services $container->singleton(ContainerInterface::class, Container::class); $container->singleton(LoggerInterface::class, Logger::class); $container->singleton(DatabaseAdapterInterface::class, DatabaseAdapter::class); } public function boot(Container $container): void { // Boot core services $logger = $container->make(LoggerInterface::class); $logger->info('Core services booted'); } public function bootstrap(Container $container): void { $this->register($container); $this->boot($container); } }
4. Facade System
Base Facade
abstract class Facade { protected static Container $container; public static function setContainer(Container $container): void { static::$container = $container; } public static function getFacadeAccessor(): string { throw new RuntimeException('Facade does not implement getFacadeAccessor method.'); } public static function __callStatic(string $method, array $arguments): mixed { $instance = static::$container->make(static::getFacadeAccessor()); return $instance->$method(...$arguments); } }
Logger Facade
class Logger extends Facade { protected static function getFacadeAccessor(): string { return LoggerInterface::class; } } // Usage Logger::info('Application started'); Logger::error('An error occurred', ['context' => 'data']);
5. Migration System
Migration Manager
class MigrationManager { private DatabaseAdapterInterface $adapter; private SchemaGenerator $generator; private array $migrations = []; public function runMigrations(): array { $results = []; foreach ($this->migrations as $migration) { try { $this->runMigration($migration); $results[] = ['migration' => $migration, 'status' => 'success']; } catch (Exception $e) { $results[] = ['migration' => $migration, 'status' => 'failed', 'error' => $e->getMessage()]; } } return $results; } public function rollbackMigrations(): array { // Rollback migrations return []; } public function getMigrationStatus(): array { // Get migration status return []; } }
Schema Generator
class SchemaGenerator { private DatabaseAdapterInterface $adapter; public function createTable(string $table, array $schema): bool { $sql = $this->generateCreateTableSQL($table, $schema); return $this->adapter->query($sql); } public function dropTable(string $table): bool { $sql = "DROP TABLE IF EXISTS {$table}"; return $this->adapter->query($sql); } private function generateCreateTableSQL(string $table, array $schema): string { // Generate CREATE TABLE SQL return "CREATE TABLE {$table} (...)"; } }
6. Logging System
Logger Manager
class LoggerManager implements LoggerInterface { private LoggerInterface $logger; private array $config; public function __construct(array $config = []) { $this->config = $config; $this->initializeLogger(); } public function log($level, string $message, array $context = []): void { $this->logger->log($level, $message, $context); } public function emergency(string $message, array $context = []): void { $this->log(LogLevel::EMERGENCY, $message, $context); } public function alert(string $message, array $context = []): void { $this->log(LogLevel::ALERT, $message, $context); } public function critical(string $message, array $context = []): void { $this->log(LogLevel::CRITICAL, $message, $context); } public function error(string $message, array $context = []): void { $this->log(LogLevel::ERROR, $message, $context); } public function warning(string $message, array $context = []): void { $this->log(LogLevel::WARNING, $message, $context); } public function notice(string $message, array $context = []): void { $this->log(LogLevel::NOTICE, $message, $context); } public function info(string $message, array $context = []): void { $this->log(LogLevel::INFO, $message, $context); } public function debug(string $message, array $context = []): void { $this->log(LogLevel::DEBUG, $message, $context); } }
📚 TÀI LIỆU KỸ THUẬT
Tài liệu chi tiết
📖 docs/technical-documentation.md
Nội dung:
- Container (Dependency Injection)
- Kernel System
- Bootstrapper System
- Database Migration
- Logging System
- Facade Pattern
- Development Guidelines
Code Examples
Container Usage
// Create container $container = new Container(); // Register services $container->singleton(LoggerInterface::class, Logger::class); $container->bind(DatabaseInterface::class, MySQLDatabase::class); // Resolve services $logger = $container->make(LoggerInterface::class); $database = $container->make(DatabaseInterface::class); // Use services $logger->info('Service resolved successfully');
Kernel Usage
// Create kernel $container = new Container(); $kernel = new ConsoleKernel($container); // Handle command $input = new ArgvInput(); $output = new ConsoleOutput(); $exitCode = $kernel->handle($input, $output);
Facade Usage
// Set container Facade::setContainer($container); // Use facades Logger::info('Application started'); Database::query('SELECT * FROM users');
Migration Usage
// Create migration manager $adapter = new DatabaseAdapter(); $manager = new MigrationManager($adapter); // Run migrations $results = $manager->runMigrations(); // Check status $status = $manager->getMigrationStatus();
🛠️ DEVELOPMENT GUIDELINES
Coding Standards
PSR-12 Compliance
<?php declare(strict_types=1); namespace Rake\Container; use Rake\Contracts\ContainerInterface; class Container implements ContainerInterface { private array $services = []; private array $singletons = []; private array $resolved = []; public function bind(string $abstract, $concrete): void { $this->services[$abstract] = $concrete; } public function singleton(string $abstract, $concrete): void { $this->singletons[$abstract] = $concrete; } public function make(string $abstract): mixed { if ($this->has($abstract)) { return $this->resolve($this->services[$abstract]); } throw new RuntimeException("Service {$abstract} not found."); } public function has(string $abstract): bool { return isset($this->services[$abstract]); } }
Interface Segregation
// Define specific interfaces interface LoggerInterface { public function log($level, string $message, array $context = []): void; public function emergency(string $message, array $context = []): void; public function alert(string $message, array $context = []): void; public function critical(string $message, array $context = []): void; public function error(string $message, array $context = []): void; public function warning(string $message, array $context = []): void; public function notice(string $message, array $context = []): void; public function info(string $message, array $context = []): void; public function debug(string $message, array $context = []): void; } interface DatabaseAdapterInterface { public function query(string $sql): bool; public function getResults(string $sql): array; public function getRow(string $sql): ?array; public function getVar(string $sql): mixed; public function insert(string $table, array $data): int; public function update(string $table, array $data, array $where): int; public function delete(string $table, array $where): int; public function getPrefix(): string; public function escape(string $value): string; }
Testing Guidelines
Unit Testing
class ContainerTest extends TestCase { private Container $container; protected function setUp(): void { $this->container = new Container(); } public function testBindService(): void { // Arrange $this->container->bind('test', TestService::class); // Act $service = $this->container->make('test'); // Assert $this->assertInstanceOf(TestService::class, $service); } public function testSingletonService(): void { // Arrange $this->container->singleton('singleton', SingletonService::class); // Act $service1 = $this->container->make('singleton'); $service2 = $this->container->make('singleton'); // Assert $this->assertSame($service1, $service2); } }
Integration Testing
class KernelIntegrationTest extends TestCase { public function testConsoleKernel(): void { // Arrange $container = new Container(); $kernel = new ConsoleKernel($container); // Act $input = new ArgvInput(['command' => 'test']); $output = new ConsoleOutput(); $exitCode = $kernel->handle($input, $output); // Assert $this->assertEquals(0, $exitCode); } }
Error Handling
class RakeException extends Exception { public function __construct(string $message, array $context = [], int $code = 0, ?Throwable $previous = null) { parent::__construct("Rake error: {$message}", $code, $previous); } } // Usage try { $container = new Container(); $service = $container->make('non-existent-service'); } catch (RakeException $e) { Logger::error('Service resolution failed: ' . $e->getMessage()); }
🔧 CONFIGURATION
Basic Configuration
// Container configuration $container = new Container(); // Register core services $container->singleton(LoggerInterface::class, Logger::class); $container->bind(DatabaseAdapterInterface::class, DatabaseAdapter::class); // Register configuration $container->bind('config', function() { return [ 'debug' => true, 'log_level' => 'info', 'database' => [ 'host' => 'localhost', 'database' => 'test', 'username' => 'root', 'password' => '' ] ]; });
Advanced Configuration
// Service provider pattern class AppServiceProvider implements ServiceProviderInterface { public function register(Container $container): void { // Register services $container->singleton(LoggerInterface::class, Logger::class); $container->bind(DatabaseAdapterInterface::class, DatabaseAdapter::class); } public function boot(Container $container): void { // Boot services $logger = $container->make(LoggerInterface::class); $logger->info('Application services booted'); } } // Register service provider $container = new Container(); $container->register(new AppServiceProvider());
🚨 TROUBLESHOOTING
Common Issues
Error: Service not found
Solution:
// Ensure service is registered $container->bind('service', ServiceClass::class); // Check if service exists if ($container->has('service')) { $service = $container->make('service'); }
Error: Circular dependency detected
Solution:
// Use lazy loading $container->bind('service', function() { return new ServiceClass(); }); // Or use interface $container->bind(ServiceInterface::class, ServiceClass::class);
Error: Facade not initialized
Solution:
// Set container for facades Facade::setContainer($container); // Then use facades Logger::info('Application started');
Debug Mode
// Enable debug mode $container->bind('debug', true); // Check container state $services = $container->getServices(); $singletons = $container->getSingletons();
📊 PERFORMANCE
Optimizations
- Lazy loading: Services only instantiated when needed
- Singleton pattern: Single instance for expensive services
- Caching: Resolved services cached
- Memory management: Efficient memory usage
Best Practices
// Use singletons for expensive services $container->singleton(LoggerInterface::class, Logger::class); $container->singleton(DatabaseAdapterInterface::class, DatabaseAdapter::class); // Use interfaces for flexibility $container->bind(ServiceInterface::class, ServiceClass::class); // Use lazy loading for complex dependencies $container->bind('complex-service', function() { return new ComplexService(new Dependency1(), new Dependency2()); });
🎯 KẾT LUẬN
Rake Core Framework cung cấp nền tảng tổng quát cho việc xây dựng ứng dụng với:
Điểm nổi bật:
- Platform Agnostic: Không phụ thuộc vào platform cụ thể nào
- Modular Architecture: Kiến trúc module hóa với các thành phần độc lập
- Flow-based Design: Mọi thứ phải thấy được luồng xử lý
- Dependency Injection: Container pattern cho quản lý dependencies
- Event-driven: Hệ thống event-driven với logging toàn diện
- Extensible: Dễ dàng mở rộng và tùy chỉnh
Triết lý:
"Platform Agnostic" - framework tổng quát, không phụ thuộc vào platform cụ thể nào, chỉ tập trung vào lý thuyết, tư tưởng và triết lý thiết kế.
Tương lai:
- Mở rộng adapter system
- Thêm nhiều platform adapters
- Performance optimization
- Advanced features
- Community contributions
Tài liệu này sẽ được cập nhật thường xuyên khi có thay đổi trong framework.