Configuration

Overview

Configuration in ValPress is handled through a tiered approach that combines Laravel’s environment-based settings with CMS-specific configuration files and a user-friendly Admin Dashboard. This multi-layered system allows for both developer-level control over infrastructure and user-level control over site-wide behavior without touching code.

Why It Matters

  • Security: Sensitive credentials (database, API keys) are kept out of version control via .env files.
  • Flexibility: Environment-specific settings allow the same codebase to run differently on local, staging, and production servers.
  • User Experience: The Admin Dashboard empowers non-technical users to manage site titles, regional settings, and content behavior.
  • Extensibility: Developers can define custom post types, roles, and media sizes in configuration files to tailor the CMS to specific project needs.

How It Works

ValPress relies on three primary configuration layers:

  1. Environment Variables (.env): The foundation for infrastructure-level settings (DB connections, mail servers, app keys). These are loaded into PHP's $_ENV superglobal.
  2. *Configuration Files (`config/.php`)**: Laravel-style PHP arrays that consume environment variables and define structured settings.
    • config/app.php: Core Laravel settings (timezone, locale, encryption).
    • config/valpress.php: CMS-specific definitions (post types, roles, media sizes).
  3. Database Settings (options table): Persistent settings managed through the Admin Dashboard. These are typically accessed via the get_option() helper and override or complement static configurations.

Usage

1) Environment Configuration

Always start by configuring your .env file. This file is unique to each installation and should never be committed to your repository.

# Generate a new application key
php artisan key:generate

# Clear the configuration cache after manual .env changes
php artisan config:clear

2) Core CMS Configuration (config/valpress.php)

This file contains the structural definitions for your ValPress site. Key areas include:

  • Post Types: Define the labels and capabilities for content types like post and page.
  • Roles & Permissions: Manage the hierarchy of user roles and what each can perform.
  • Media Sizes: Configure the dimensions for automatically generated image thumbnails.

3) Admin Settings Dashboard

Navigate to Settings in the ValPress Admin sidebar to manage high-level site behavior:

  • General: Site title, tagline, and regional settings (Timezone, Date Format).
  • Writing: Default post categories and the ability to enable/disable specific Custom Post Types.
  • Reading: Control what is displayed on the front page (a static page vs. the latest posts) and search engine visibility.
  • Media: Set maximum upload sizes and default dimensions for the media library.
  • Membership: Enable user registration and set the default role for new users.

4) Localization

ValPress uses Laravel’s translation system. To change the site language:

  1. Set APP_LOCALE in your .env.
  2. Ensure the corresponding language files exist in lang/ (or resources/lang/ in older versions).
  3. For plugins/themes, use __() or @lang to ensure strings are translatable.

Code Examples

Example 1 — Customizing config/valpress.php

Adding a new custom post type and a custom user role directly in the configuration file.

<?php // config/valpress.php

return [
    // ... existing configuration

    'post_types' => [
        'post' => [ /* ... default post config ... */ ],
        'page' => [ /* ... default page config ... */ ],

        // Registering a custom 'Product' post type
        'product' => [
            'labels' => [
                'name' => 'Products',
                'singular_name' => 'Product',
            ],
            'public' => true,
            'has_archive' => true,
            'menu_order' => 10,
            'menu_icon' => 'bi-cart',
            'supports' => ['title', 'editor', 'thumbnail', 'excerpt', 'price'],
            'is_core' => false,
        ],
    ],

    'roles' => [
        'administrator' => [ /* ... */ ],
        'editor' => [ /* ... */ ],

        // Adding a 'Store Manager' role with specific permissions
        'store_manager' => [
            'name' => 'Store Manager',
            'permissions' => [
                'edit_posts',
                'publish_posts',
                'manage_products', // Custom permission
                'upload_files',
            ],
        ],
    ],

    'media' => [
        'sizes' => [
            'thumbnail' => ['width' => 150, 'height' => 150, 'crop' => true],
            'medium' => ['width' => 300, 'height' => null, 'crop' => false],
            'large' => ['width' => 1024, 'height' => null, 'crop' => false],

            // Custom size for hero banners
            'hero' => [
                'width' => 1920,
                'height' => 600,
                'crop' => true,
            ],
        ],
    ],
];

Example 2 — Accessing Settings via Helper Functions

How to retrieve settings in your controllers or Blade templates.

// In a Controller: Get the site title from the options table
$siteTitle = get_option('site_title', 'Default ValPress Site');

// In a Blade Template: Check if registration is allowed
@if(get_option('users_can_register'))
    <a href="{{ route('register') }}">Join our community!</a>
@endif

// Accessing static config values
$thumbnailWidth = config('valpress.media.sizes.thumbnail.width');

Advanced Usage

Dynamic Configuration via Plugins

Plugins can hook into the configuration process to register settings or modify existing ones at runtime.

// In a plugin.php file
add_filter('valpress_all_post_types', function ($post_types) {
    $post_types['event'] = [
        'labels' => ['name' => 'Events', 'singular_name' => 'Event'],
        'public' => true,
        // ... other settings
    ];
    return $post_types;
});

Environment-Specific Config Overrides

For complex setups, you can use APP_ENV to load specific configuration logic. While Laravel doesn't natively support config/production/app.php anymore, you can achieve this in your service providers:

public function boot()
{
    if ($this->app->environment('production')) {
        config(['app.debug' => false]);
    }
}

Best Practices

  • Never commit .env: Always include .env in your .gitignore.
  • Use env() only in config files: Avoid calling env() directly in your application logic; use the config() helper instead. This allows for configuration caching.
  • Cache for Production: Always run php artisan config:cache on production servers to boost performance.
  • Default Values: Always provide a sensible default value when using config() or get_option().
  • Type Safety: Cast values retrieved from environment variables (e.g., (bool) env('APP_DEBUG')) to ensure they behave as expected in PHP.

Common Mistakes

  • *Directly modifying `config/.phpfor site-specific data**: Use the Admin Dashboard or.env` for things that change between environments or users.
  • Forgetting to clear cache: If you change a .env file and don't see the change, it’s likely because the configuration is cached. Run php artisan config:clear.
  • Hardcoding sensitive data: Never put passwords or API keys directly in config/valpress.php. Use env().
  • Namespace Collisions: When adding custom keys to config/valpress.php, prefix them if you are developing a public plugin to avoid conflicts with core updates.

Summary

ValPress configuration is a robust blend of Laravel's environment management and CMS-specific settings. By utilizing .env for infrastructure, config/valpress.php for structural definitions, and the Admin Dashboard for site-wide preferences, you create a secure, flexible, and user-friendly environment. Remember to always cache your configuration in production and keep your secrets safe.