eZINI Class Reference
[Utility classes]

Reads and writes .ini style configuration files. More...

Public Member Functions
	appendOverrideDir ($dir, $globalDir=false, $identifier=false)
	assign ($blockName, $varName, &$variable)
	eZINI ($fileName, $rootDir="", $useTextCodec=null, $useCache=null, $useLocalOverrides=null, $directAccess=false, $addArrayDefinition=false)
&	fetchFromFile ($fileName, $useTextCodec=null)
	filename ()
&	findSettingPlacement ($path)
	getNamedArray ()
&	group ($blockName)
&	groupPlacements ()
&	groups ()
	hasGroup ($blockName)
	hasSection ($sectionName)
	hasVariable ($blockName, $varName)
	isNoCacheAdviced ()
	isSettingReadOnly ($fileName=false, $blockName=false, $settingName=false)
	isVariableModified ($blockName, $varName)
	load ($reset=true)
	loadPlacement ($reset=true)
	overrideDirs ()
	prependOverrideDir ($dir, $globalDir=false, $identifier=false)
	readOnlySettingsCheck ()
	removeGroup ($blockName)
	removeSetting ($blockName, $settingName)
	reset ()
	resetCache ()
	rootDir ()
	save ($fileName=false, $suffix=false, $useOverride=false, $onlyModified=false, $useRootDir=true, $resetArrays=false, $encapsulateInPHP=true)
	setGroups ($groupArray)
	setReadOnlySettingsCheck ($readOnly=true)
	settingType ($settingValue)
	setVariable ($blockName, $variableName, $variableValue)
	variable ($blockName, $varName)
&	variableArray ($blockName, $varName)
	variableMulti ($blockName, $varNames, $signatures=array())
Static Public Member Functions
&	create ($fileName="site.ini", $rootDir="settings", $useTextCodec=null, $useCache=null, $useLocalOverrides=null)
	exists ($fileName="site.ini", $rootDir="settings")
&	instance ($fileName="site.ini", $rootDir="settings", $useTextCodec=null, $useCache=null, $useLocalOverrides=null, $directAccess=false, $addArrayDefinition=false)
	isCacheEnabled ()
	isDebugEnabled ()
	isLoaded ($fileName="site.ini", $rootDir="settings", $useLocalOverrides=null)
	isTextCodecEnabled ()
	parameterSet ($fileName= 'site.ini', $rootDir= 'settings', &$section, &$parameter)
	resetGlobals ($fileName="site.ini", $rootDir="settings", $useLocalOverrides=null)
	setIsCacheEnabled ($cache)
	setIsDebugEnabled ($debug)
	setIsTextCodecEnabled ($codec)
Private Member Functions
	findInputFiles (&$inputFiles, &$iniFile)
	loadCache ($reset=true, $placement=false)
	parse ($inputFiles=false, $iniFile=false, $reset=true, $placement=false)
	parseFile ($file, $placement=false)
	saveCache ($cachedDir, $cachedFile, $data)
Private Attributes
	$AddArrayDefinition
	If `true` empty element will be created in the beginning of array if it is defined in this ini file.
	$BlockValues
	Variable to store the ini file values.
	$BlockValuesPlacement
	Variable to store the setting placement (which file is the setting in).
	$CacheFile
	Stores the path and filename of the value cache file.
	$Charset
	$Codec
	Variable to store the textcodec.
	$DirectAccess
	If `true` then all file loads are done directly on the filename.
	$FileName
	Stores the filename.
	$LocalOverrideDirArray
	Contains the override dirs, if in local mode.
	$ModifiedBlockValues
	Variable to store whether variables are modified or not.
	$PlacementCacheFile
	Stores the path and filename of the placement cache file.
	$ReadOnlySettingsCheck = true
	If `true` eZINI will check each setting (before saving) for correspondence of settings in site.ini[eZINISetting].ReadonlySettingList.
	$RootDir
	The root of all ini files.
	$UseCache
	true if cache should be used
	$UseLocalOverrides
	true if the overrides should only be changed locally
	$UseTextCodec
	Whether to use the text codec when reading the ini file or not.

Detailed Description

Reads and writes .ini style configuration files.

The most common way of using it is.

  // include the file
  include_once( "classes/ezinifile.php" );

  $ini = eZINI::instance( "site.ini" );

  // get a variable from the file.
  $iniVar = $ini->variable( "BlockName", "Variable" );

The default ini file is site.ini but others can be passed to the instance() function among with some others. It will create one unique instance for each ini file and rootdir, this means that the next time instance() is used with the same parameters the same object will be returned and no new parsing is required.

The class will by default try to create a cache file in var/cache/ini, however to change this behaviour the static setIsCacheEnabled() function can be used, or use the $useCache parameter in instance() for setting this for one object only.

The class will also handle charset conversion using eZTextCodec, to turn this behaviour off use the static setIsTextCodecEnabled() function or set the $useTextCodec parameter in instance() for a per object basis setting.

Normally the eZINI class will not give out much information about what it's doing, it's only when errors occur that you'll see this. To enable internal debugging use the static setIsDebugEnabled() function. The class will then give information about which files are load, if cache files are used and when cache files are written.

Definition at line 80 of file ezini.php.

Member Function Documentation

eZINI::appendOverrideDir	(	$	dir,
		$	globalDir = `false`,
		$	identifier = `false`
	)

Appends the override directory $dir to the override directory list.

Definition at line 996 of file ezini.php.

eZINI::assign	(	$	blockName,
		$	varName,
		&$	variable
	)

Reads a variable from the ini file and puts it in the parameter $variable.

Note:: $variable is not modified if the variable does not exist

Definition at line 1033 of file ezini.php.

& eZINI::create	(	$	fileName = `"site.ini"`,
		$	rootDir = `"settings"`,
		$	useTextCodec = `null`,
		$	useCache = `null`,
		$	useLocalOverrides = `null`
	)			`[static]`

Similar to instance() but will always create a new copy.

Definition at line 1400 of file ezini.php.

eZINI::exists	(	$	fileName = `"site.ini"`,
		$	rootDir = `"settings"`
	)			`[static]`

Returns:: true if the INI file $fileName exists in the root dir $rootDir. $fileName defaults to site.ini and rootDir to settings.

Definition at line 229 of file ezini.php.

Referenced by eZLocale::countryFile(), eZLocale::languageFile(), eZLocale::localeFile(), and parameterSet().

eZINI::eZINI	(	$	fileName,
		$	rootDir = `""`,
		$	useTextCodec = `null`,
		$	useCache = `null`,
		$	useLocalOverrides = `null`,
		$	directAccess = `false`,
		$	addArrayDefinition = `false`
	)

Initialization of object;

Definition at line 85 of file ezini.php.

Referenced by create(), fetchFromFile(), and instance().

& eZINI::fetchFromFile	(	$	fileName,
		$	useTextCodec = `null`
	)

Fetches the ini file $fileName and returns the INI object for it.

Note:: This will not use the override system or read cache files, this is a direct fetch from one file.

Definition at line 1390 of file ezini.php.

Referenced by eZFilePackageHandler::install().

eZINI::filename ( )

Returns:: the filename.

Definition at line 121 of file ezini.php.

Referenced by setVariable().

eZINI::findInputFiles	(	&$	inputFiles,
		&$	iniFile
	)			`[private]`

Looks trough all known settings and override folders to find relevant INI files. The result is a list with expanded paths to the files.

Returns:: the expanded file list.

Definition at line 284 of file ezini.php.

Referenced by loadCache(), and parse().

& eZINI::findSettingPlacement ( $ path )

Definition at line 1232 of file ezini.php.

eZINI::getNamedArray ( )

Returns BlockValues, which is a nicely named Array

Definition at line 1344 of file ezini.php.

& eZINI::group ( $ blockName )

Fetches a variable group and returns it as an associative array.

Definition at line 1157 of file ezini.php.

& eZINI::groupPlacements ( )

Fetches all defined placements for every setting and returns them as an associative array

Definition at line 1223 of file ezini.php.

& eZINI::groups ( )

Fetches all defined groups and returns them as an associative array

Definition at line 1215 of file ezini.php.

eZINI::hasGroup ( $ blockName )

Checks if group $blockName is set. Returns true if the group exists, false if not.

Definition at line 1149 of file ezini.php.

eZINI::hasSection ( $ sectionName )

Check if a block/section is set. Returns true if the section/block is set, false if not

Definition at line 1108 of file ezini.php.

eZINI::hasVariable	(	$	blockName,
		$	varName
	)

Checks if a variable is set. Returns true if the variable exists, false if not.

Definition at line 1100 of file ezini.php.

Referenced by assign().

& eZINI::instance	(	$	fileName = `"site.ini"`,
		$	rootDir = `"settings"`,
		$	useTextCodec = `null`,
		$	useCache = `null`,
		$	useLocalOverrides = `null`,
		$	directAccess = `false`,
		$	addArrayDefinition = `false`
	)			`[static]`

Returns the current instance of the given .ini file If $useLocalOverrides is set to true you will get a copy of the current overrides, but changes to the override settings will not be global. Direct access is for accessing the filename directly in the specified path. .append and .append.php is automaticly added to filename

Note:: Use create() if you need to get a unique copy which you can alter.

Definition at line 1369 of file ezini.php.

eZINI::isCacheEnabled ( ) [static]

Returns:: true if INI cache is enabled globally, the default value is true. Change this setting with setIsCacheEnabled.

Definition at line 131 of file ezini.php.

Referenced by eZINI().

eZINI::isDebugEnabled ( ) [static]

Returns:: true if debugging of internals is enabled, this will display which files are loaded and when cache files are created. Set the option with setIsDebugEnabled().

Definition at line 168 of file ezini.php.

Referenced by appendOverrideDir(), loadCache(), parseFile(), prependOverrideDir(), and saveCache().

eZINI::isLoaded	(	$	fileName = `"site.ini"`,
		$	rootDir = `"settings"`,
		$	useLocalOverrides = `null`
	)			`[static]`

Returns:: true if the ini file $fileName has been loaded yet.

Definition at line 1353 of file ezini.php.

eZINI::isNoCacheAdviced ( )

Returns:: true if cache is not adviced to be used.

Note:: The no-cache-adviced flag might not be modified in time for site.ini and some other important files to be affected.

Definition at line 142 of file ezini.php.

Referenced by eZINI().

eZINI::isSettingReadOnly	(	$	fileName = `false`,
		$	blockName = `false`,
		$	settingName = `false`
	)

Definition at line 1170 of file ezini.php.

Referenced by setGroups(), and setVariable().

eZINI::isTextCodecEnabled ( ) [static]

Returns:: true if textcodecs is to be used, this will use the eZTextCodec class in the eZI18N library for text conversion. Set the option with setIsTextCodecEnabled().

Definition at line 190 of file ezini.php.

Referenced by eZINI().

eZINI::isVariableModified	(	$	blockName,
		$	varName
	)

Returns:: true if the variable $varName in group $blockName has been modified.

Definition at line 1116 of file ezini.php.

eZINI::load ( $ reset = true )

Tries to load the ini file specified in the constructor or instance() function. If cache files should be used and a cache file is found it loads that instead. Set $reset to false if you don't want to reset internal data.

Definition at line 249 of file ezini.php.

Referenced by eZINI().

eZINI::loadCache	(	$	reset = `true`,
		$	placement = `false`
	)			`[private]`

Will load a cached version of the ini file if it exists, if not it will parse the original file and create the cache file.

Definition at line 353 of file ezini.php.

Referenced by load(), and loadPlacement().

eZINI::loadPlacement ( $ reset = true )

Tries to load the ini file placement specified in the constructor or instance() function. If cache files should be used and a cache file is found it loads that instead. Set $reset to false if you don't want to reset internal data.

Definition at line 266 of file ezini.php.

Referenced by groupPlacements().

eZINI::overrideDirs ( )

Returns:: the override directories, if no directories has been set "override" is returned.

The override directories are returned as an array of arrays. The first value in the array is the override directory, the second is a boolean which defines if the directory is relative to the rootDir() or not. If the second value is false the override dir is relative, true means that the override dir is relative to the eZ publish root directory. The third value of the array will contain the identifier of the override, if it exists. Identifiers are useful if you want to overwrite the current override setting.

Definition at line 943 of file ezini.php.

Referenced by findInputFiles().

eZINI::parameterSet	(	$	fileName = `'site.ini'`,
		$	rootDir = `'settings'`,
		&$	section,
		&$	parameter
	)			`[static]`

Check wether a specified parameter in a specified section is set in a specified file

Parameters:

	filename	(optional)
	directory	(optional)
	section	name
	parameter	name

Returns:: true if the the parameter is set.

Definition at line 215 of file ezini.php.

Referenced by eZIniSettingType::initializeObjectAttribute(), and eZIniSettingType::objectAttributeContent().

eZINI::parse	(	$	inputFiles = `false`,
		$	iniFile = `false`,
		$	reset = `true`,
		$	placement = `false`
	)			`[private]`

Parses either the override ini file or the standard file and then the append override file if it exists.

Definition at line 525 of file ezini.php.

Referenced by load(), loadCache(), and loadPlacement().

eZINI::parseFile	(	$	file,
		$	placement = `false`
	)			`[private]`

Will parse the INI file and store the variables in the variable $this->BlockValues

Definition at line 546 of file ezini.php.

Referenced by parse().

eZINI::prependOverrideDir	(	$	dir,
		$	globalDir = `false`,
		$	identifier = `false`
	)

Appends the override directory $dir to the override directory list. If global dir is set top

Definition at line 959 of file ezini.php.

eZINI::readOnlySettingsCheck ( )

Returns:: ReadonlySettingsCheck variable.

Definition at line 1417 of file ezini.php.

Referenced by isSettingReadOnly().

eZINI::removeGroup ( $ blockName )

Removes the group and all it's settings from the .ini file

Definition at line 1198 of file ezini.php.

Referenced by removeSetting().

eZINI::removeSetting	(	$	blockName,
		$	settingName
	)

Definition at line 1204 of file ezini.php.

eZINI::reset ( )

Removes all read data from .ini files.

Definition at line 916 of file ezini.php.

Referenced by loadCache(), and parse().

eZINI::resetCache ( )

the cache file if it exists.

Definition at line 696 of file ezini.php.

eZINI::resetGlobals	(	$	fileName = `"site.ini"`,
		$	rootDir = `"settings"`,
		$	useLocalOverrides = `null`
	)			`[static]`

Definition at line 1425 of file ezini.php.

eZINI::rootDir ( )

Returns:: the root directory from where all .ini and override files are read.

This is set by the instance() or eZINI() functions.

Definition at line 927 of file ezini.php.

eZINI::save	(	$	fileName = `false`,
		$	suffix = `false`,
		$	useOverride = `false`,
		$	onlyModified = `false`,
		$	useRootDir = `true`,
		$	resetArrays = `false`,
		$	encapsulateInPHP = `true`
	)

Saves the file to disk. If filename is given the file is saved with that name if not the current name is used. If $useOverride is true then the file will be placed in the override directory, if $useOverride is "append" it will append ".append" to the filename.

Definition at line 711 of file ezini.php.

eZINI::saveCache	(	$	cachedDir,
		$	cachedFile,
		$	data
	)			`[private]`

Stores the content of the INI object to the cache file $cachedFile.

Definition at line 482 of file ezini.php.

Referenced by loadCache().

eZINI::setGroups ( $ groupArray )

Sets all groups overwriting the current values

Definition at line 1288 of file ezini.php.

eZINI::setIsCacheEnabled ( $ cache ) [static]

Sets whether caching is enabled for INI files or not. This setting is global and can be overriden in the instance() function.

Definition at line 157 of file ezini.php.

eZINI::setIsDebugEnabled ( $ debug ) [static]

Sets whether internal debugging is enabled or not.

Definition at line 179 of file ezini.php.

eZINI::setIsTextCodecEnabled ( $ codec ) [static]

Sets whether textcodec conversion is enabled or not.

Definition at line 201 of file ezini.php.

eZINI::setReadOnlySettingsCheck ( $ readOnly = true )

Sets ReadonlySettingsCheck variable.

Definition at line 1409 of file ezini.php.

eZINI::settingType ( $ settingValue )

Definition at line 1265 of file ezini.php.

eZINI::setVariable	(	$	blockName,
		$	variableName,
		$	variableValue
	)

Sets multiple variables from the array $variables.

Parameters:

$variables

Contains an associative array with groups as first key, variable names as second key and variable values as values.

     $ini->setVariables( array( 'SiteSettings' => array( 'SiteName' => 'mysite',
                                                         'SiteURL' => 'http://mysite.com' ) ) );
     \encode
     \sa setVariable
    */
    function setVariables( $variables )
    {
        foreach ( $variables as $blockName => $blockVariables )
        {
            foreach ( $blockVariables as $variableName => $variableValue )
            {
                $this->setVariable( $blockName, $variableName, $variableValue );
            }
        }
    }

    /*!
     Sets an INI file variable.
     \code
     $ini->setVariable( 'SiteSettings', 'SiteName', 'mysite' );

See also:: setVariables

Definition at line 1332 of file ezini.php.

eZINI::variable	(	$	blockName,
		$	varName
	)

Reads a variable from the ini file. false is returned if the variable was not found.

Definition at line 1046 of file ezini.php.

Referenced by assign(), and variableArray().

& eZINI::variableArray	(	$	blockName,
		$	varName
	)

Reads a variable from the ini file. The variable will be returned as an array. ; is used as delimiter.

Definition at line 1126 of file ezini.php.

eZINI::variableMulti	(	$	blockName,
		$	varNames,
		$	signatures = `array()`
	)

Reads multiple variables from the ini file. false is returned if the variable was not found.

Definition at line 1063 of file ezini.php.

Member Data Documentation

eZINI::$AddArrayDefinition [private]

If true empty element will be created in the beginning of array if it is defined in this ini file.

Definition at line 1475 of file ezini.php.

eZINI::$BlockValues [private]

Variable to store the ini file values.

Definition at line 1439 of file ezini.php.

eZINI::$BlockValuesPlacement [private]

Variable to store the setting placement (which file is the setting in).

Definition at line 1442 of file ezini.php.

eZINI::$CacheFile [private]

Stores the path and filename of the value cache file.

Definition at line 1457 of file ezini.php.

eZINI::$Charset [private]

The charset of the ini file

Definition at line 1433 of file ezini.php.

eZINI::$Codec [private]

Variable to store the textcodec.

Definition at line 1436 of file ezini.php.

eZINI::$DirectAccess [private]

If true then all file loads are done directly on the filename.

Definition at line 1472 of file ezini.php.

eZINI::$FileName [private]

Stores the filename.

Definition at line 1448 of file ezini.php.

eZINI::$LocalOverrideDirArray [private]

Contains the override dirs, if in local mode.

Definition at line 1469 of file ezini.php.

eZINI::$ModifiedBlockValues [private]

Variable to store whether variables are modified or not.

Definition at line 1445 of file ezini.php.

eZINI::$PlacementCacheFile [private]

Stores the path and filename of the placement cache file.

Definition at line 1460 of file ezini.php.

eZINI::$ReadOnlySettingsCheck = true [private]

If true eZINI will check each setting (before saving) for correspondence of settings in site.ini[eZINISetting].ReadonlySettingList.

Definition at line 1478 of file ezini.php.

eZINI::$RootDir [private]

The root of all ini files.

Definition at line 1451 of file ezini.php.

eZINI::$UseCache [private]

true if cache should be used

Definition at line 1463 of file ezini.php.

eZINI::$UseLocalOverrides [private]

true if the overrides should only be changed locally

Definition at line 1466 of file ezini.php.

eZINI::$UseTextCodec [private]

Whether to use the text codec when reading the ini file or not.

Definition at line 1454 of file ezini.php.

The documentation for this class was generated from the following file:

ezini.php

eZINI Class Reference [Utility classes]

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Function Documentation

Member Data Documentation

eZINI Class Reference
[Utility classes]