Troubleshooting & FAQ

Overview

Even the most robust systems encounter issues during development or deployment. Troubleshooting in ValPress is the systematic process of identifying, analyzing, and resolving technical hurdles, ranging from environment misconfigurations to plugin conflicts. This section provides a guide to diagnosing common errors and answers frequently asked questions about the CMS.

Why It Matters

A smooth developer experience depends on the ability to quickly recover from errors. Effective troubleshooting:

  • Reduces Downtime: Swiftly identifying the root cause of a "White Screen of Death" prevents prolonged site outages.
  • Ensures Data Integrity: Proper database connection troubleshooting prevents data loss or corruption.
  • Empowers Developers: Understanding how to use Laravel's debugging tools within the ValPress context allows for faster feature iteration and bug fixing.

How It Works

ValPress leverages the underlying Laravel exception handling and logging systems.

  • Logging: All errors are recorded in storage/logs/laravel.log (or your configured log driver).
  • Exception Handler: The app/Exceptions/Handler.php (if customized) or the core Laravel handler manages how errors are presented to the user based on the environment.
  • Debug Mode: Controlled by the APP_DEBUG environment variable, it determines whether detailed stack traces are shown in the browser.
  • Caching: Many "phantom" issues in ValPress are caused by stale configuration, route, or view caches, which the CMS uses heavily for performance.

Usage

Enabling Debug Mode

During development, always ensure APP_DEBUG is set to true in your .env file to see descriptive error messages.

# .env file
APP_ENV=local
APP_DEBUG=true

Clearing Caches

When changes to config/valpress.php or new routes don't seem to take effect, clear the application cache:

php artisan optimize:clear

Checking Logs

If you encounter a generic "500 Internal Server Error" on production, inspect the latest log entries:

tail -n 100 storage/logs/laravel.log

Code Examples

Custom Error Logging in Plugins

When building plugins, use the Laravel Log facade to record troubleshooting information without interrupting the user flow.

use Illuminate\Support\Facades\Log;

add_action('valpress_init', function () {
    try {
        // Attempt a complex operation
        $result = ExternalService::connect();
    } catch (\Exception $e) {
        // Log the error with context for easier debugging
        Log::error('Plugin Name: Failed to connect to External Service', [
            'message' => $e->getMessage(),
            'trace' => $e->getTraceAsString(),
        ]);

        // Optionally show a non-breaking admin notice
        add_action('admin_notices', function() {
            echo '<div class="alert alert-danger">External Service connection failed. Check logs.</div>';
        });
    }
});

Handling 404s on Custom Post Types

A common issue is 404 errors after registering a new CPT. This usually happens because the route cache is stale or the permalink structure hasn't been refreshed.

// In your plugin.php or functions.php
add_action('valpress_init', function () {
    register_post_type('portfolio', [
        'public' => true,
        'has_archive' => true,
        'rewrite' => ['slug' => 'portfolio'],
    ]);

    // Protip: Only flush during activation, not on every request!
});

// Correct way: Flush on plugin activation
register_activation_hook('my-plugin-slug', function() {
    // ValPress handles route clearing automatically when plugins are toggled,
    // but manually you can run:
    \Illuminate\Support\Facades\Artisan::call('route:cache');
});

Advanced Usage

Profiling with Laravel Telescope

For deep architectural debugging, ValPress is fully compatible with Laravel Telescope. Install it via composer to monitor requests, exceptions, database queries, and mail.

composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate

Debugging Hooks

If a filter isn't modifying data as expected, you can debug the hook stack. Since ValPress uses a custom PluginManager, you can inspect registered callbacks:

// Debugging a specific filter in a template or controller
$value = apply_filters('the_content', $original_content);

if (config('app.debug')) {
    // Use dd() to inspect why the content isn't what you expect
    // dd($value); 
}

Best Practices

  • Environment Isolation: Never set APP_DEBUG=true on a production server; it exposes sensitive environment variables and path information.
  • Contextual Logging: Always include relevant metadata (user ID, input data) when logging errors in your plugins or themes.
  • Graceful Degradation: Use try-catch blocks in your functions.php to prevent a single failing hook from bringing down the entire site (WSOD).
  • Verify Permissions: Ensure storage and bootstrap/cache directories are writable by the web server (usually www-data or nginx).

Common Mistakes

The White Screen of Death (WSOD)

  • Cause: Usually a fatal PHP error (syntax error, missing class) while APP_DEBUG is false.
  • Fix: Check storage/logs/laravel.log immediately. If the log is empty, check the web server error logs (e.g., /var/log/nginx/error.log).

"Database Connection Refused"

  • Cause: Incorrect credentials in .env or the database service is down.
  • Fix: Verify DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, and DB_PASSWORD. If using Docker, ensure the database container is in the same network as the application.

Styles and Scripts Not Loading

  • Cause: Incorrectly hardcoded URLs or failing to use ScriptManager.
  • Fix: Always use asset() or valpress_get_theme_asset_url() to generate paths. Check the browser console for 404 errors or mixed content (HTTP vs HTTPS) warnings.

Update Center failures

  • Cause: Verification or apply failed during a core, plugin, or theme update.
  • Fix:
    1. Open Admin > Updates and read the structured stage report for the failing step.
    2. Use repair action buttons when offered (cache clear, storage:link, plugin migrations). See Repair Actions.
    3. For core apply failures, restore from a snapshot in the Update Center if available.
    4. Ensure a dedicated test database is configured under Settings → Test Database before running verify. See Testing.
    5. If an active plugin or theme blocks core verify, fix the reported validation issue or run suggested repairs. See Plugin Update Validation.
    6. Export the report JSON (GET /admin/updates/export-report) for support or staging reproduction.

Summary

Troubleshooting in ValPress is built upon standard Laravel patterns. By utilizing APP_DEBUG during development, monitoring laravel.log, and keeping caches clear, you can resolve the majority of common configuration and code errors. Always remember to decouple your code using hooks and handle exceptions gracefully to maintain a stable environment for your users.