README.md 4.43 KB
Newer Older
yosymfony's avatar
yosymfony committed
1
2
TOML parser for PHP
===================
YoSymfony's avatar
YoSymfony committed
3

Yo! Symfony's avatar
Yo! Symfony committed
4
A PHP parser for [TOML](https://github.com/toml-lang/toml) compatible with [TOML v0.4.0](https://github.com/toml-lang/toml/releases/tag/v0.4.0).
victorpuertas's avatar
victorpuertas committed
5

yosymfony's avatar
yosymfony committed
6
[![Build Status](https://travis-ci.org/yosymfony/toml.png?branch=master)](https://travis-ci.org/yosymfony/toml)
7
8
9
[![Latest Stable Version](https://poser.pugx.org/yosymfony/toml/v/stable.png)](https://packagist.org/packages/yosymfony/toml)
[![Total Downloads](https://poser.pugx.org/yosymfony/toml/downloads.png)](https://packagist.org/packages/yosymfony/toml)

Yo! Symfony's avatar
Yo! Symfony committed
10
11
12
13
Support:

[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/yosymfony/Toml?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)

victorpuertas's avatar
victorpuertas committed
14
15
Installation
------------
yosymfony's avatar
yosymfony committed
16
**Requires PHP >= 7.1.**
victorpuertas's avatar
victorpuertas committed
17

18
Use [Composer](http://getcomposer.org/) to install this package:
victorpuertas's avatar
victorpuertas committed
19

20
21
```bash
composer require yosymfony/toml
Yo! Symfony's avatar
Yo! Symfony committed
22
```
victorpuertas's avatar
victorpuertas committed
23
24
25

Usage
-----
yosymfony's avatar
yosymfony committed
26
You can parse an inline TOML string or from a file:
victorpuertas's avatar
victorpuertas committed
27

yosymfony's avatar
yosymfony committed
28
29
To parse an inline TOML string:

Yo! Symfony's avatar
Yo! Symfony committed
30
31
32
33
34
35
36
```php
use Yosymfony\Toml\Toml;

$array = Toml::Parse('key = [1,2,3]');

print_r($array);
```
victorpuertas's avatar
victorpuertas committed
37

yosymfony's avatar
yosymfony committed
38
To parse a TOML file:
victorpuertas's avatar
victorpuertas committed
39

Yo! Symfony's avatar
Yo! Symfony committed
40
```php
yosymfony's avatar
yosymfony committed
41
$array = Toml::ParseFile('example.toml');
Yo! Symfony's avatar
Yo! Symfony committed
42
43
44

print_r($array);
```
victorpuertas's avatar
victorpuertas committed
45

yosymfony's avatar
yosymfony committed
46
Additionally, methods `parse` and `parseFile` accept a second argument called
yosymfony's avatar
yosymfony committed
47
48
49
50
51
52
`resultAsObject` to return the result as an object based on `stdClass`.

```php
$object = Toml::Parse('key = [1,2,3]', true);
```

victorpuertas's avatar
victorpuertas committed
53
### TomlBuilder
yosymfony's avatar
yosymfony committed
54
You can create a TOML string with TomlBuilder. TomlBuilder uses a *fluent interface* for more readable code:
victorpuertas's avatar
victorpuertas committed
55

56
```php
victorpuertas's avatar
victorpuertas committed
57
    use Yosymfony\Toml\TomlBuilder;
58

victorpuertas's avatar
victorpuertas committed
59
    $tb = new TomlBuilder();
yosymfony's avatar
yosymfony committed
60

victorpuertas's avatar
victorpuertas committed
61
    $result = $tb->addComment('Toml file')
yosymfony's avatar
yosymfony committed
62
        ->addTable('data.string')
victorpuertas's avatar
victorpuertas committed
63
64
65
        ->addValue('name', "Toml", 'This is your name')
        ->addValue('newline', "This string has a \n new line character.")
        ->addValue('winPath', "C:\\Users\\nodejs\\templates")
66
        ->addValue('literal', '@<\i\c*\s*>') // literals starts with '@'.
victorpuertas's avatar
victorpuertas committed
67
        ->addValue('unicode', 'unicode character: ' . json_decode('"\u03B4"'))
yosymfony's avatar
yosymfony committed
68

yosymfony's avatar
yosymfony committed
69
        ->addTable('data.bool')
victorpuertas's avatar
victorpuertas committed
70
71
        ->addValue('t', true)
        ->addValue('f', false)
yosymfony's avatar
yosymfony committed
72

yosymfony's avatar
yosymfony committed
73
        ->addTable('data.integer')
victorpuertas's avatar
victorpuertas committed
74
75
        ->addValue('positive', 25, 'Comment inline.')
        ->addValue('negative', -25)
yosymfony's avatar
yosymfony committed
76

yosymfony's avatar
yosymfony committed
77
        ->addTable('data.float')
victorpuertas's avatar
victorpuertas committed
78
79
        ->addValue('positive', 25.25)
        ->addValue('negative', -25.25)
yosymfony's avatar
yosymfony committed
80

Daniel Bannert's avatar
Daniel Bannert committed
81
        ->addTable('data.datetime')
victorpuertas's avatar
victorpuertas committed
82
        ->addValue('datetime', new \Datetime())
yosymfony's avatar
yosymfony committed
83

victorpuertas's avatar
victorpuertas committed
84
        ->addComment('Related to arrays')
85

yosymfony's avatar
yosymfony committed
86
        ->addTable('data.array')
victorpuertas's avatar
victorpuertas committed
87
        ->addValue('simple', array(1,2,3))
88
89
90
91
92
        ->addValue('multiple', array(
            array(1,2),
            array('abc', 'def'),
            array(1.1, 1.2),
            array(true, false),
victorpuertas's avatar
victorpuertas committed
93
            array( new \Datetime()) ))
yosymfony's avatar
yosymfony committed
94

95
        ->addComment('Array of tables')
96

97
        ->addArrayTables('fruit')                            // Row
yosymfony's avatar
yosymfony committed
98
            ->addValue('name', 'apple')
99
            ->addArrayTables('fruit.variety')
yosymfony's avatar
yosymfony committed
100
                ->addValue('name', 'red delicious')
101
            ->addArrayTables('fruit.variety')
yosymfony's avatar
yosymfony committed
102
                ->addValue('name', 'granny smith')
103
        ->addArrayTables('fruit')                            // Row
yosymfony's avatar
yosymfony committed
104
            ->addValue('name', 'banana')
105
            ->addArrayTables('fruit.variety')
yosymfony's avatar
yosymfony committed
106
107
                ->addValue('name', 'platain')

victorpuertas's avatar
victorpuertas committed
108
        ->getTomlString();    // Generate the TOML string
109
```
110
The result:
victorpuertas's avatar
victorpuertas committed
111
112

    #Toml file
113

victorpuertas's avatar
victorpuertas committed
114
115
116
117
    [data.string]
    name = "Toml" #This is your name
    newline = "This string has a \n new line character."
    winPath = "C:\\Users\\nodejs\\templates"
118
    literal = '<\i\c*\s*>'
victorpuertas's avatar
victorpuertas committed
119
    unicode = "unicode character: δ"
120

victorpuertas's avatar
victorpuertas committed
121
122
123
    [data.bool]
    t = true
    f = false
124

victorpuertas's avatar
victorpuertas committed
125
126
127
    [data.integer]
    positive = 25 #Comment inline.
    negative = -25
128

victorpuertas's avatar
victorpuertas committed
129
130
131
    [data.float]
    positive = 25.25
    negative = -25.25
132

victorpuertas's avatar
victorpuertas committed
133
134
    [data.datetime]
    datetime = 2013-06-10T21:12:48Z
135

victorpuertas's avatar
victorpuertas committed
136
    #Related to arrays
137

victorpuertas's avatar
victorpuertas committed
138
139
140
    [data.array]
    simple = [1, 2, 3]
    multiple = [[1, 2], ["abc", "def"], [1.1, 1.2], [true, false], [2013-06-10T21:12:48Z]]
141

142
    # Array of tables
143

144
145
    [[fruit]]
        name = "apple"
146

147
148
        [[fruit.variety]]
            name = "red delicious"
149

150
151
        [[fruit.variety]]
            name = "granny smith"
152

153
154
    [[fruit]]
        name = "banana"
155

156
157
        [[fruit.variety]]
        name = "platain"
victorpuertas's avatar
victorpuertas committed
158

victorpuertas's avatar
victorpuertas committed
159
160
Unit tests
----------
161
This library requires [PHPUnit](https://phpunit.de/) >= 6.3.
victorpuertas's avatar
victorpuertas committed
162
163
You can run the unit tests with the following command:

164
165
166
167
168
169
170
171
172
```bash
$ cd toml
$ phpunit
```

## License

This library is open-sourced software licensed under the
[MIT license](http://opensource.org/licenses/MIT).