sweetchuck/ini-serializer

INI reader-writer

2.x-dev 2025-10-16 20:18 UTC

Requires

• php: >=8.4
• ext-mbstring: *

Requires (Dev)

• ext-json: *
• nuvoleweb/robo-config: ^3.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^2.1
• phpstan/phpstan-phpunit: ^2.0
• phpunit/phpunit: ^11.0
• squizlabs/php_codesniffer: ^3.5
• sweetchuck/git-hooks: 2.x-dev
• sweetchuck/robo-git: 4.x-dev
• sweetchuck/robo-phpcs: 4.x-dev
• sweetchuck/robo-phpstan: 3.x-dev
• symfony/error-handler: ^7.0

GPL-2.0-or-later

• Andor

• ini
• serializer

README

A flexible PHP library for parsing and generating INI files with flexible type handling, customizable formatting options, and full control over serialization behavior.

Features

• Intelligent Type Conversion: Automatically converts values to proper PHP types (integers, floats, booleans, null)
• Customizable Type Aliases: Define your own values for null, true, and false
• Comment Support: Handles both ; and # style comments (configurable)
• Grouped Sections: Full support for INI sections [group_name]
• Flexible Formatting: Control quote usage and spacing around equal signs
• Bidirectional: Parse INI strings to PHP arrays and emit PHP arrays back to INI format
• UTF-8 Ready: Built-in mbstring support for proper Unicode handling

Why Use This Over PHP's Native parse_ini_file()?

1. Predictable Type Conversion

• This library explicitly converts typed values (bool, null, int, float)
• You can configure which string values represent true, false, and null

2. Complete Bidirectional Support

• Native parse_ini_file() only reads INI files
• This library can generate INI files from PHP arrays, maintaining structure

3. Formatting Control

• Configure spacing around equal signs
• Control whether strings are quoted
• Generate consistently formatted INI files

4. Customizable Comment Characters

• Change which characters are treated as comments
• Useful for different INI dialects

5. Better Boolean Handling

• Recognizes multiple boolean representations:
  • True: true, on, yes
  • False: false, off, no
• All case-insensitive

6. Proper Null Handling

• Distinguishes between empty strings and null values
• Recognizes null and nil as null values

7. Group Name Escaping

• Properly handles special characters in section names [group_name]

Limitations

⚠️ Important: This library does not resolve PHP constants or environment variables.

• PHP constants like \PHP_VERSION or \E_ALL are treated as regular strings
• Environment variables are not interpolated during parsing
• If you need constant/environment variable support, you should handle that separately before parsing or after parsing

Example:

$ini = 'debug=DEBUG_MODE'; // DEBUG_MODE constant won't be resolved
$data = $serializer->parse($ini);
$data['debug']; // Returns string 'DEBUG_MODE', not the constant value

// If you need this, resolve it manually:
if (defined($data['debug'])) {
    $data['debug'] = constant($data['debug']);
}

Usage

Basic Parsing

use Sweetchuck\IniSerializer\IniSerializer;

$ini = <<<INI
[database]
host=localhost
port=3306
debug=true
password=

[cache]
enabled=yes
ttl=3600
max_size=null
INI;

$serializer = new IniSerializer();
$data = $serializer->parse($ini);

// Result:
// [
//     'database' => [
//         'host' => 'localhost',
//         'port' => 3306,
//         'debug' => true,
//         'password' => null,
//     ],
//     'cache' => [
//         'enabled' => true,
//         'ttl' => 3600,
//         'max_size' => null,
//     ],
// ]

Generating INI Files

$data = [
    'database' => [
        'host' => 'localhost',
        'port' => 3306,
        'debug' => true,
        'timeout' => 30.5,
    ],
    'cache' => [
        'enabled' => false,
        'ttl' => 3600,
    ],
];

$serializer = new IniSerializer();
$iniString = $serializer->emit($data);

echo $iniString;
// Output:
// [database]
// host=localhost
// port=3306
// debug=true
// timeout=30.5
//
// [cache]
// enabled=false
// ttl=3600
//

Formatting Options

$serializer = new IniSerializer();

// Add spaces around equal signs
$serializer->setSpaceAroundEqualSign(true);

// Quote all string values
$serializer->setQuoteStrings(true);

$data = ['section' => ['key' => 'value']];
$ini = $serializer->emit($data);

// Output:
// [section]
// key = "value"
//

Customizing Type Values

$serializer = new IniSerializer();

// Customize what values represent booleans
$serializer->setValueBoolTrue(['yes', 'on', 'enabled', '1']);
$serializer->setValueBoolFalse(['no', 'off', 'disabled', '0']);

// Customize what values represent null
$serializer->setValueNull(['null', 'nil', 'none']);

// Or set all options at once
$serializer->setOptions([
    'valueBoolTrue' => ['yes', 'on', '1'],
    'valueBoolFalse' => ['no', 'off', '0'],
    'valueNull' => ['null', 'nil'],
    'commentChars' => [';', '#'],
    'quoteStrings' => false,
    'spaceAroundEqualSign' => false,
]);

$iniString = 'enabled=yes
is_prod=no
api_key=null';

$data = $serializer->parse($iniString);
// Result: ['enabled' => true, 'is_prod' => false, 'api_key' => null]

Working with Existing Files

$serializer = new IniSerializer();

// Read and parse
$iniContent = file_get_contents('config.ini');
$config = $serializer->parse($iniContent);

// Modify
$config['database']['host'] = 'newhost.com';

// Write back
$updatedIni = $serializer->emit($config);
file_put_contents('config.ini', $updatedIni);