README

The JOOservices Laravel Config package stores Laravel application configuration in MongoDB and exposes typed runtime access through JOOservices\\LaravelConfig\\Facades\\Config.

Package name: jooservices/laravel-config

Install

composer require jooservices/laravel-config

Publish configuration:

php artisan vendor:publish --tag=config-store-config

Requirements

PHP 8.5+
Laravel 12 or 13 (CI-verified)
Laravel 11 (constraint-compatible; not CI-verified due to testbench audit constraints)
MongoDB via mongodb/laravel-mongodb ^5.4
MongoDB PHP extension

What the package does

stores values as group, key, value, and type documents in MongoDB
loads a full in-memory map on first read and optionally caches that map
supports typed normalization for string, int, float, bool, array, json, and null
provides runtime get, typed getters, set, forget, remember, group, all, refresh, and fresh operations
ships Artisan commands for common operator tasks
provides Config::fake() for consumer-app tests without MongoDB

Quick example

use JOOservices\LaravelConfig\Facades\Config;

Config::set('system.site_name', 'XCrawler');
Config::set('system.enabled', true);
Config::set('payment.retry_times', 3);

$siteName = Config::get('system.site_name');
$system = Config::group('system');
$fresh = Config::fresh('system.site_name');

Path format and validation

Paths must use the group.key format.

Rejected values include:

empty paths
missing dots
leading dots
trailing dots
double dots
empty group or empty key segments

Examples:

valid: system.site_name
valid: payment.retry_times
invalid: system
invalid: .system.site_name
invalid: system.
invalid: system..site_name

Cache and memory behavior

get, has, group, and all load from memory first
when memory is cold, the service reads the cached full map first, then MongoDB on cache miss
set and forget update MongoDB, bump a shared cache version stamp, and refresh the cached full map within the current process
when a loaded process detects a newer cache version stamp, it reloads from cache or MongoDB before serving reads
refresh clears in-memory state and the configured cache key, then reloads from MongoDB
fresh bypasses the in-memory map and cache for a direct MongoDB read
stored null is returned as null; caller defaults are not applied when the key exists with a null value
bool normalization uses PHP filter_var(..., FILTER_VALIDATE_BOOLEAN) semantics

Important limitations:

the in-memory map is process-local, so long-running workers can hold stale in-memory state until refresh() is called or the process is recycled
each mutation rewrites the full cached map; keep collections config-sized (hundreds of keys, not thousands)
use a dedicated cache store/prefix in production; treat the shared cache as a trusted boundary

MongoDB index requirement

Create a unique compound index on group and key so each config path remains unique.

php artisan config-store:ensure-index

Equivalent Mongo shell command:

db.configs.createIndex(
  { group: 1, key: 1 },
  { name: 'config_group_key_unique', unique: true }
);

Artisan commands

php artisan config-store:get system.site_name --default="Default"
php artisan config-store:set system.site_name XCrawler
php artisan config-store:set system.enabled true --type=bool
php artisan config-store:forget system.site_name
php artisan config-store:list system --json
php artisan config-store:doctor
php artisan config-store:export storage/config-store.json
php artisan config-store:import storage/config-store.json --merge
php artisan config-store:refresh
php artisan config-store:ensure-index

Security note

This package can store sensitive values, but it does not encrypt stored values by default. Do not place credentials or secrets in this store unless your MongoDB deployment, backups, and access controls already satisfy your security requirements.

Upgrade note

The canonical namespace for this package is now JOOservices\\LaravelConfig\\. Existing code that imports JooServices\\LaravelConfig\\... must be updated. This repository does not currently ship a compatibility alias layer.

Documentation

Start with:

AI support

This repository includes AI contributor guidance and skill files.

Start with:

Development

composer lint
composer lint:all
composer test
composer test:coverage
composer check
composer ci

MongoDB must be available for integration tests.

jooservices / laravel-config

Maintainers

Package info

Statistics

Security