gnu-social/vendor/zendframework/zend-config/doc/book/writer.md

Zend\Config\Writer

Zend\Config\Writer provides the ability to write config files from an array, Zend\Config\Config instance, or any Traversable object. Zend\Config\Writer is itself only an interface that defining the methods toFile() and toString().

We have five writers implementing the interface:

• Zend\Config\Writer\Ini
• Zend\Config\Writer\Xml
• Zend\Config\Writer\PhpArray
• Zend\Config\Writer\Json
• Zend\Config\Writer\Yaml

Zend\Config\Writer\Ini

The INI writer has two modes for rendering with regard to sections. By default, the top-level configuration is always written into section names. By calling $writer->setRenderWithoutSectionsFlags(true); all options are written into the global namespace of the INI file and no sections are applied.

Zend\Config\Writer\Ini has an additional option parameter, nestSeparator, which defines with which character the single nodes are separated. The default is a single dot (.), such as is accepted by Zend\Config\Reader\Ini by default.

When modifying or creating a Zend\Config\Config object, there are several considerations to keep in mind. To create or modify a value, you simply say set the parameter of the Config object via the parameter accessor (->). To create a section in the root or to create a branch, just create a new array ($config->branch = [];).

Using Zend\Config\Writer\Ini

Consider the following code, which creates a configuration structure:

// Create the config object
$config = new Zend\Config\Config([], true);
$config->production = [];

$config->production->webhost = 'www.example.com';
$config->production->database = [];
$config->production->database->params = [];
$config->production->database->params->host = 'localhost';
$config->production->database->params->username = 'production';
$config->production->database->params->password = 'secret';
$config->production->database->params->dbname = 'dbproduction';

$writer = new Zend\Config\Writer\Ini();
echo $writer->toString($config);

The result of this code is the following INI string:

[production]
webhost = "www.example.com"
database.params.host = "localhost"
database.params.username = "production"
database.params.password = "secret"
database.params.dbname = "dbproduction"

You can use the method toFile() to store the INI data to a file instead.

Zend\Config\Writer\Xml

Zend\Config\Writer\Xml can be used to generate an XML string or file.

Using Zend\Config\Writer\Xml

Consider the following code, which creates a configuration structure:

// Create the config object
$config = new Zend\Config\Config([], true);
$config->production = [];

$config->production->webhost = 'www.example.com';
$config->production->database = [];
$config->production->database->params = [];
$config->production->database->params->host = 'localhost';
$config->production->database->params->username = 'production';
$config->production->database->params->password = 'secret';
$config->production->database->params->dbname = 'dbproduction';

$writer = new Zend\Config\Writer\Xml();
echo $writer->toString($config);

The result of this code is the following XML string:

<?xml version="1.0" encoding="UTF-8"?>
<zend-config>
    <production>
        <webhost>www.example.com</webhost>
        <database>
            <params>
                <host>localhost</host>
                <username>production</username>
                <password>secret</password>
                <dbname>dbproduction</dbname>
            </params>
        </database>
    </production>
</zend-config>

You can use the method toFile() to store the XML data to a file.

Zend\Config\Writer\PhpArray

Zend\Config\Writer\PhpArray can be used to generate a PHP script that represents and returns configuration.

Using Zend\Config\Writer\PhpArray

Consider the following code, which creates a configuration structure:

// Create the config object
$config = new Zend\Config\Config([], true);
$config->production = [];

$config->production->webhost = 'www.example.com';
$config->production->database = [];
$config->production->database->params = [];
$config->production->database->params->host = 'localhost';
$config->production->database->params->username = 'production';
$config->production->database->params->password = 'secret';
$config->production->database->params->dbname = 'dbproduction';

$writer = new Zend\Config\Writer\PhpArray();
echo $writer->toString($config);

The result of this code is the following PHP script:

<?php
return array (
  'production' =>
  array (
    'webhost' => 'www.example.com',
    'database' =>
    array (
      'params' =>
      array (
        'host' => 'localhost',
        'username' => 'production',
        'password' => 'secret',
        'dbname' => 'dbproduction',
      ),
    ),
  ),
);

You can use the method toFile() to save the PHP script to a file.

Zend\Config\Writer\Json

Zend\Config\Writer\Json can be used to generate a JSON representation of configuration.

Using Zend\Config\Writer\Json

Consider the following code, which creates a configuration structure:

// Create the config object
$config = new Zend\Config\Config([], true);
$config->production = [];

$config->production->webhost = 'www.example.com';
$config->production->database = [];
$config->production->database->params = [];
$config->production->database->params->host = 'localhost';
$config->production->database->params->username = 'production';
$config->production->database->params->password = 'secret';
$config->production->database->params->dbname = 'dbproduction';

$writer = new Zend\Config\Writer\Json();
echo $writer->toString($config);

The result of this code is the following JSON string:

{
  "webhost": "www.example.com",
  "database": {
    "params": {
      "host": "localhost",
      "username": "production",
      "password": "secret",
      "dbname": "dbproduction"
    }
  }
}

You can use the method toFile() to save the JSON data to a file.

Zend\Config\Writer\Json uses the zend-json component to convert the data to JSON.

Zend\Config\Writer\Yaml

Zend\Config\Writer\Yaml can be used to generate a PHP code that returns the YAML representation of configuration. In order to use the YAML writer, we need to pass a callback to an external PHP library, or use the YAML PECL extension.

Using Zend\Config\Writer\Yaml

Consider the following code, which creates a configuration structure using the YAML PECL extension:

// Create the config object
$config = new Zend\Config\Config([], true);
$config->production = [];

$config->production->webhost = 'www.example.com';
$config->production->database = [];
$config->production->database->params = [];
$config->production->database->params->host = 'localhost';
$config->production->database->params->username = 'production';
$config->production->database->params->password = 'secret';
$config->production->database->params->dbname = 'dbproduction';

$writer = new Zend\Config\Writer\Yaml();
echo $writer->toString($config);

The result of this code is the following YAML string contains the following value:

webhost: www.example.com
database:
    params:
      host:     localhost
      username: production
      password: secret
      dbname:   dbproduction

You can use the method toFile() to save the YAML data to a file.

If you want to use an external YAML writer library, pass the callback function that will generate the YAML from the configuration when instantiating the writer. For instance, to use the Spyc library:

// include the Spyc library
require_once 'path/to/spyc.php';

$writer = new Zend\Config\Writer\Yaml(['Spyc', 'YAMLDump']);
echo $writer->toString($config);