How to add custom config file to app/config in Laravel 5?

How to add custom config file to app/config in Laravel 5?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Loading Custom Configuration in Laravel 5's app/config

Laravel 5 introduced a significant architectural shift regarding configuration management by moving the default configuration files from the app/config directory to the package-specific config folder within vendor directories. While this centralized approach keeps third-party settings out of your main codebase, it often leaves developers wondering how to inject their own custom configuration files directly into that legacy location without breaking the framework's bootstrapping logic.

To add a file named custom_config.php to the app/config directory in Laravel 5, you cannot simply drop the file there and expect it to be loaded automatically. The framework does not iterate over every .php file in that directory during the boot process. Instead, it relies on a specific whitelist of configuration files defined in the config/config.php manifest.

If you attempt to add your custom file without registering it, Laravel will ignore it entirely, resulting in configuration values being inaccessible via the Config::get() helper or environment variables. The core mechanism for this behavior lives in the Illuminate\Foundation\Bootstrap\LoadConfigurationVariables class and is controlled by the $files array found in app/config/config.php.

To implement your custom configuration, you must first locate the config.php file within your app/config directory. Inside this file, you will find an associative array where keys correspond to configuration file names (without the .php extension) and values define their relative paths. You need to add an entry for your new file here:

'files' => [
    // Existing standard configs are loaded from vendor packages...
    
    'custom_config' => config_path('custom_config.php'),
],

In this example, the key 'custom_config' tells Laravel what name to use when accessing the configuration values. The value must point to the absolute path of your new file using the config_path() helper function. This ensures that regardless of where your application root is located, Laravel can find the file correctly.

Once you have appended this entry to the manifest, you can create the custom_config.php file in the same app/config directory. Inside this file, you define your configuration keys using an array structure:

<?php

return [
    'api_key' => env('API_KEY', 'default-key'),
    'service_url' => 'https://internal.example.com',
];

You can then access these values anywhere in your application using Config::get('custom_config.api_key') or via dependency injection.

It is crucial to understand the trade-offs of this approach. Because you are manually editing the config/config.php manifest, any deployment script that resets your configuration directory to a clean state will remove your custom entry unless it is part of a version-controlled migration or explicitly preserved in your git history. Furthermore, if you are upgrading Laravel versions, changes to the bootstrap sequence could potentially alter how these files are loaded, though the files array mechanism has remained stable since Laravel 5.

A common pitfall occurs when developers try to access configuration values before the config system is fully initialized, such as in early bootstrapping scripts that run outside of the standard controller or service context. Always ensure your custom configuration relies on environment variables for sensitive data rather than hardcoding secrets directly into the file.

If you prefer a more decoupled approach where your configuration logic lives entirely separate from the framework's internal manifest, consider defining your settings in a dedicated directory and loading them manually within a Service Provider's boot() method. This offers greater flexibility but requires explicitly calling Config::set() for every key you wish to inject, which can become verbose quickly. Sticking to the files array in app/config/config.php remains the most Laravel-native way to achieve true declarative configuration loading in version 5.

Our network