Primordyx Framework Documentation

Ini
in package

Class Ini

A lightweight INI file handler with read/write support, default sectioning, and an optional safe-save capability that preserves comment lines when possible.

Tags
since
1.0.0

Table of Contents

Properties

$contents  : array<string|int, mixed>|null
$defaultSection  : string
$filename  : string
$readOnly  : bool

Methods

__construct()  : mixed
Ini constructor.
all()  : array<string|int, mixed>
Alias of dump().
bool()  : bool
Returns the boolean interpretation of a key's value.
clear()  : void
Clears all contents.
delete()  : string
Deletes a key from the contents.
deleteSection()  : array<string|int, mixed>
Deletes an entire section from the contents.
dump()  : array<string|int, mixed>
Returns the raw contents array.
filename()  : string
Returns the currently loaded filename.
get()  : mixed
Gets a value from the INI content.
getArray()  : array<int, string>
Get a config value as an array (comma-separated).
getBool()  : bool
Get a config value as a boolean.
getDefaultSection()  : string
Returns the current default section.
getEnum()  : string
Get a config value that must match one of the allowed options.
getFloat()  : float
Get a config value as a float.
getInt()  : int
Get a config value as an integer.
getJsonArray()  : array<string|int, mixed>
Get a config value as a JSON-decoded array.
getSection()  : array<string|int, mixed>
Gets all key-value pairs from a section.
has()  : bool
Checks if a key exists in the given section.
loadFromFile()  : void
Loads content from an INI file or creates a stub file if it doesn't exist. This DOES NOT change the filename that future calls to save functions will do. This gives you the ability to copy from an existing file
lock()  : void
Locks the INI handler to prevent write operations.
reload()  : void
Resets and reloads the INI file from the disk.
reset()  : void
Resets readOnly status and clears all contents.
safeSave()  : void
Safely writes contents to the file, preserving existing structure and comments where possible by modifying in-place.
saveToFile()  : bool|int
Saves the current INI contents to the file.
set()  : string
Sets a value in the INI content.
setDefaultSection()  : string
Sets the default section to use when none is provided.
toJson()  : string
Converts the entire contents array to a JSON string.
unlock()  : void
Unlocks the INI handler to allow your write operations.

Properties

$contents

protected array<string|int, mixed>|null $contents = []

$defaultSection

protected string $defaultSection

$filename

protected string $filename

$readOnly

protected bool $readOnly = false

Methods

__construct()

Ini constructor.

public __construct(string $filename, string $defaultSection[, bool $readOnly = false ]) : mixed

Initializes the INI handler using the given filename and section.

Parameters
$filename : string

The INI file path.

$defaultSection : string

The default section name to use.

$readOnly : bool = false

Whether to open in read-only mode.

all()

Alias of dump().

public all() : array<string|int, mixed>
Return values
array<string|int, mixed>

bool()

Returns the boolean interpretation of a key's value.

public bool(string $key[, string $section = '' ]) : bool
Parameters
$key : string
$section : string = ''
Return values
bool

clear()

Clears all contents.

public clear() : void

delete()

Deletes a key from the contents.

public delete(string $key[, string $section = '' ]) : string
Parameters
$key : string
$section : string = ''
Return values
string —

The original value before deletion.

deleteSection()

Deletes an entire section from the contents.

public deleteSection(string $section) : array<string|int, mixed>
Parameters
$section : string
Return values
array<string|int, mixed> —

The original contents of the deleted section.

dump()

Returns the raw contents array.

public dump() : array<string|int, mixed>
Return values
array<string|int, mixed>

filename()

Returns the currently loaded filename.

public filename() : string
Return values
string

get()

Gets a value from the INI content.

public get(string $key[, string $section = '' ][, string $default = 'undefined' ]) : mixed

Returns the raw value from parse_ini_file(), which may be a string, int, float, or bool, depending on whether the original value was quoted or unquoted. If the key is not found, returns the string 'undefined' for consistency with older behavior.

Parameters
$key : string
$section : string = ''

Optional section to look in

$default : string = 'undefined'

optional default value

Return values
mixed —

The raw value or 'undefined' if the key is missing

getArray()

Get a config value as an array (comma-separated).

public getArray(string $key[, string $section = '' ][, string $separator = ',' ]) : array<int, string>

Useful for values like: "one,two,three" Will trim whitespace and ignore empty segments. Returns an empty array if the key is missing or empty.

Note: parse_ini_file() may return raw strings even for lists, so this method does the right thing regardless of quoting.

Parameters
$key : string
$section : string = ''

Optional section to look in

$separator : string = ','

Delimiter to split on (default: comma)

Return values
array<int, string>

getBool()

Get a config value as a boolean.

public getBool(string $key[, string $section = '' ][, bool $default = false ]) : bool

Supports native booleans or common truthy/falsy strings like "true", "false", "on", "off", etc. Quoted values in the INI will be strings and need parsing. Unquoted values may be real booleans.

Parameters
$key : string
$section : string = ''

Optional section to look in

$default : bool = false

Fallback value if key is missing or unrecognized

Return values
bool

getDefaultSection()

Returns the current default section.

public getDefaultSection() : string
Return values
string

getEnum()

Get a config value that must match one of the allowed options.

public getEnum(string $key[, string $section = '' ][, array<string|int, mixed> $allowed = [] ][, string $default = '' ]) : string

Helps validate "enum-style" settings where only specific values are valid.

Parameters
$key : string
$section : string = ''

Optional section to look in

$allowed : array<string|int, mixed> = []

List of allowed values

$default : string = ''

Fallback if not present or invalid

Return values
string

getFloat()

Get a config value as a float.

public getFloat(string $key[, string $section = '' ][, float $default = 0.0 ]) : float

Like getInt(), this ensures type safety since parse_ini_file() returns strings for quoted numbers.

Parameters
$key : string
$section : string = ''

Optional section to look in

$default : float = 0.0

Fallback if value is missing or invalid

Return values
float

getInt()

Get a config value as an integer.

public getInt(string $key[, string $section = '' ][, int $default = 0 ]) : int

parse_ini_file() might return strings if the value was quoted, so this explicitly casts the result.

Parameters
$key : string
$section : string = ''

Optional section to look in

$default : int = 0

Fallback if value is missing or invalid

Return values
int

getJsonArray()

Get a config value as a JSON-decoded array.

public getJsonArray(string $key[, string $section = '' ][, array<string|int, mixed> $default = [] ]) : array<string|int, mixed>

Some weirdos (probably you) put actual JSON in an INI file. This decodes it into an array and fails gracefully if it's not valid JSON.

Example INI:

options = '["foo", "bar", "baz"]'
Parameters
$key : string
$section : string = ''

Optional section to look in

$default : array<string|int, mixed> = []

Fallback if not set or invalid

Return values
array<string|int, mixed> —

Can be replaced with 'array'

getSection()

Gets all key-value pairs from a section.

public getSection([string $section = '' ]) : array<string|int, mixed>
Parameters
$section : string = ''
Return values
array<string|int, mixed>

has()

Checks if a key exists in the given section.

public has(string $key[, string $section = '' ]) : bool
Parameters
$key : string
$section : string = ''
Return values
bool

loadFromFile()

Loads content from an INI file or creates a stub file if it doesn't exist. This DOES NOT change the filename that future calls to save functions will do. This gives you the ability to copy from an existing file

public loadFromFile([string $filename = '' ]) : void
Parameters
$filename : string = ''

Optional filename to override the current one.

lock()

Locks the INI handler to prevent write operations.

public lock() : void

reload()

Resets and reloads the INI file from the disk.

public reload() : void

reset()

Resets readOnly status and clears all contents.

public reset() : void

safeSave()

Safely writes contents to the file, preserving existing structure and comments where possible by modifying in-place.

public safeSave([string $filename = '' ]) : void
Parameters
$filename : string = ''

Optional filename override.

saveToFile()

Saves the current INI contents to the file.

public saveToFile([string $filename = '' ]) : bool|int

Note: This will overwrite the file and remove all comments.

Parameters
$filename : string = ''

Optional filename override.

Return values
bool|int —

Number of bytes written, or false on failure.

set()

Sets a value in the INI content.

public set(string $key, string $value[, string $section = '' ]) : string
Parameters
$key : string
$value : string
$section : string = ''
Return values
string

setDefaultSection()

Sets the default section to use when none is provided.

public setDefaultSection(string $section) : string
Parameters
$section : string
Return values
string —

The old default section.

toJson()

Converts the entire contents array to a JSON string.

public toJson() : string
Return values
string

unlock()

Unlocks the INI handler to allow your write operations.

public unlock() : void 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results