355 lines
10 KiB
Markdown
355 lines
10 KiB
Markdown
|
# Zend\\Config\\Reader
|
||
|
|
|
||
|
|
`Zend\Config\Reader` gives you the ability to read a config file. It works with
|
||
|
|
concrete implementations for different file formats. `Zend\Config\Reader` itself
|
||
|
|
is only an interface, defining the methods `fromFile()` and `fromString()`. The
|
||
|
|
concrete implementations of this interface are:
|
||
|
|
|
||
|
|
- `Zend\Config\Reader\Ini`
|
||
|
|
- `Zend\Config\Reader\Xml`
|
||
|
|
- `Zend\Config\Reader\Json`
|
||
|
|
- `Zend\Config\Reader\Yaml`
|
||
|
|
- `Zend\Config\Reader\JavaProperties`
|
||
|
|
|
||
|
|
`fromFile()` and `fromString()` are expected to return a PHP array containing
|
||
|
|
the data from the specified configuration.
|
||
|
|
|
||
|
|
> ## Differences from ZF1
|
||
|
|
>
|
||
|
|
> The `Zend\Config\Reader` component no longer supports the following features:
|
||
|
|
>
|
||
|
|
> - Inheritance of sections.
|
||
|
|
> - Reading of specific sections.
|
||
|
|
|
||
|
|
## Zend\\Config\\Reader\\Ini
|
||
|
|
|
||
|
|
`Zend\Config\Reader\Ini` enables developers to store configuration data in a
|
||
|
|
familiar INI format, and then to read them in the application by using an array
|
||
|
|
syntax.
|
||
|
|
|
||
|
|
`Zend\Config\Reader\Ini` utilizes the [`parse_ini_file()`](http://php.net/parse_ini_file) PHP
|
||
|
|
function. Please review this documentation to be aware of its specific behaviors, which propagate to
|
||
|
|
`Zend\Config\Reader\Ini`, such as how the special values of `TRUE`, `FALSE`, "yes", "no", and
|
||
|
|
`NULL` are handled.
|
||
|
|
|
||
|
|
> ### Key Separator
|
||
|
|
>
|
||
|
|
> By default, the key separator character is the period character (`.`). This can be changed,
|
||
|
|
> however, using the `setNestSeparator()` method. For example:
|
||
|
|
>
|
||
|
|
> ```php
|
||
|
|
> $reader = new Zend\Config\Reader\Ini();
|
||
|
|
> $reader-setNestSeparator('-');
|
||
|
|
> ```
|
||
|
|
|
||
|
|
The following example illustrates basic usage of `Zend\Config\Reader\Ini` for
|
||
|
|
loading configuration data from an INI file. In this example, configuration data
|
||
|
|
for both a production system and for a staging system exists.
|
||
|
|
|
||
|
|
```ini
|
||
|
|
webhost = 'www.example.com'
|
||
|
|
database.adapter = 'pdo_mysql'
|
||
|
|
database.params.host = 'db.example.com'
|
||
|
|
database.params.username = 'dbuser'
|
||
|
|
database.params.password = 'secret'
|
||
|
|
database.params.dbname = 'dbproduction'
|
||
|
|
```
|
||
|
|
|
||
|
|
We can use `Zend\Config\Reader\Ini` to read this INI file:
|
||
|
|
|
||
|
|
```php
|
||
|
|
$reader = new Zend\Config\Reader\Ini();
|
||
|
|
$data = $reader->fromFile('/path/to/config.ini');
|
||
|
|
|
||
|
|
echo $data['webhost']; // prints "www.example.com"
|
||
|
|
echo $data['database']['params']['dbname']; // prints "dbproduction"
|
||
|
|
```
|
||
|
|
|
||
|
|
`Zend\Config\Reader\Ini` supports a feature to include the content of a INI file
|
||
|
|
in a specific section of another INI file. For instance, suppose we have an INI
|
||
|
|
file with the database configuration:
|
||
|
|
|
||
|
|
```ini
|
||
|
|
database.adapter = 'pdo_mysql'
|
||
|
|
database.params.host = 'db.example.com'
|
||
|
|
database.params.username = 'dbuser'
|
||
|
|
database.params.password = 'secret'
|
||
|
|
database.params.dbname = 'dbproduction'
|
||
|
|
```
|
||
|
|
|
||
|
|
We can include this configuration in another INI file by using the `@include`
|
||
|
|
notation:
|
||
|
|
|
||
|
|
```ini
|
||
|
|
webhost = 'www.example.com'
|
||
|
|
@include = 'database.ini'
|
||
|
|
```
|
||
|
|
|
||
|
|
If we read this file using the component `Zend\Config\Reader\Ini`, we will obtain the same
|
||
|
|
configuration data structure as in the previous example.
|
||
|
|
|
||
|
|
The `@include = 'file-to-include.ini'` notation can be used also in a subelement
|
||
|
|
of a value. For instance we can have an INI file like the following:
|
||
|
|
|
||
|
|
```ini
|
||
|
|
adapter = 'pdo_mysql'
|
||
|
|
params.host = 'db.example.com'
|
||
|
|
params.username = 'dbuser'
|
||
|
|
params.password = 'secret'
|
||
|
|
params.dbname = 'dbproduction'
|
||
|
|
```
|
||
|
|
|
||
|
|
And assign the `@include` as a subelement of the `database` value:
|
||
|
|
|
||
|
|
```ini
|
||
|
|
webhost = 'www.example.com'
|
||
|
|
database.@include = 'database.ini'
|
||
|
|
```
|
||
|
|
|
||
|
|
## Zend\\Config\\Reader\\Xml
|
||
|
|
|
||
|
|
`Zend\Config\Reader\Xml` enables developers to provide configuration data in a
|
||
|
|
familiar XML format and consume it in the application using an array syntax.
|
||
|
|
The root element of the XML file or string is irrelevant and may be named
|
||
|
|
arbitrarily.
|
||
|
|
|
||
|
|
The following example illustrates basic usage of `Zend\Config\Reader\Xml` for loading configuration
|
||
|
|
data from an XML file. First, our XML configuration in the file `config.xml`:
|
||
|
|
|
||
|
|
```markup
|
||
|
|
<?xml version="1.0" encoding="utf-8"?>
|
||
|
|
<config>
|
||
|
|
<webhost>www.example.com</webhost>
|
||
|
|
<database>
|
||
|
|
<adapter value="pdo_mysql"/>
|
||
|
|
<params>
|
||
|
|
<host value="db.example.com"/>
|
||
|
|
<username value="dbuser"/>
|
||
|
|
<password value="secret"/>
|
||
|
|
<dbname value="dbproduction"/>
|
||
|
|
</params>
|
||
|
|
</database>
|
||
|
|
</config>
|
||
|
|
```
|
||
|
|
|
||
|
|
We can use the `Zend\Config\Reader\Xml` to read the XML configuration:
|
||
|
|
|
||
|
|
```php
|
||
|
|
$reader = new Zend\Config\Reader\Xml();
|
||
|
|
$data = $reader->fromFile('/path/to/config.xml');
|
||
|
|
|
||
|
|
echo $data['webhost']; // prints "www.example.com"
|
||
|
|
echo $data['database']['params']['dbname']['value']; // prints "dbproduction"
|
||
|
|
```
|
||
|
|
|
||
|
|
`Zend\Config\Reader\Xml` utilizes PHP's [XMLReader](http://php.net/xmlreader) class. Please
|
||
|
|
review its documentation to be aware of its specific behaviors, which propagate to
|
||
|
|
`Zend\Config\Reader\Xml`.
|
||
|
|
|
||
|
|
Using `Zend\Config\Reader\Xml`, we can include the content of XML files in a
|
||
|
|
specific XML element. This is provided using the standard
|
||
|
|
[XInclude](http://www.w3.org/TR/xinclude/) functionality of XML. To use this
|
||
|
|
functionality, you must add the namespace
|
||
|
|
`xmlns:xi="http://www.w3.org/2001/XInclude"` to the XML file.
|
||
|
|
|
||
|
|
Suppose we have an XML file that contains only the database configuration:
|
||
|
|
|
||
|
|
```markup
|
||
|
|
<?xml version="1.0" encoding="utf-8"?>
|
||
|
|
<config>
|
||
|
|
<database>
|
||
|
|
<adapter>pdo_mysql</adapter>
|
||
|
|
<params>
|
||
|
|
<host>db.example.com</host>
|
||
|
|
<username>dbuser</username>
|
||
|
|
<password>secret</password>
|
||
|
|
<dbname>dbproduction</dbname>
|
||
|
|
</params>
|
||
|
|
</database>
|
||
|
|
</config>
|
||
|
|
```
|
||
|
|
|
||
|
|
We can include this configuration in another XML file using an xinclude:
|
||
|
|
|
||
|
|
```markup
|
||
|
|
<?xml version="1.0" encoding="utf-8"?>
|
||
|
|
<config xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<webhost>www.example.com</webhost>
|
||
|
|
<xi:include href="database.xml"/>
|
||
|
|
</config>
|
||
|
|
```
|
||
|
|
|
||
|
|
The syntax to include an XML file in a specific element is `<xi:include
|
||
|
|
href="file-to-include.xml"/>`
|
||
|
|
|
||
|
|
## Zend\\Config\\Reader\\Json
|
||
|
|
|
||
|
|
`Zend\Config\Reader\Json` enables developers to consume configuration data in
|
||
|
|
JSON, and read it in the application by using an array syntax.
|
||
|
|
|
||
|
|
The following example illustrates a basic use of `Zend\Config\Reader\Json` for
|
||
|
|
loading configuration data from a JSON file.
|
||
|
|
|
||
|
|
Consider the following JSON configuration file:
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
{
|
||
|
|
"webhost" : "www.example.com",
|
||
|
|
"database" : {
|
||
|
|
"adapter" : "pdo_mysql",
|
||
|
|
"params" : {
|
||
|
|
"host" : "db.example.com",
|
||
|
|
"username" : "dbuser",
|
||
|
|
"password" : "secret",
|
||
|
|
"dbname" : "dbproduction"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
We can use `Zend\Config\Reader\Json` to read the file:
|
||
|
|
|
||
|
|
```php
|
||
|
|
$reader = new Zend\Config\Reader\Json();
|
||
|
|
$data = $reader->fromFile('/path/to/config.json');
|
||
|
|
|
||
|
|
echo $data['webhost']; // prints "www.example.com"
|
||
|
|
echo $data['database']['params']['dbname']; // prints "dbproduction"
|
||
|
|
```
|
||
|
|
|
||
|
|
`Zend\Config\Reader\Json` utilizes [zend-json](https://github.com/zendframework/zend-json).
|
||
|
|
|
||
|
|
Using `Zend\Config\Reader\Json`, we can include the content of a JSON file in a
|
||
|
|
specific JSON section or element. This is provided using the special syntax
|
||
|
|
`@include`. Suppose we have a JSON file that contains only the database
|
||
|
|
configuration:
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
{
|
||
|
|
"database" : {
|
||
|
|
"adapter" : "pdo_mysql",
|
||
|
|
"params" : {
|
||
|
|
"host" : "db.example.com",
|
||
|
|
"username" : "dbuser",
|
||
|
|
"password" : "secret",
|
||
|
|
"dbname" : "dbproduction"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
Now let's include it via another configuration file:
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
{
|
||
|
|
"webhost" : "www.example.com",
|
||
|
|
"@include" : "database.json"
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## Zend\\Config\\Reader\\Yaml
|
||
|
|
|
||
|
|
`Zend\Config\Reader\Yaml` enables developers to consume configuration data in a
|
||
|
|
YAML format, and read them in the application by using an array syntax. In order
|
||
|
|
to use the YAML reader, we need to pass a callback to an external PHP library or
|
||
|
|
use the [YAML PECL extension](http://www.php.net/manual/en/book.yaml.php).
|
||
|
|
|
||
|
|
The following example illustrates basic usage of `Zend\Config\Reader\Yaml`,
|
||
|
|
using the YAML PECL extension.
|
||
|
|
|
||
|
|
Consider the following YAML file:
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
webhost: www.example.com
|
||
|
|
database:
|
||
|
|
adapter: pdo_mysql
|
||
|
|
params:
|
||
|
|
host: db.example.com
|
||
|
|
username: dbuser
|
||
|
|
password: secret
|
||
|
|
dbname: dbproduction
|
||
|
|
```
|
||
|
|
|
||
|
|
We can use `Zend\Config\Reader\Yaml` to read this YAML file:
|
||
|
|
|
||
|
|
```php
|
||
|
|
$reader = new Zend\Config\Reader\Yaml();
|
||
|
|
$data = $reader->fromFile('/path/to/config.yaml');
|
||
|
|
|
||
|
|
echo $data['webhost']; // prints "www.example.com"
|
||
|
|
echo $data['database']['params']['dbname']; // prints "dbproduction"
|
||
|
|
```
|
||
|
|
|
||
|
|
If you want to use an external YAML reader, you must pass a callback function to
|
||
|
|
the class constructor. For instance, if you want to use the
|
||
|
|
[Spyc](http://code.google.com/p/spyc/) library:
|
||
|
|
|
||
|
|
```php
|
||
|
|
// include the Spyc library
|
||
|
|
require_once 'path/to/spyc.php';
|
||
|
|
|
||
|
|
$reader = new Zend\Config\Reader\Yaml(['Spyc', 'YAMLLoadString']);
|
||
|
|
$data = $reader->fromFile('/path/to/config.yaml');
|
||
|
|
|
||
|
|
echo $data['webhost']; // prints "www.example.com"
|
||
|
|
echo $data['database']['params']['dbname']; // prints "dbproduction"
|
||
|
|
```
|
||
|
|
|
||
|
|
You can also instantiate `Zend\Config\Reader\Yaml` without any parameters, and
|
||
|
|
specify the YAML reader using the `setYamlDecoder()` method.
|
||
|
|
|
||
|
|
Using `Zend\Config\ReaderYaml`, we can include the content of another YAML file
|
||
|
|
in a specific YAML section or element. This is provided using the special syntax
|
||
|
|
`@include`.
|
||
|
|
|
||
|
|
Consider the following YAML file containing only database configuration:
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
database:
|
||
|
|
adapter: pdo_mysql
|
||
|
|
params:
|
||
|
|
host: db.example.com
|
||
|
|
username: dbuser
|
||
|
|
password: secret
|
||
|
|
dbname: dbproduction
|
||
|
|
```
|
||
|
|
|
||
|
|
We can include this configuration in another YAML file:
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
webhost: www.example.com
|
||
|
|
@include: database.yaml
|
||
|
|
```
|
||
|
|
|
||
|
|
## Zend\\Config\\Reader\\JavaProperties
|
||
|
|
|
||
|
|
`Zend\Config\Reader\JavaProperties` enables developers to provide configuration
|
||
|
|
data in the popular JavaProperties format, and read it in the application by
|
||
|
|
using array syntax.
|
||
|
|
|
||
|
|
The following example illustrates basic usage of `Zend\Config\Reader\JavaProperties`
|
||
|
|
for loading configuration data from a JavaProperties file.
|
||
|
|
|
||
|
|
Suppose we have the following JavaProperties configuration file:
|
||
|
|
|
||
|
|
```ini
|
||
|
|
#comment
|
||
|
|
!comment
|
||
|
|
webhost:www.example.com
|
||
|
|
database.adapter:pdo_mysql
|
||
|
|
database.params.host:db.example.com
|
||
|
|
database.params.username:dbuser
|
||
|
|
database.params.password:secret
|
||
|
|
database.params.dbname:dbproduction
|
||
|
|
```
|
||
|
|
|
||
|
|
We can use `Zend\Config\Reader\JavaProperties` to read it:
|
||
|
|
|
||
|
|
```php
|
||
|
|
$reader = new Zend\Config\Reader\JavaProperties();
|
||
|
|
$data = $reader->fromFile('/path/to/config.properties');
|
||
|
|
|
||
|
|
echo $data['webhost']; // prints "www.example.com"
|
||
|
|
echo $data['database.params.dbname']; // prints "dbproduction"
|
||
|
|
```
|