Skip to content

Commit 6f02f23

Browse files
markcmarkc
committed
WIP backup of current changes
1 parent e42efd3 commit 6f02f23

22 files changed

+1519
-281
lines changed

‎doc/01-Abstract-PHP-Classes.md

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
Let me explain abstract PHP classes and their key differences from concrete classes.
2+
3+
An abstract class in PHP is a class that contains at least one abstract method or is explicitly declared with the 'abstract' keyword. It serves as a template or blueprint for other classes but cannot be instantiated directly.
4+
5+
Here's a practical example to illustrate:
6+
7+
```php
8+
abstract class Vehicle {
9+
protected $brand;
10+
11+
// Regular concrete method
12+
public function setBrand($brand) {
13+
$this->brand = $brand;
14+
}
15+
16+
// Abstract method - must be implemented by child classes
17+
abstract public function startEngine();
18+
}
19+
20+
// Concrete class extending abstract class
21+
class Car extends Vehicle {
22+
// Must implement the abstract method
23+
public function startEngine() {
24+
return "Turning key and starting {$this->brand} car engine";
25+
}
26+
}
27+
```
28+
29+
Key differences from concrete classes:
30+
31+
1. Instantiation:
32+
- Abstract classes CANNOT be instantiated directly (`new Vehicle()` would cause an error)
33+
- Concrete classes CAN be instantiated (`new Car()` works fine)
34+
35+
2. Method Implementation:
36+
- Abstract classes can have both abstract and concrete methods
37+
- Abstract methods must be implemented by child classes
38+
- Concrete classes must implement all methods and cannot have abstract methods
39+
40+
3. Purpose:
41+
- Abstract classes define a common interface and shared behavior for related classes
42+
- Concrete classes provide complete, specific implementations
43+
44+
4. Code Structure:
45+
- Abstract classes often represent generic concepts or base functionality
46+
- Concrete classes represent specific, implementable entities
47+
48+
Would you like me to explain any specific aspect of abstract classes in more detail?

‎doc/01-technical.md

+207
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# Pablo Technical Documentation
2+
3+
## Overview
4+
5+
Pablo is a modular PHP web application framework that uses a plugin-based architecture. It requires PHP 8.4 or higher and follows modern PHP practices including strict types and namespacing.
6+
7+
## Core Architecture
8+
9+
### Entry Point (public/index.php)
10+
11+
The application bootstraps through `public/index.php`, which:
12+
13+
1. Defines the ROOT constant
14+
2. Loads the Composer autoloader
15+
3. Initializes configuration
16+
4. Creates and runs the main application instance
17+
18+
### Initialization Process
19+
20+
The `Init` class (`src/Core/Init.php`) handles the application bootstrap sequence:
21+
22+
1. Environment validation
23+
2. Session initialization
24+
3. Configuration setup
25+
4. Plugin navigation initialization
26+
5. Theme initialization
27+
6. Plugin execution
28+
29+
## Plugin System
30+
31+
### Plugin Structure
32+
33+
Each plugin resides in its own directory under `src/Plugins/` and consists of:
34+
35+
- `Plugin.php`: The main plugin class
36+
- `meta.json`: Plugin configuration and metadata
37+
38+
### Plugin Base Class
39+
40+
All plugins extend the abstract `Plugin` class (`src/Core/Plugin.php`) which:
41+
42+
- Implements the `PluginInterface`
43+
- Provides access to the theme instance
44+
- Requires implementation of the `execute()` method
45+
- Provides string conversion through `__toString()`
46+
47+
### Plugin Interface
48+
49+
The `PluginInterface` (`src/Interfaces/PluginInterface.php`) defines two methods:
50+
51+
- `execute(): mixed` - Main plugin logic
52+
- `__toString(): string` - String representation
53+
54+
### Plugin Discovery
55+
56+
The `PluginScanner` class handles plugin discovery:
57+
58+
1. Scans the plugins directory
59+
2. Reads each plugin's meta.json
60+
3. Creates a navigation structure with:
61+
- Plugin name
62+
- URL (based on plugin directory name)
63+
- Icon
64+
- Display order
65+
66+
### Plugin Metadata (meta.json)
67+
68+
Each plugin includes a meta.json file with:
69+
70+
```json
71+
{
72+
"name": "Plugin Name",
73+
"description": "Plugin description",
74+
"icon": "Bootstrap icon class",
75+
"order": "Navigation display order"
76+
}
77+
```
78+
79+
### Plugin Invocation Process
80+
81+
1. **URL Routing**
82+
83+
- Plugins are invoked via the `plugin` URL parameter
84+
- Default plugin is "Home" if no plugin parameter is specified
85+
86+
2. **Plugin Loading**
87+
88+
```php
89+
$pluginName = ucfirst(strtolower($this->config->in['plugin'] ?? 'Home'));
90+
$pluginClass = "Markc\\Pablo\\Plugins\\{$pluginName}\\Plugin";
91+
```
92+
93+
3. **Instantiation**
94+
95+
- Plugin class is instantiated with Theme instance
96+
- Validates plugin implements PluginInterface
97+
98+
```php
99+
$plugin = new $pluginClass($this->theme);
100+
```
101+
102+
4. **Execution**
103+
- Plugin's execute() method is called via \_\_toString()
104+
- Output is stored in config->out['main']
105+
```php
106+
$this->config->out['main'] = (string)$plugin;
107+
```
108+
109+
### Creating a New Plugin
110+
111+
1. Create directory: `src/Plugins/YourPlugin/`
112+
113+
2. Create meta.json:
114+
115+
```json
116+
{
117+
"name": "Your Plugin",
118+
"description": "Plugin description",
119+
"icon": "bi bi-your-icon fw",
120+
"order": 1
121+
}
122+
```
123+
124+
3. Create Plugin.php:
125+
126+
```php
127+
<?php
128+
declare(strict_types=1);
129+
130+
namespace Markc\Pablo\Plugins\YourPlugin;
131+
132+
use Markc\Pablo\Core\Plugin as BasePlugin;
133+
134+
class Plugin extends BasePlugin
135+
{
136+
public function execute(): mixed
137+
{
138+
// Your plugin logic here
139+
return "Plugin output";
140+
}
141+
}
142+
```
143+
144+
### Plugin Features
145+
146+
1. **Theme Access**
147+
148+
- Plugins have access to the theme instance via `$this->theme`
149+
- Enables consistent styling and layout
150+
151+
2. **Output Formats**
152+
153+
- HTML (default)
154+
- Text (strips HTML tags)
155+
- JSON
156+
- Partial (specific sections)
157+
158+
3. **API Support**
159+
160+
- Plugins can handle API requests
161+
- CSRF protection for API endpoints
162+
- JSON response formatting
163+
164+
4. **Debug Mode**
165+
- Detailed error reporting when APP_DEBUG is enabled
166+
- Request logging
167+
- Performance metrics
168+
169+
## Security Features
170+
171+
1. **Session Security**
172+
173+
- HTTP-only cookies
174+
- Strict same-site policy
175+
- CSRF token generation and validation
176+
177+
2. **Input Sanitization**
178+
179+
- Configuration sanitizes input
180+
- Type declarations enforce data types
181+
182+
3. **Error Handling**
183+
- Production-safe error messages
184+
- Detailed debugging in development
185+
186+
## Best Practices
187+
188+
1. **Plugin Development**
189+
190+
- Use strict types
191+
- Implement proper error handling
192+
- Follow PSR standards
193+
- Document your code
194+
- Include meaningful meta.json
195+
196+
2. **Security**
197+
198+
- Validate all input
199+
- Use CSRF tokens for forms/API
200+
- Sanitize output
201+
- Follow least privilege principle
202+
203+
3. **Performance**
204+
- Keep plugins focused and lightweight
205+
- Cache when appropriate
206+
- Optimize database queries
207+
- Minimize dependencies

‎doc/02-summary.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Pablo Technical Summary
2+
3+
## Core Concepts
4+
5+
Pablo is a PHP 8.4+ web framework using a plugin-based architecture. The system consists of:
6+
7+
1. **Core Framework**
8+
9+
- Entry point (`public/index.php`)
10+
- Configuration management
11+
- Plugin system
12+
- Theme handling
13+
14+
2. **Plugin System**
15+
16+
- Plugins live in `src/Plugins/{PluginName}/`
17+
- Each plugin needs:
18+
- `Plugin.php`: Main class extending `Core\Plugin`
19+
- `meta.json`: Configuration (name, icon, order)
20+
- Plugins are invoked via `?plugin=name` URL parameter
21+
22+
3. **Plugin Lifecycle**
23+
24+
- Discovery: `PluginScanner` finds and loads plugins
25+
- Initialization: Plugin instantiated with theme
26+
- Execution: `execute()` method runs
27+
- Output: Result rendered via theme
28+
29+
4. **Security**
30+
- HTTP-only cookies
31+
- CSRF protection
32+
- Input sanitization
33+
- Type safety

0 commit comments

Comments
 (0)