Skip to content

Configuration

Jump to bottom
lpachecob edited this page Mar 24, 2026 · 4 revisions

⚙️ Configuration: boundly.php

Everything in BOUNDLY can be customized. The configuration file config/boundly.php is the bridge between your domain and the infrastructure layer.

All values support .env overrides for clean environment separation.

🔝 locale

The default language for CLI output and system messages.

Value Default Description
'en' ✅ English
'es' Spanish 
BOUNDLY_LOCALE=es

🌐 api_prefix

The URL segment for all auto-generated endpoints.

Default Description
'api' Generates routes like /api/users, /api/posts, etc. 
BOUNDLY_API_PREFIX=v1

📂 paths

Where BOUNDLY's discovery engine scans for your code.

Key Default Description
domain base_path('Domain') Path scanned for #[Entity] attributes.
application base_path('Application') Path scanned for #[Action] attributes.

⚡ disable_cache

Controls whether the framework uses the static metadata cache.

Value Behavior
false (default in production) Reads from bootstrap/cache/boundly.php — zero overhead.
true (default in local) Scans and reflects on every request — always fresh. 
# Force disable cache during development
BOUNDLY_DISABLE_CACHE=true

⚠️ Note: Run php artisan core:cache before deploying to production. The cache is automatically disabled on APP_ENV=local.

🛡️ auth.default_guard

The Laravel auth guard used by the #[Authorize] middleware when no explicit guard is specified.

Default Description
'sanctum' Works with Laravel Sanctum tokens out of the box. 
BOUNDLY_AUTH_GUARD=api

📄 pagination

Controls the default page size for the generic CRUD list endpoint.

Key Default Description
default_per_page 15 Items returned when per_page is not specified.
max_per_page 100 Hard cap to prevent clients from requesting millions of rows. 
BOUNDLY_PER_PAGE=20
BOUNDLY_MAX_PER_PAGE=200

⚡ rate_limit

Controls API rate limiting to prevent abuse and ensure fair usage.

Key Default Description
enabled true Enable or disable rate limiting globally.
max_attempts 60 Maximum requests allowed per time window.
decay_minutes 1 Time window in minutes before attempts reset.
prefix 'api' Cache key prefix for rate limit counters. 
# Disable rate limiting (not recommended for production)
BOUNDLY_RATE_LIMIT_ENABLED=false

# Stricter limits for sensitive endpoints
BOUNDLY_RATE_LIMIT_MAX_ATTEMPTS=30
BOUNDLY_RATE_LIMIT_DECAY_MINUTES=1

Per-Entity Rate Limiting

You can also set rate limits directly on entities using the #[RateLimit] attribute:

#[Entity(table: 'payments')]
#[RateLimit(maxAttempts: 10, decayMinutes: 1)]
class Payment extends AggregateRoot { ... }

See Behavioral-Traits#rate-limit for more details.

🧱 Full Configuration Example

// config/boundly.php
return [
    'locale'        => env('BOUNDLY_LOCALE', 'en'),
    'api_prefix'    => env('BOUNDLY_API_PREFIX', 'api'),

    'paths' => [
        'domain'      => base_path('Domain'),
        'application' => base_path('Application'),
    ],

    'disable_cache' => env('BOUNDLY_DISABLE_CACHE', app()->environment('local')),

    'auth' => [
        'default_guard' => env('BOUNDLY_AUTH_GUARD', 'sanctum'),
    ],

    'pagination' => [
        'default_per_page' => env('BOUNDLY_PER_PAGE', 15),
        'max_per_page'     => env('BOUNDLY_MAX_PER_PAGE', 100),
    ],

    'rate_limit' => [
        'enabled'       => env('BOUNDLY_RATE_LIMIT_ENABLED', true),
        'max_attempts'  => env('BOUNDLY_RATE_LIMIT_MAX_ATTEMPTS', 60),
        'decay_minutes' => env('BOUNDLY_RATE_LIMIT_DECAY_MINUTES', 1),
        'prefix'        => env('BOUNDLY_RATE_LIMIT_PREFIX', 'api'),
    ],

    // v0.9.0 Production Features
    'health' => [
        'enabled' => true,
        'timeout' => 5,
        'services' => [
            'database' => true,
            'cache' => true,
            'queue' => true,
            'storage' => true,
        ],
        'custom' => [],
    ],

    'logging' => [
        'version' => '1.0.0',
        'channel' => 'single',
        'request_logger' => [
            'enabled' => true,
            'channel' => 'single',
            'exclude_paths' => ['health', 'up'],
        ],
        'audit' => [
            'enabled' => true,
            'channel' => 'single',
            'events' => ['created', 'updated', 'deleted', 'accessed'],
        ],
    ],

    'database_timeouts' => [
        'default' => 30,
        'operations' => [
            'select' => 30,
            'insert' => 30,
            'update' => 30,
            'delete' => 30,
            'bulk' => 60,
            'migration' => 300,
        ],
    ],

    'cache' => [
        'response' => [
            'enabled' => false,
            'store' => 'file',
            'ttl' => 60,
            'exclude_paths' => ['api/health', 'api/*/health'],
        ],
    ],

    'ip_access' => [
        'enabled' => false,
        'default_action' => 'deny',
        'whitelist' => [],
        'blacklist' => [],
        'cache_store' => 'file',
    ],

    'security' => [
        'request_signing' => [
            'enabled' => false,
            'algorithm' => 'sha256',
            'secret_key' => env('REQUEST_SIGNING_SECRET', ''),
            'timestamp_tolerance' => 300,
        ],
        'tier_throttling' => [
            'enabled' => true,
            'cache_store' => 'file',
            'tiers' => [
                'free' => ['requests_per_minute' => 60, 'requests_per_hour' => 1000, 'requests_per_day' => 10000],
                'basic' => ['requests_per_minute' => 300, 'requests_per_hour' => 5000, 'requests_per_day' => 50000],
                'pro' => ['requests_per_minute' => 1000, 'requests_per_hour' => 20000, 'requests_per_day' => 200000],
                'enterprise' => ['requests_per_minute' => 5000, 'requests_per_hour' => 100000, 'requests_per_day' => 1000000],
            ],
        ],
    ],
];

🏥 Health Checks (v0.9.0)

Configure health check behavior for monitoring and orchestration.

Key Default Description
enabled true Enable/disable health checks
timeout 5 Timeout in seconds per check
services.database true Check database connectivity
services.cache true Check cache connectivity
services.queue true Check queue worker connectivity
services.storage true Check storage connectivity

📝 Logging (v0.9.0)

Configure structured logging and audit trail.

Key Default Description
logging.version '1.0.0' Log format version
logging.channel 'single' Log channel
logging.request_logger.enabled true Log HTTP requests
logging.audit.enabled true Enable audit logging
logging.audit.events ['created', 'updated', 'deleted', 'accessed'] Audited events

⏱️ Database Timeouts (v0.9.0)

Configure query timeouts per operation type.

Key Default Description
database_timeouts.default 30 Default timeout in seconds
database_timeouts.operations.select 30 SELECT query timeout
database_timeouts.operations.insert 30 INSERT query timeout
database_timeouts.operations.update 30 UPDATE query timeout
database_timeouts.operations.delete 30 DELETE query timeout
database_timeouts.operations.bulk 60 Bulk operations timeout
database_timeouts.operations.migration 300 Migration timeout

🚀 Response Cache (v0.9.0)

Configure API response caching for improved performance.

Key Default Description
cache.response.enabled false Enable response caching
cache.response.store 'file' Cache store driver
cache.response.ttl 60 Cache TTL in minutes
cache.response.exclude_paths ['api/health', ...] Paths to exclude

🌐 IP Access Control (v0.9.0)

Configure IP-based access restrictions.

Key Default Description
ip_access.enabled false Enable IP restrictions
ip_access.default_action 'deny' Default action when no match
ip_access.whitelist [] Allowed IPs (supports CIDR/wildcard)
ip_access.blacklist [] Blocked IPs

🔏 Request Signing (v0.9.0)

Configure HMAC request signature verification.

Key Default Description
security.request_signing.enabled false Enable signature verification
security.request_signing.algorithm 'sha256' Hash algorithm
security.request_signing.secret_key env Signing secret
security.request_signing.timestamp_tolerance 300 Timestamp window in seconds

📊 Tier Throttling (v0.9.0)

Configure multi-tier rate limiting.

Key Description
security.tier_throttling.enabled Enable tier-based limits
security.tier_throttling.tiers.free Free tier limits
security.tier_throttling.tiers.basic Basic tier limits
security.tier_throttling.tiers.pro Pro tier limits
security.tier_throttling.tiers.enterprise Enterprise tier limits

🧪 Usage Tips

  1. Environment Aware: All keys support env() — use .env to separate local, staging, and production configs.
  2. CLI Override: --lang in any core:* command takes precedence over locale.
  3. Publish Config: Run php artisan vendor:publish --tag=boundly-config to copy the default config to config/boundly.php.

Next Step: Roadmap 🚀

Clone this wiki locally