core/php-framework
8
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 3
php-framework/docs/guide/configuration.md

504 lines
10 KiB
Markdown
Raw Blame History

# Configuration
Core PHP Framework provides extensive configuration options for all packages. This guide covers the configuration system and available options.
## Configuration System
Core PHP uses Laravel's configuration system with multi-profile support for environment-specific settings.
### Publishing Configuration
Publish configuration files for the packages you need:
```bash
# Publish all core configurations
php artisan vendor:publish --tag=core-config
# Publish specific package configs
php artisan vendor:publish --tag=core-admin-config
php artisan vendor:publish --tag=core-api-config
php artisan vendor:publish --tag=core-mcp-config
```
This creates configuration files in your `config/` directory:
- `config/core.php` - Core framework settings
- `config/core-admin.php` - Admin panel configuration
- `config/core-api.php` - API configuration
- `config/core-mcp.php` - MCP tools configuration
## Core Configuration
Location: `config/core.php`
### Module Paths
Define where the framework scans for modules:
```php
'module_paths' => [
app_path('Core'),
app_path('Mod'),
app_path('Plug'),
base_path('packages'),
],
```
### Module Discovery
Control module auto-discovery behavior:
```php
'modules' => [
'auto_discover' => env('MODULES_AUTO_DISCOVER', true),
'cache_enabled' => env('MODULES_CACHE_ENABLED', true),
'cache_key' => 'core:modules:discovered',
],
```
### Seeder Configuration
Configure automatic seeder discovery and ordering:
```php
'seeders' => [
'auto_discover' => env('SEEDERS_AUTO_DISCOVER', true),
'paths' => [
'Mod/*/Database/Seeders',
'Core/*/Database/Seeders',
],
'exclude' => [
'DatabaseSeeder',
'CoreDatabaseSeeder',
],
],
```
### Activity Logging
Configure activity log retention and behavior:
```php
'activity' => [
'enabled' => env('ACTIVITY_LOG_ENABLED', true),
'retention_days' => env('ACTIVITY_RETENTION_DAYS', 90),
'cleanup_enabled' => true,
'log_ip_address' => false, // GDPR compliance
],
```
### Workspace Cache
Configure team-scoped caching:
```php
'workspace_cache' => [
'enabled' => env('WORKSPACE_CACHE_ENABLED', true),
'ttl' => env('WORKSPACE_CACHE_TTL', 3600),
'use_tags' => env('WORKSPACE_CACHE_USE_TAGS', true),
'prefix' => 'workspace',
],
```
### Action Gate System
Configure request whitelisting for sensitive operations:
```php
'bouncer' => [
'enabled' => env('ACTION_GATE_ENABLED', true),
'training_mode' => env('ACTION_GATE_TRAINING', false),
'block_unauthorized' => true,
'log_all_requests' => true,
],
```
### CDN Configuration
Configure CDN and storage offloading:
```php
'cdn' => [
'enabled' => env('CDN_ENABLED', false),
'provider' => env('CDN_PROVIDER', 'bunny'), // bunny, cloudflare
'url' => env('CDN_URL'),
'storage_url' => env('CDN_STORAGE_URL'),
'apex_domain' => env('CDN_APEX_DOMAIN'),
'zones' => [
'public' => env('CDN_ZONE_PUBLIC'),
'private' => env('CDN_ZONE_PRIVATE'),
],
],
```
### Security Headers
Configure security header policies:
```php
'security_headers' => [
'enabled' => env('SECURITY_HEADERS_ENABLED', true),
'csp' => [
'enabled' => true,
'report_only' => env('CSP_REPORT_ONLY', false),
'directives' => [
'default-src' => ["'self'"],
'script-src' => ["'self'", "'unsafe-inline'"],
'style-src' => ["'self'", "'unsafe-inline'"],
'img-src' => ["'self'", 'data:', 'https:'],
],
],
'hsts' => [
'enabled' => true,
'max_age' => 31536000,
'include_subdomains' => true,
],
],
```
## Admin Configuration
Location: `config/core-admin.php`
### Admin Menu
Configure admin panel navigation:
```php
'menu' => [
'cache_enabled' => env('ADMIN_MENU_CACHE', true),
'cache_ttl' => 3600,
'show_icons' => true,
'collapsible_groups' => true,
],
```
### Global Search
Configure admin global search:
```php
'search' => [
'enabled' => env('ADMIN_SEARCH_ENABLED', true),
'providers' => [
\Core\Admin\Search\Providers\AdminPageSearchProvider::class,
// Add custom providers here
],
'max_results' => 10,
'highlight' => true,
],
```
### Livewire Configuration
Configure Livewire modal behavior:
```php
'livewire' => [
'modal_max_width' => '7xl',
'modal_close_on_escape' => true,
'modal_close_on_backdrop_click' => true,
],
```
## API Configuration
Location: `config/core-api.php`
### Rate Limiting
Configure API rate limits by tier:
```php
'rate_limits' => [
'tiers' => [
'free' => [
'requests' => 1000,
'window' => 60, // minutes
'burst' => 1.2, // 20% over limit
],
'starter' => [
'requests' => 10000,
'window' => 60,
'burst' => 1.2,
],
'pro' => [
'requests' => 50000,
'window' => 60,
'burst' => 1.5,
],
'enterprise' => [
'requests' => null, // unlimited
'window' => 60,
'burst' => 2.0,
],
],
'headers_enabled' => true,
],
```
### API Keys
Configure API key security:
```php
'api_keys' => [
'hash_algorithm' => 'bcrypt', // bcrypt or sha256
'rotation_grace_period' => 86400, // 24 hours
'prefix' => 'sk_', // secret key prefix
'length' => 32,
],
```
### Webhook Configuration
Configure outbound webhook behavior:
```php
'webhooks' => [
'signature_algorithm' => 'sha256',
'max_retries' => 3,
'retry_delay' => 60, // seconds
'timeout' => 10, // seconds
'verify_ssl' => true,
'replay_tolerance' => 300, // 5 minutes
],
```
### OpenAPI Documentation
Configure API documentation:
```php
'documentation' => [
'enabled' => env('API_DOCS_ENABLED', true),
'require_auth' => env('API_DOCS_REQUIRE_AUTH', false),
'title' => env('API_DOCS_TITLE', 'API Documentation'),
'version' => '1.0.0',
'default_ui' => 'scalar', // scalar, swagger, redoc
'servers' => [
[
'url' => env('APP_URL').'/api',
'description' => 'Production',
],
],
],
```
### Scope Enforcement
Configure API scope requirements:
```php
'scopes' => [
'enforce' => env('API_SCOPES_ENFORCE', true),
'available' => [
'bio:read',
'bio:write',
'bio:delete',
'analytics:read',
'webhooks:manage',
'keys:manage',
],
],
```
## MCP Configuration
Location: `config/core-mcp.php`
### Tool Registry
Configure MCP tool discovery:
```php
'tools' => [
'auto_discover' => env('MCP_TOOLS_AUTO_DISCOVER', true),
'paths' => [
'Mod/*/Mcp/Tools',
'Core/Mcp/Tools',
],
'cache_enabled' => true,
],
```
### Database Access
Configure SQL query validation and database access:
```php
'database' => [
'connection' => env('MCP_DB_CONNECTION', 'mcp_readonly'),
'validation' => [
'enabled' => true,
'blocked_keywords' => ['INSERT', 'UPDATE', 'DELETE', 'DROP', 'TRUNCATE'],
'allowed_tables' => '*', // or array of specific tables
'blocked_tables' => ['users', 'api_keys', 'password_resets'],
'whitelist_enabled' => env('MCP_QUERY_WHITELIST', false),
'whitelist_path' => storage_path('mcp/query-whitelist.json'),
],
'explain' => [
'enabled' => true,
'performance_thresholds' => [
'slow_query_rows' => 10000,
'full_table_scan_warning' => true,
],
],
],
```
### Workspace Context
Configure workspace context security:
```php
'workspace_context' => [
'required' => env('MCP_WORKSPACE_REQUIRED', true),
'validation' => [
'verify_existence' => true,
'check_suspension' => true,
],
'cache' => [
'enabled' => true,
'ttl' => 3600,
],
],
```
### Tool Analytics
Configure tool usage tracking:
```php
'analytics' => [
'enabled' => env('MCP_ANALYTICS_ENABLED', true),
'retention_days' => 90,
'track_performance' => true,
'track_errors' => true,
],
```
### Usage Quotas
Configure per-workspace usage limits:
```php
'quotas' => [
'enabled' => env('MCP_QUOTAS_ENABLED', true),
'tiers' => [
'free' => [
'daily_calls' => 100,
'monthly_calls' => 2000,
],
'pro' => [
'daily_calls' => 1000,
'monthly_calls' => 25000,
],
'enterprise' => [
'daily_calls' => null, // unlimited
'monthly_calls' => null,
],
],
],
```
## Environment Variables
Key environment variables for configuration:
```bash
# Core
MODULES_AUTO_DISCOVER=true
MODULES_CACHE_ENABLED=true
SEEDERS_AUTO_DISCOVER=true
# Activity Logging
ACTIVITY_LOG_ENABLED=true
ACTIVITY_RETENTION_DAYS=90
# Workspace Cache
WORKSPACE_CACHE_ENABLED=true
WORKSPACE_CACHE_TTL=3600
WORKSPACE_CACHE_USE_TAGS=true
# Action Gate
ACTION_GATE_ENABLED=true
ACTION_GATE_TRAINING=false
# CDN
CDN_ENABLED=false
CDN_PROVIDER=bunny
CDN_URL=https://cdn.example.com
CDN_STORAGE_URL=https://storage.example.com
# Security Headers
SECURITY_HEADERS_ENABLED=true
CSP_REPORT_ONLY=false
# API
API_DOCS_ENABLED=true
API_DOCS_REQUIRE_AUTH=false
API_SCOPES_ENFORCE=true
# MCP
MCP_TOOLS_AUTO_DISCOVER=true
MCP_DB_CONNECTION=mcp_readonly
MCP_QUERY_WHITELIST=false
MCP_WORKSPACE_REQUIRED=true
MCP_ANALYTICS_ENABLED=true
MCP_QUOTAS_ENABLED=true
```
## Configuration Profiles
Core PHP supports multi-profile configuration for different environments:
### Creating Profiles
```php
use Core\Config\Models\ConfigProfile;
$profile = ConfigProfile::create([
'name' => 'production',
'workspace_id' => $workspace->id,
'is_active' => true,
]);
```
### Setting Configuration Values
```php
use Core\Config\ConfigService;
$config = app(ConfigService::class);
$config->set('api.rate_limit', 10000, $profile);
$config->set('cdn.enabled', true, $profile);
```
### Retrieving Configuration
```php
$rateLimit = $config->get('api.rate_limit', $profile);
```
## Configuration Versioning
Track configuration changes over time:
```bash
# Export current configuration
php artisan config:export production
# Import configuration from file
php artisan config:import production.json --profile=production
# Show configuration version history
php artisan config:version --profile=production
```
## Next Steps
- [Quick Start Guide](/guide/quick-start) - Create your first module
- [Architecture Overview](/architecture/lifecycle-events) - Understand the event system
- [Security Configuration](/security/overview) - Security best practices
Reference in a new issue View git blame Copy permalink