Osumi Framework
es en eu v9.8.0 GitHub

Configuration

The Osumi Framework configuration is managed through JSON files located in src/Config/. These settings control the application's behavior, database connections, environment-specific variables, and more.

Configuration Files

The framework follows a hierarchical loading pattern:

  1. Config.json: The main configuration file with default values.
  2. Config_{environment}.json: Optional environment-specific file (e.g., Config_prod.json) that overrides values from the main file.

Core Configuration Blocks

Application Settings

Global parameters for the application's basic behavior.

{
	"name": "My Awesome App",
	"lang": "en",
	"use-session": true,
	"allow-cross-origin": true,
	"base_url": "https://example.com",
	"css_list": [],
	"js_list": [],
	"head_elements": []
}

Database (db)

Configuration for the PDO connection.

{
	"db": {
		"driver": "mysql",
		"host": "localhost",
		"user": "root",
		"pass": "secret",
		"name": "my_database",
		"charset": "utf8mb4",
		"collate": "utf8mb4_unicode_ci"
	}
}

Logging (log)

Settings for application logs.

{
	"log_level": "DEBUG",
	"log": {
		"name": "app_log",
		"max_file_size": 50,
		"max_num_files": 3
	}
}

Custom Directories (dir)

You can define custom paths using placeholders from existing directories.

{
	"dir": {
		"uploads": "{{base}}public/uploads/",
		"exports": "{{ofw_export}}my_reports/"
	}
}

Extra Settings (extra)

A key-value store for any custom data your application needs (API keys, secrets, etc.).

{
	"extra": {
		"api_key": "12345-abcde",
		"items_per_page": 20
	}
}

Assets and head elements

The css_list and js_list entries accept arrays of strings. Each string is interpreted as a file name that must live under the application's public directory.

The head_elements option accepts an array of objects to inject arbitrary elements into the document <head> using a simple structure.

Example:

{
	"head_elements": [
		{
			"item": "meta",
			"attributes": { "name": "theme-color", "content": "#000" }
		},
		{
			"item": "link",
			"attributes": {
				"rel": "icon",
				"href": "/fav.svg",
				"type": "image/svg+xml"
			}
		},
		{
			"item": "script",
			"attributes": {
				"src": "https://cdn.example.com/lib.js",
				"async": true
			}
		}
	]
}

Each head_elements entry must be an object with item (tag name) and attributes (an object of key/value pairs). Scripts will be rendered with an explicit closing tag (<script></script>); other tags are self-closed.

Accessing Configuration in Code

The OConfig object is typically available within the framework's core classes (like Components or Tasks).

// Example: Accessing an "extra" value
$apiKey = $this->getConfig()->getExtra('api_key');

// Example: Accessing a directory path
$uploadPath = $this->getConfig()->getDir('uploads');

// Example: Accessing DB info
$dbName = $this->getConfig()->getDB('name');

Overriding values

When a key is present on the Config.json file, but there is also defined on the environment specific file, the latest is applied. Selected environment is defined by using the env key:

  // Config.json file
  {
	"log_level": "DEBUG",
	"env": "prod"
  }

  // Config_prod.json file
  {
	"log_level": "ERROR"
  }

In this case "ERROR" would be the value for log_level because the key is defined as a key on the global file and the environment specific one.

Application paths

When the application is loaded, a set of default paths are loaded on OConfig:

Key Path Description
base / Applications base path
app /src/ User code
app_component /src/Component/ Reusable components
app_config /src/Config/ Configuration files
app_dto /src/DTO/ DTOs used on actions
app_filter /src/Filter/ Filters used on actions
app_layout /src/Layout/ Reusable layouts
app_mode /src/Model/ Database model files
app_routes /src/Routes/ User defined URLs
app_service /src/Service/ Reusable service files
app_task /src/Task/ User defined tasks for the CLI
app_utils /src/Utils/ Generic utils classes
ofw /ofw/ Location of application generated files (logs, exports...)
ofw_cache /ofw/cache/ Path of application cache files
ofw_export /ofw/export/ Path of exported files (as model.sql)
ofw_tmp /ofw/tmp/ Path of tmp files
ofw_logs /ofw/logs/ Path of generated log files
ofw_base /vendor/osumionline/framework/ Base path of framework
ofw_vendor /vendor/osumionline/framework/src/ Framework code
ofw_assets /vendor/osumionline/framework/src/Assets/ Framework assets (locales, templates)
ofw_locale /vendor/osumionline/framework/src/Assets/locale/ Framerowk locale files (en, es, eu)
ofw_template /vendor/osumionline/framework/src/Assets/template/ Framework templates for generating new files
ofw_task /vendor/osumionline/framework/src/Task/ Framework CLI tasks
ofw_tools /vendor/osumionline/framework/src/Tools/ Framework internal tools
public /public/ DocumentRoot of the application

Summary of Configuration Keys

Key Type Description
name String Application name.
lang String Default language (e.g., "en", "es").
use-session Boolean Whether to enable native PHP sessions.
db Object Database connection details.
dir Object Custom directory definitions.
extra Object Custom key-value pairs.
error_pages Object Custom URLs for 403, 404, or 500 errors.
css_list Array List of CSS files to include.
js_list Array List of JavaScript files to include.
head_elements Array List of HTML head elements to inject (meta, link, script).
libs Array List of third-party libraries to load.

Best Practices

llms osumi-framework-llm.md Markdown version