README

Some classes to read and write properties files.

Properties files are like Java Properties file. The implemented format is using to store locales for an application made with Jelix, a PHP Framework.

installation

The library is compatible from PHP 5.6 to PHP 8.1.

You can install it from Composer. In your project:

composer require "jelix/properties-file"

Usage

You have two classes: Properties which is a container for key/value pairs, a Reader to parse a properties file and a Writer to write properties into a file.

use \Jelix\PropertiesFile\Properties;
use \Jelix\PropertiesFile\Parser;
use \Jelix\PropertiesFile\Writer;

$properties = new Properties();

$reader = new Parser();
$reader->parseFromFile('file.properties', $properties);

$value = $properties->get('a_key');
$value = $properties['a_key'];

$properties->set('a_key', 'new_value');
$properties['a_key'] = 'new_value';

$writer = new Writer();
$writer->writeToFile($properties, 'file.properties');

// with a limit of line length (default is 120)
$writer->writeToFile($properties, 'file.properties', 
                    array("lineLength"=>80));

Options for the writer:

lineLength: maximum length of a line. If the string length is higher, it will be splitted. (default: 120)
cutOnlyAtSpace: to cut lines where there is space, not on the middle of a word (default: true)
spaceAroundEqual: to add or not space around the equal sign (boolean, default: true)
headerComment: to add comment as header (string, default: empty string)
removeTrailingSpace: to remove trailing space on values (boolean, default: false)
encoding: encoding of values to write. (string, default: "UTF-8")

History

The parser is based on a class, jBundle coming from the Jelix Framework until Jelix 1.6, and has been released in 2018 into a separate repository as Jelix\PropertiesFile\Parser.

Format

The file content structure is quite simple. It's basically a key=string structure, with some improvements.

You can't use double and single quotes to delimit your strings, new lines do this.

Keys can contain characters a to z (lowercase/uppercase), numbers and characters _, -, ..

Here is an example of file:

title.offlineElements = elements to check
title.onlineElements = online elements
buttons.save = Save
buttons.ok=Ok

Multi line

If the text is long and you want to write it in several lines, you can type an anti-slash \ at the end of each line (excepted the last one of the text), to tell the parser to continue reading the translated string.

intro=this is a very very\
long text in\
several lines
message=this is a regular line

However, it doesn't insert a line break in the displayed string. If you want to insert a real line break, use \n or \r (\r\n on windows, \n on linux, \r on macs):

intro=this is a very very \
long text in\nseveral lines, but in\n one line\nin the source

Comments

You can also put some comments. They have to begin with a #. When the parser sees #, the rest of the line is ignored. A comment can be at the beginning of a line, or in the middle of a line, or at the end of the line. If you want to use a # in a value, you have to escape it with an anti-slash: \#.

Whitespaces

Whitespaces before and after a value are ignored. If you want to put a value equal to a space, you have to use \s.

nospace= #this is using a regular space
space= \s#this is using a \s space

The value of space will be ' ', and the value of nospace, an empty string.

You can also use \S to insert an 'unbreakable' space.

jelix / properties-file

Maintainers

Details