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:

• Documentation Hub
• Installation
• Quick Start
• Configuration
• Usage Guide
• Release Process
• Risks, Legacy, and Gaps
• Changelog

AI support

This repository includes AI contributor guidance and skill files.

Start with:

• AGENTS.md
• CLAUDE.md
• AI Skills Map
• AI Skills Usage Guide

Development

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

MongoDB must be available for integration tests.

Community

• Contributing
• Security Policy
• License