jooservices/laravel-config

MongoDB-backed typed application configuration for Laravel, with optional cache and Artisan operator commands.

Package: jooservices/laravel-config

v4.0.0 includes breaking changes from 1.x. See UPGRADE-4.0.md.

Current release: 4.0.0 · Laravel 12/13 · PHP 8.5+

Install

composer require jooservices/laravel-config:^4.0

Publish configuration:

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

Requirements

• PHP 8.5+
• Laravel 12 or 13 only (Laravel 11 dropped)
• MongoDB via mongodb/laravel-mongodb ^5.7
• 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
• typed normalization: string, int, float, bool, array, json, null, and encrypted (Laravel Crypt) for secrets
• nested paths: first segment = group, remainder = key (dots allowed in key), e.g. mail.smtp.host
• runtime get, typed getters, set, setMany, forget, forgetMany, clear, remember, listOrdered (normalized), group, all, refresh, and fresh
• Artisan commands including import --dry-run / --force and CLI --reveal-secrets
• Config::fake() for consumer-app tests without MongoDB

Prefer JOOservices\LaravelConfig\Facades\Config or the ConfigStore alias — do not bind this package as Laravel’s native Config.

Quick example

use JOOservices\LaravelConfig\Facades\Config;

Config::set('system.site_name', 'XCrawler');
Config::set('system.enabled', true);
Config::set('payment.retry_times', 3);
Config::set('mail.smtp.host', 'smtp.example.com');

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

Path format

group.key… — first segment is the group; the rest (with dots) is the key.

• valid: system.site_name, mail.smtp.host
• invalid: system, .system.site_name, system., system..site_name

Cache and memory behavior

• get, has, group, and all load from memory first
• cold memory reads the cached full map, then MongoDB on miss
• mutations update MongoDB, bump a shared cache version stamp, and refresh the process map; setMany / bulk import bump once per batch
• refresh clears memory + cache key and reloads from MongoDB
• fresh bypasses memory and cache for a direct MongoDB read

Limitations: process-local memory can go stale in long-lived workers; treat the shared cache as a trusted boundary; keep collections config-sized.

MongoDB index

php artisan config-store:ensure-index

Unique compound index on group + key.

Artisan commands

php artisan config-store:get system.site_name --default="Default"
php artisan config-store:get system.secret --reveal-secrets
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 --with-types
php artisan config-store:doctor
php artisan config-store:export storage/config-store.json --reveal-secrets
php artisan config-store:import storage/config-store.json --dry-run
php artisan config-store:import storage/config-store.json --merge
php artisan config-store:import storage/config-store.json --force
php artisan config-store:refresh
php artisan config-store:ensure-index

Import: use --dry-run to preview. Replace without merge requires --force. Export/list/get redact encrypted values unless --reveal-secrets.

Security note

Use ConfigType::Encrypted for secrets. ConfigChanged does not embed plaintext for encrypted values. Access control for MongoDB, backups, and the cache store remain application responsibilities.

Documentation

• Documentation Hub
• Upgrade to 4.0
• Installation
• Quick Start
• Usage Guide
• Risks, Legacy, and Gaps
• Repo audit vs dto
• Changelog

Development

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

MongoDB is required for integration tests.

Community

• Contributing
• Security Policy
• License