php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #47703 ini file syntax not well documented
Submitted: 2009-03-18 07:17 UTC Modified: 2010-01-14 07:47 UTC
Votes:7
Avg. Score:4.1 ± 0.8
Reproduced:7 of 7 (100.0%)
Same Version:7 (100.0%)
Same OS:6 (85.7%)
From: ctoomey at yahoo-inc dot com Assigned: kalle
Status: Closed Package: Documentation problem
PHP Version: Irrelevant OS: *
Private report: No CVE-ID:
 [2009-03-18 07:17 UTC] ctoomey at yahoo-inc dot com
Description:
------------
The legal syntax for PHP ini files (both php.ini and those parsed by parse_ini_file()) is not really fully described anywhere in the manual. It'd be helpful to have that documented say on http://www.php.net/manual/en/configuration.file.php, and then have the parse_ini_file() and parse_ini_string() documentation pages link to that syntax documentation.

There are bits and pieces of documentation, like in the comments of the php.ini in Example 1 on the above page, and in the comments of the latest php.ini in CVS.  Also, in the page for parse_ini_file(), it documents the set of illegal words and characters for keys.  It also says certain characters have "special meaning" in values, but doesn't say what those meanings are / what they can be used for in values.

The lack of precise syntax documentation makes it hard to predict how parse_ini_file() will actually treat a given ini file line (as an error, as ok but with some odd value interpretation, or just silently ignore).  The following examples illustrate; these are using 5.3.0-beta2 snapshot on Windows.

			value of key "x" 
ini line		from parse_ini_file()
--------		---------------------
x = 'foo' ;blah		foo
	;; Single quotes are ok too?

# x = blah		N/A
	;; No keys parsed out for this line, and no syntax
	;; error reported -- is "#" a comment char.?

x = "foo" # test	foo# test
	;; Hmm, legal to have text after double quoted value
	;; and gets oddly appended to value.
	;; And no, guess "#" ISN'T a comment char.

foo bar car		N/A
	;; No keys parsed out for this line, and no syntax
	;; error reported.  What happened to it?


Reproduce code:
---------------
The above was done by varying the contents of test.ini and then running the following command at the windows prompt:

% php -r "print_r(parse_ini_file('test.ini'));"


Expected result:
----------------
For most of the examples I expected syntax errors to be reported.  But the larger issue is that without documentation of the legal syntax of ini files, PHP users don't really know what's legal and what's not.


Actual result:
--------------
See above.


Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2009-08-07 14:56 UTC] jani@php.net
In PHP 5.3 single quotes allow putting anything inside them, except single quotes. In PHP 5.2 they have no meaning and are included in the value.

# Is comment in PHP 5.3 but not in 5.2, and in 5.3 it's already deprecated and using it causes a deprecated warning if error_reporting is appropriate. And it's only comment when it's not used after =

Keys without values are just ignored. Only when there is = char, you get it into the array.

 [2009-08-07 14:58 UTC] jani@php.net
See also bug #44575
 [2010-01-13 01:02 UTC] svn@php.net
Automatic comment from SVN on behalf of kalle
Revision: http://svn.php.net/viewvc/?view=revision&revision=293473
Log: Fixed bug #47703 (ini file syntax not well documented)
 [2010-01-13 01:04 UTC] kalle@php.net
This bug has been fixed in the documentation's XML sources. Since the
online and downloadable versions of the documentation need some time
to get updated, we would like to ask you to be a bit patient.

Thank you for the report, and for helping us make our documentation better.

Documented these new syntax options on parse_ini_file(), I don't think we should add a new appendix just for the ini syntax.
 [2010-01-14 07:47 UTC] ctoomey at yahoo-inc dot com
Cool, thanks.
 
PHP Copyright © 2001-2014 The PHP Group
All rights reserved.
Last updated: Mon Apr 21 02:02:11 2014 UTC