The Registry class provides easy access to the Windows registry. You can create, update or delete registry values,
as well as create or delete registry keys.
Most of the Registry functions accept as their first parameter a registry root key, which can be one of the following :
- Registry::HKEY_CLASSES_ROOT (or HKCR)
- Registry::HKEY_CURRENT_USER (or HKCU)
- Registry::HKEY_LOCAL_MACHINE (or HKLM)
- Registry::HKEY_USERS
- Registry::HKEY_PERFORMANCE_DATA
- Registry::HKEY_PERFORMANCE_TEXT
- Registry::HKEY_PERFORMANCE_NLSTEXT
- Registry::HKEY_CURRENT_CONFIG (or HKCC)
- Registry::HKEY_DYN_DATA
No means are currently provided to retrieve a handle from any other existing registry key.
Almost all methods use the StdRegProv WMI interface, which assumes that you already know the type of the underlying registry
values you are manipulating.
If you want a little bit more freedom when reading or updating registry values, use the
GetValue() /
SetValue() methods,
which do not require you to specify an explicit value type. However, the number of available value types is restricted when compared to
the Registry WMI interface.
Registry keys do not include the root key when calling the Registry class methods, since it is specified as a separate parameter.
Both slashes and backslashes can be used ; thus, the key
'TestKey/subkey' is the same as
'TestKey\subkey'.
Regarding key paths, some provisions have been made to perform automatic inline substitutions. The origin of this came from the day I tried
to retrieve Visual Studio settings for some reason ; it appeared that those settings, on 64-bit platforms, were only accessible from a subkey
named
Wow6432Node, and not from the classic
HKLM/Microsoft/Visual Studio/* registry key, where access rights were refused.
To handle such cases, you can specify the
{OsArchitecture} keyword (enclosed in curly braces), and it will be replaced by the
appropriate subkey name. For example :
Software/{OsArchitecture}/SomeSoftware
will give, on 64-bits platforms :
Software/Wow6432Node/SomeSoftware
and, on 32-bits platforms :
Software/SomeSoftware
Note that the extra slashes are removed.
After calling any registry access method, the
GetLastError() method can be called to retrieve the Windows error codeof the last
API result. Zero means everything is ok.
Creation/deletion
CreateKey ( $root, $keypath )
Creates a registry key.
$root is one of the
Registry::HKEY_* constants.
$keypath is the key to be created. It can include as many subkeys as you want, since Windows will recursively
create them if they do not exist.
DeleteKey ( $root, $keypath )
Deletes a registry key.
$root is one of the
Registry::HKEY_* constants.
$keypath is the key to be deleted.
The key won't be deleted if it contains subkeys or values. Note that, for security reasons, I chosed not to implement
a recursive delete, although it would be really simple.
DeleteValue ( $root, $keypath, $key_value )
Deletes the specified registry value.
Setting key values
SetBinaryValue ( $root, $keypath, $value_name, $value )
Creates or updates the specified binary value
$value_name.
$value is a string that can hold any arbitrary data.
SetBinaryValueFromHexString ( $root, $keypath, $value_name, $value )
Creates or updates the specified binary value
$value_name.
SetBinaryValueFromHexString() is similar to
SetBinaryValue(), except that the
$value parameter must be a string of hexadecimal digits.
If the supplied string has an odd number of hexadecimal digits, the last digit will be used for the high nibble of the last byte.
SetDWORDValue ( $root, $keypath, $value_name, $value )
Creates or updates the specified DWORD value
$value_name.
SetExpandedStringValue ( $root, $keypath, $value_name, $value )
Creates or updates the specified "expand" string value
$value_name.
A registry value of type REG_EXPAND_SZ is like a REG_SZ one, except that references to environment variables
(such as %WINDIR%) will be expanded when the value is retrieved.
SetMultiStringValue ( $root, $keypath, $value_name, $values )
Creates or updates the specified multi-string value
$value_name.
The
$values parameter can be either an array of strings or a single string value.
Multi-string values are returned as array of strings when retrieved from the registry.
SetQWORDValue ( $root, $keypath, $value_name, $value )
Creates or updates the specified QWORD value
$value_name.
Note that values greater than PHP_INT_MAX will be converted to doubles.
SetStringValue ( $root, $keypath, $value_name, $value )
Creates or updates the specified string value
$value_name.
SetValue ( $root, $keypath, $value_name, $value, $value_type )
Creates or updates the specified value
$value_name. This method uses the WShell object.
The
$value_type parameter can be one of the
REG_SZ, REG_EXPAND_SZ, REG_DWORD or
REG_BINARY constants (other registry value types are not supported).
Note that the
REG_BINARY type only supports one DWORD value.
Retrieving key values
GetBinaryValue ( $root, $keypath, $value_name )
Retrieves the specified binary registry value, as a string of hexadecimal digits.
GetDWORDValue ( $root, $keypath, $value_name )
Retrieves the specified DWORD registry value, as an integer value.
GetExpandedStringValue ( $root, $keypath, $value_name )
Retrieves the specified string value, expanding environment variable references.
(for example, a value of '%WINDIR\Something' will expand to 'C:\Windows\Something').
GetMultiStringValue ( $root, $keypath, $value_name )
Retrieves the specified multi-string registry value, as an array of strings.
GetQWORDValue ( $root, $keypath, $value_name )
Retrieves the specified QWORD registry value, as an integer value on true 64-bit implementations, or
as a double, on Windows (as of PHP 5.6).
GetStringValue ( $root, $keypath, $value_name )
Retrieves the specified string registry value.
GetValue ( $root, $keypath, $value_name )
Retrieves the specified registry value.
Only the
REG_SZ, REG_EXPAND_SZ, REG_DWORD or
REG_BINARY registry value types are
supported.
Enumerating keys and values
EnumKeys ( $root, $keypath )
Retrieves the list of all subkeys in
$keypath and returns them as an array of strings.
If
$keypath is null or unspecified, the keys that are directly under
$root will be returned.
EnumValues ( $root, $keypath, $value_names_only = true )
Retrieves the list of all value names in
$keypath and returns them as an array of strings.
If the
$value_names_only parameter is false, the returned value will be an associative array,
whose keys are the value names and whose elements are the value types (
REG_* constants).
EnumValuesEx ( $root, $keypath )
Retrieves the list of all values in
$keypath and returns an array of RegistryValue objects.