parse_ini_file

(PHP 4, PHP 5, PHP 7, PHP 8)

parse_ini_file — Обрабатывает конфигурационный файл

Описание

parse_ini_file(string $filename, bool $process_sections = false, int $scanner_mode = INI_SCANNER_NORMAL): array|false

parse_ini_file() загружает ini-файл, указанный в аргументе filename, и возвращает его настройки в виде ассоциативного массива.

Структура ini-файла похожа на структуру php.ini.

Список параметров

filename

Имя обрабатываемого ini-файла. Если используется относительный путь, он оценивается относительно текущего рабочего каталога, а затем include_path.

process_sections

Установив параметр process_sections в true, вы получаете многомерный массив, который включает как название отдельных настроек, так и секции. По умолчанию process_sections равен false

scanner_mode

Может принимать следующие значения: INI_SCANNER_NORMAL (по умолчанию) или INI_SCANNER_RAW. Если указано значение INI_SCANNER_RAW, то значения опций не будут обрабатываться.

С версии PHP 5.6.1 также можно задать INI_SCANNER_TYPED. В этом режиме типы boolean, null и integer будут, по возможности, сохраняться. Строковые значения "true", "on" и "yes" будут преобразованы в true. "false", "off", "no" и "none" в false. "null" преобразуется в null. Кроме этого, все числовые строки будут, по возможности, преобразованы к целым числам.

Возвращаемые значения

В случае успешного выполнения, настройки возвращаются в виде ассоциативного массива (array). В случае возникновения ошибки возвращается false.

Примеры

Пример #1 Содержимое sample.ini

; Это пример файла настроек
; Комментарии начинаются с ';', как в php.ini

[first_section]
one = 1
five = 5
animal = BIRD

[second_section]
path = "/usr/local/bin"
URL = "http://www.example.com/~username"

[third_section]
phpversion[] = "5.0"
phpversion[] = "5.1"
phpversion[] = "5.2"
phpversion[] = "5.3"

urls[svn] = "http://svn.php.net"
urls[git] = "http://git.php.net"

Пример #2 Пример использования функции parse_ini_file()

Константы (но не "магические константы" вроде __FILE__) также могут обрабатываться в ini-файлах, так что если вы объявите константу в виде значения для ini-файла до вызова parse_ini_file(), то константа будет корректно обработана. Только значения опций будут обрабатываться и значение должно быть просто константой. Например:


<?php

define('BIRD', 'Птица додо');

// Обрабатываем без секций
$ini_array = parse_ini_file("sample.ini");
print_r($ini_array);

// Обрабатываем с секциями
$ini_array = parse_ini_file("sample.ini", true);
print_r($ini_array);

?>

Результатом выполнения данного примера будет что-то подобное:

Array
(
    [one] => 1
    [five] => 5
    [animal] => Птица додо
    [path] => /usr/local/bin
    [URL] => http://www.example.com/~username
    [phpversion] => Array
        (
            [0] => 5.0
            [1] => 5.1
            [2] => 5.2
            [3] => 5.3
        )

    [urls] => Array
        (
            [svn] => http://svn.php.net
            [git] => http://git.php.net
        )

)
Array
(
    [first_section] => Array
        (
            [one] => 1
            [five] => 5
            [animal] => Птица додо
        )

    [second_section] => Array
        (
            [path] => /usr/local/bin
            [URL] => http://www.example.com/~username
        )

    [third_section] => Array
        (
            [phpversion] => Array
                (
                    [0] => 5.0
                    [1] => 5.1
                    [2] => 5.2
                    [3] => 5.3
                )

            [urls] => Array
                (
                    [svn] => http://svn.php.net
                    [git] => http://git.php.net
                )

        )

)

Пример #3 Обработка файла php.ini функцией parse_ini_file()


<?php
// Простая функция для сравнения результатов
function yesno($expression)
{
    return($expression ? 'Да' : 'Нет');
}

// Получаем путь к php.ini с помощью функции php_ini_loaded_file()
$ini_path = php_ini_loaded_file();

// Обрабатываем php.ini
$ini = parse_ini_file($ini_path);

// Выводим и сравниваем значения, учтите, что использование get_cfg_var()
// даст одинаковые результаты для используемых здесь значений parsed (загруженное из файла) и loaded (используемое в данный момент)
echo '(parsed) magic_quotes_gpc = ' . yesno($ini['magic_quotes_gpc']) . PHP_EOL;
echo '(loaded) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . PHP_EOL;
?>

Результатом выполнения данного примера будет что-то подобное:

(parsed) magic_quotes_gpc = Да
(loaded) magic_quotes_gpc = Да

Пример #4 Интерполяция значений

Помимо оценки констант, некоторые символы имеют особое значение в значении ini-файлах. Кроме того, переменные среды и ранее определённые параметры конфигурации (смотрите get_cfg_var()) могут быть прочитаны с использованием синтаксиса ${}.

; | используется для побитового ИЛИ
three = 2|3

; & используется для побитового AND
four = 6&5

; ^ используется для побитового XOR
five = 3^6

; ~ используется для побитового отрицания
negative_two = ~1

; () используется для группировки
seven = (8|7)&(6|5)

; Интерполируйте переменную окружения PATH
path = ${PATH}

; Интерполируйте параметр конфигурации 'memory_limit'
configured_memory_limit = ${memory_limit}

Пример #5 Экранирование символов

Некоторые символы имеют особое значение в строках с двойными кавычками и должны быть экранированы префиксом обратной косой черты. Прежде всего, это двойная кавычка " в качестве маркера границы и сама обратная косая черта \ (если за ней следует один из специальных символов):

quoted = "Она сказала \"Именно моя точка зрения\"." ; Результатом является строка с кавычками.
hint = "Используйте \\\", чтобы избежать двойных кавычек" ; Результат: Используйте \", чтобы избежать двойных кавычек

Для путей, подобных Windows, сделано исключение: можно не экранировать обратную косую черту в конце, если за строкой в кавычках следует разрыв строки:

save_path = "C:\Temp\"

Если нужно экранировать двойные кавычки, за которыми следует перенос строки в многострочном значении, можно использовать конкатенацию значений следующим образом (за одной строкой в двойных кавычках непосредственно следует другая):

long_text = "Lorem \"ipsum\"""
 dolor" ; Результат: Lorem "ipsum"\n dolor

Другой символ со специальным значением - это $ (знак доллара). Он должен быть экранирован, если за ним следует открытая фигурная скобка:

code = "\${test}"

Экранирующие символы не поддерживаются в режиме INI_SCANNER_RAW (в этом режиме все символы обрабатываются "как есть").

Обратите внимание, что синтаксический анализатор ini не поддерживает стандартные последовательности экранирования (\n, \t и т.д.). При необходимости выполните постобработку результата parse_ini_file() с помощью функции stripcslashes().

Примечания

Замечание:
Эта функция не имеет никакого отношения к файлу php.ini. К моменту выполнения вашего скрипта, он уже обработан. Эта функция может быть использована для загрузки настроек вашего собственного приложения.

Замечание:
Если значение в ini-файле содержит прочие символы, кроме букв и цифр, оно должно заключаться в двойные кавычки (").

Замечание: Существует зарезервированные слова, которые нельзя использовать в качестве ключей в ini-файлах. Такими словами являются: null, yes, no, true, false, on, off, none. Значения null, off, no и false преобразуются в "", а значения on, yes и true в "1" , но только если не используется режим INI_SCANNER_TYPED. Символы ?{}|&~!()^" не должны использоваться в ключах и иметь какой-либо особый смысл в значениях.

Замечание:
Записи без знака равенства игнорируются. Например, "foo" игнорируется, тогда как "bar =" обрабатывается и добавляется с пустым значением. Например, в MySQL есть опция "no-auto-rehash", устанавливаемая в my.cnf, которая не имеет значения и игнорируется.

Замечание:
ini-файлы обычно обрабатываются веб-серверами как простой текст и, таким образом, по запросу передаются браузерам. Это означает, что в целях безопасности вы должны либо хранить свои ini-файлы вне корневого каталога документов, либо перенастроить веб-сервер, чтобы они не обслуживались. Невыполнение любого из этих требований может создать угрозу безопасности.

Смотрите также

parse_ini_string() - Разбирает строку конфигурации

add a note

User Contributed Notes 15 notes

down

jeremygiberson at gmail dot com ¶

14 years ago


Here is a quick parse_ini_file wrapper to add extend support to save typing and redundancy.
<?php
    /**
     * Parses INI file adding extends functionality via ":base" postfix on namespace.
     *
     * @param string $filename
     * @return array
     */
    function parse_ini_file_extended($filename) {
        $p_ini = parse_ini_file($filename, true);
        $config = array();
        foreach($p_ini as $namespace => $properties){
            list($name, $extends) = explode(':', $namespace);
            $name = trim($name);
            $extends = trim($extends);
            // create namespace if necessary
            if(!isset($config[$name])) $config[$name] = array();
            // inherit base namespace
            if(isset($p_ini[$extends])){
                foreach($p_ini[$extends] as $prop => $val)
                    $config[$name][$prop] = $val;
            }
            // overwrite / set current namespace values
            foreach($properties as $prop => $val)
            $config[$name][$prop] = $val;
        }
        return $config;
    }
?>

Treats this ini:
<?php 
/*
[base]
host=localhost
user=testuser
pass=testpass
database=default

[users:base]
database=users

[archive : base]
database=archive
*/
?>
As if it were like this:
<?php
/*
[base]
host=localhost
user=testuser
pass=testpass
database=default

[users:base]
host=localhost
user=testuser
pass=testpass
database=users

[archive : base]
host=localhost
user=testuser
pass=testpass
database=archive
*/
?>

down

Rekam ¶

9 years ago


You may want, in some very special cases, to parse multi-dimensional array with N levels in your ini file. Something like setting[data][config][debug] = true will result in an error (expected "=").

Here's a little function to match this, using dots (customizable).
<?php
function parse_ini_file_multi($file, $process_sections = false, $scanner_mode = INI_SCANNER_NORMAL) {
    $explode_str = '.';
    $escape_char = "'";
    // load ini file the normal way
    $data = parse_ini_file($file, $process_sections, $scanner_mode);
    if (!$process_sections) {
        $data = array($data);
    }
    foreach ($data as $section_key => $section) {
        // loop inside the section
        foreach ($section as $key => $value) {
            if (strpos($key, $explode_str)) {
                if (substr($key, 0, 1) !== $escape_char) {
                    // key has a dot. Explode on it, then parse each subkeys
                    // and set value at the right place thanks to references
                    $sub_keys = explode($explode_str, $key);
                    $subs =& $data[$section_key];
                    foreach ($sub_keys as $sub_key) {
                        if (!isset($subs[$sub_key])) {
                            $subs[$sub_key] = [];
                        }
                        $subs =& $subs[$sub_key];
                    }
                    // set the value at the right place
                    $subs = $value;
                    // unset the dotted key, we don't need it anymore
                    unset($data[$section_key][$key]);
                }
                // we have escaped the key, so we keep dots as they are
                else {
                    $new_key = trim($key, $escape_char);
                    $data[$section_key][$new_key] = $value;
                    unset($data[$section_key][$key]);
                }
            }
        }
    }
    if (!$process_sections) {
        $data = $data[0];
    }
    return $data;
}
?>

The following file:
<?php
/*
[normal]
foo = bar
; use quotes to keep your key as it is
'foo.with.dots' = true

[array]
foo[] = 1
foo[] = 2

[dictionary]
foo[debug] = false
foo[path] = /some/path

[multi]
foo.data.config.debug = true
foo.data.password = 123456
*/
?>

will result in:
<?php
parse_ini_file_multi('file.ini', true);

Array
(
    [normal] => Array
        (
            [foo] => bar
            [foo.with.dots] => 1
        )
    [array] => Array
        (
            [foo] => Array
                (
                    [0] => 1
                    [1] => 2
                )
        )
    [dictionary] => Array
        (
            [foo] => Array
                (
                    [debug] => 
                    [path] => /some/path
                )
        )
    [multi] => Array
        (
            [foo] => Array
                (
                    [data] => Array
                        (
                            [config] => Array
                                (
                                    [debug] => 1
                                )
                            [password] => 123456
                        )
                )
        )
)
?>

down

simon dot riget at gmail dot com ¶

10 years ago


.ini files or JSON file format as it is also known as, are very useful format to store stuff in. Especially large arrays. 

Strangely enough there is this nice function to read the file, but no function to write it.

So here is one.

Use it as:  put_ini_file(string $file, array $array)

<?php 
function put_ini_file($file, $array, $i = 0){
  $str="";
  foreach ($array as $k => $v){
    if (is_array($v)){
      $str.=str_repeat(" ",$i*2)."[$k]".PHP_EOL; 
      $str.=put_ini_file("",$v, $i+1);
    }else
      $str.=str_repeat(" ",$i*2)."$k = $v".PHP_EOL; 
  }
 if($file)
    return file_put_contents($file,$str);
  else
    return $str;
}
?>

down

Justin Hall ¶

16 years ago


This is a simple (but slightly hackish) way of avoiding the character limitations (in values):

<?php
define('QUOTE', '"');
$test = parse_ini_file('test.ini');

echo "<pre>";
print_r($test);
?>

contents of test.ini:

park yesterday = "I (walked) | {to} " QUOTE"the"QUOTE " park yesterday & saw ~three~ dogs!"

output:

<?php
Array
(
    [park yesterday] => I (walked) | {to} "the" park yesterday & saw ~three~ dogs!
)
?>

down

dschnepper at box dot com ¶

7 years ago


The documentation states:
Characters ?{}|&~!()^" must not be used anywhere in the key and have a special meaning in the value.

Here's the results of my experiments on what they mean:

; | is used for bitwise OR
three = 2|3

; & is used for bitwise AND
four = 6&5

; ^ is used for bitwise XOR
five = 3^6

; ~ is used for bitwise negate
negative_two = ~1

; () is used for grouping
seven = (8|7)&(6|5)

; ${...} is used for grabbing values from the environment, or previously defined values.
path = ${PATH}
also = ${five}

; ? I have no guess for
; ! I have no guess for

down

YAPs ¶

6 years ago


This function for save ini files



<?php

function array_to_ini($array,$out="")

{

    $t="";

    $q=false;

    foreach($array as $c=>$d)

    {

        if(is_array($d))$t.=array_to_ini($d,$c);

        else

        {

            if($c===intval($c))

            {

                if(!empty($out))

                {

                    $t.="\r\n".$out." = \"".$d."\"";

                    if($q!=2)$q=true;

                }

                else $t.="\r\n".$d;

            }

            else

            {    

                $t.="\r\n".$c." = \"".$d."\"";

                $q=2;

            }

        }

    }

    if($q!=true && !empty($out)) return "[".$out."]\r\n".$t;

    if(!empty($out)) return  $t;

    return trim($t);

}



function save_ini_file($array,$file)

{

    $a=array_to_ini($array);

    $ffl=fopen($file,"w");

    fwrite($ffl,$a);

    fclose($ffl);

}

?>

down

www.onphp5.com ¶

15 years ago


Looks like in PHP 5.3.0 special characters like \n are extrapolated into real newlines. Gotta use \\n.

down

kieran dot huggins at rogers dot com ¶

20 years ago


Just a quick note for all those running into trouble escaping double quotes:

I got around this by "base64_encode()"-ing my content on the way in to the ini file, and "base64_decode()"-ing on the way out.

Because base64 uses the "=" sign, you will have to encapsulate the entire value in double quotes so the line looks like this:

    varname = "TmlhZ2FyYSBGYWxscywgT04="

When base64'd, your strings will retain all \n, \t...etc...  URL's retain everything perfectly :-)

I hope some of you find this useful!

Cheers, Kieran

down

goulven.ch AT gmail DOT com ¶

15 years ago


Warning: parse_ini_files cannot cope with values containing the equal sign (=).

The following function supports sections, comments, arrays, and key-value pairs outside of any section.
Beware that similar keys will overwrite one another (unless in different sections).

<?php
function parse_ini ( $filepath ) {
    $ini = file( $filepath );
    if ( count( $ini ) == 0 ) { return array(); }
    $sections = array();
    $values = array();
    $globals = array();
    $i = 0;
    foreach( $ini as $line ){
        $line = trim( $line );
        // Comments
        if ( $line == '' || $line{0} == ';' ) { continue; }
        // Sections
        if ( $line{0} == '[' ) {
            $sections[] = substr( $line, 1, -1 );
            $i++;
            continue;
        }
        // Key-value pair
        list( $key, $value ) = explode( '=', $line, 2 );
        $key = trim( $key );
        $value = trim( $value );
        if ( $i == 0 ) {
            // Array values
            if ( substr( $line, -1, 2 ) == '[]' ) {
                $globals[ $key ][] = $value;
            } else {
                $globals[ $key ] = $value;
            }
        } else {
            // Array values
            if ( substr( $line, -1, 2 ) == '[]' ) {
                $values[ $i - 1 ][ $key ][] = $value;
            } else {
                $values[ $i - 1 ][ $key ] = $value;
            }
        }
    }
    for( $j=0; $j<$i; $j++ ) {
        $result[ $sections[ $j ] ] = $values[ $j ];
    }
    return $result + $globals;
}
?>

Example usage:
<?php
$stores = parse_ini('stores.ini');
print_r( $stores );
?>

An example ini file:
<?php
/*
;Commented line start with ';'
global_value1 = a string value
global_value1 = another string value

; empty lines are discarded
[Section1]
key = value
; whitespace around keys and values is discarded too
otherkey=other value
otherkey=yet another value
; this key-value pair will overwrite the former.
*/
?>

down

info () gaj ! design ¶

6 years ago


Not mentioned in the documentation, this function acts like include:

"Files are included based on the file path given or, if none is given, the include_path specified. If the file isn't found in the include_path, include will finally check in the calling script's own directory and the current working directory before failing."

(At least for PHP 7; have not checked PHP 5.)

down

jbricci at ya-right dot com ¶

7 years ago


This core function won't handle ini key[][] = value(s), (multidimensional arrays), so if you need to support that kind of setup you will need to write your own function. one way to do it is to convert all the key = value(s) to array string [key][][]=value(s), then use parse_str() to convert all those [key][][]=value(s) that way you just read the ini file line by line, instead of doing crazy foreach() loops to handle those (multidimensional arrays) in each section, example...

ini file...... config.php

<?php

; This is a sample configuration file
; Comments start with ';', as in php.ini

[first_section]
one = 1
five = 5
animal = BIRD

[second_section]
path = "/usr/local/bin"
URL = "http://www.example.com/~username"

[third_section]
phpversion[] = "5.0"
phpversion[] = "5.1"
phpversion[] = "5.2"
phpversion[] = "5.3"

urls[svn] = "http://svn.php.net"
urls[git] = "http://git.php.net"

[fourth_section]

a[][][] = b
a[][][][] = c
a[test_test][][] = d
test[one][two][three] = true

?>

echo parse_ini_file ( "C:\\services\\www\\docs\\config.php" );

results in...

// PHP Warning:  syntax error, unexpected TC_SECTION, expecting '=' line 27 -> a[][][] = b

Here it simple function that handles (multidimensional arrays) without looping each key[][]= value(s)

<?php

function getIni ( $file, $sections = FALSE )
{
    $return = array ();

    $keeper = array ();

    $config = fopen ( $file, 'r' );

    while ( ! feof ( $config ) )
    { 
        $line = trim ( fgets ( $config, 1024 ) );

        $line = ( $line == '' ) ? ' ' : $line;

        switch ( $line{0} )
        {
            case ' ':
            case '#':
            case '/':
            case ';':
            case '<':
            case '?':

            break;

            case '[':

            if ( $sections )
            {
                $header = 'config[' . trim ( substr ( $line, 1, -1 ) ) . ']';
            }
            else
            {
                $header = 'config';
            }

            break;

            default:

            $kv = array_map ( 'trim', explode ( '=', $line ) );

            $kv[0] = str_replace ( ' ', '+', $kv[0] );

            $kv[1] = str_replace ( ' ', '+', $kv[1] );

            if ( ( $pos = strpos ( $kv[0], '[' ) ) !== FALSE )
            {
                $kv[0] = '[' . substr ( $kv[0], 0, $pos ) . ']' . substr ( $kv[0], $pos );
            }
            else
            {
                $kv[0] = '[' . $kv[0] . ']';
            }

            $bt = strtolower ( $kv[1] );

            if ( in_array ( $bt, array ( 'true', 'false', 'on', 'off' ) ) )
            {
                $kv[1] = ( $bt == 'true' || $bt == 'on' ) ? TRUE : FALSE;
            }

            $keeper[] = $header . $kv[0] . '=' . $kv[1];
        }
    }

    fclose ( $config );

    parse_str ( implode ( '&', $keeper ), $return );

    return $return['config'];
}

// usage...

$sections = TRUE;

print_r ( $config->getIni ( "C:\\services\\www\\docs\\config.php" ),  $sections );

?>

down

dimk at pisem dot net ¶

17 years ago


Class to access ini values at format "section_name.property", for example $myconf->get("system.name") returns a property "name" in section "system":



<?php

class Settings {



var $properties = array();



    function Settings() {

        $this->properties = parse_ini_file(_SETTINGS_FILE, true);

    }



    function get($name) {

        if(strpos($name, ".")) {

            list($section_name, $property) = explode(".", $name);

            $section =& $this->properties[$section_name];

            $name = $property;

        } else {

            $section =& $properties;

        }



        if(is_array($section) && isset($section[$name])) {

            return $section[$name];

        }

        return false;

    }



}

?>

down

waikeatNOSPAM at archerlogic dot com ¶

19 years ago


I found that this function will not work on remote files.

I tried 



$someArray = parse_ini_file("http://www.example.com/setting.ini");



and it reports



Cannot Open 'http://www.example.com/setting.ini' for reading ...

down

Rubn Martnez ¶

4 years ago


The parse_ini_file function does have trouble loading valid Windows ini files like, for example, nternet shortcuts (.url files).

This is due to the function reading the URLs as a value, and failing when it finds that valid URL characters like '=' appear unescaped or the value unquoted as a whole. Since Windows does not escape them anyway, the solution is to scan it in raw mode, where it will read unparsed the value after the first '='. Since = only appears in URLs with parameters, this mistake may is not be obvious at a first glance.

An example

<?php

$links = array();

// ...

$files = scandir($directory);
foreach( $files as $filename )
{
    if (strToLower(pathinfo($filename, PATHINFO_EXTENSION)) === 'url')
    {
        $shortcut = parse_ini_file( $directory.DIRECTORY_SEPARATOR.$filename, true,  INI_SCANNER_RAW);
        if ($shortcut === false) die('Syntax Error');
        $url = $shortcut['InternetShortcut']['URL'];
        $links []= $url;
    }
}

?>

down

yarco dot w at gmail dot com ¶

15 years ago


parse_ini_file can't deal with const which cancate a string. For example, if test.ini file is

classPath = ROOT/lib

If you:
<?php
define('ROOT', dirname(__FILE__));

$buf = parse_ini_file('test.ini');
?>

const ROOT would't be parsed.

But my version could work find.

<?php
// array parse_ini_file ( string $filename [, bool $process_sections] )
function parse_ini($filename, $process_sections = false)
{
  function replace_process(& $item, $key, $consts)
  {
    $item = str_replace(array_keys($consts), array_values($consts), $item);
  }

  $buf = get_defined_constants(true); // PHP version > 5.0
  $consts = $buf['user'];
  $ini = parse_ini_file($filename, $process_sections);

  array_walk_recursive($ini, 'replace_process', $consts);
  return $ini;
}

define('ROOT', '/test');
print_r(parse_ini(dirname(__FILE__).'/test.ini'));

?>

add a note