Schema caching
Net_LDAP2s schema caching facility
Net_LDAP2 features an easy schema caching facility. Caching the schema can gain some performance, especially with slow servers or connections. The facility works with an plugin object that must be passed to Net_LDAP2s registerSchemaCache() method. The cache object can be registered (or unregistered) at any time, but of course it is the best time right after initializing Net_LDAP2.
Enabling/disabling Net_LDAP2s schema caching facility
<?php
// registering a valid schema cache object is enough to enable the caching facility:
$ldap->registerSchemaCache($myCacheObject);
// unregistering is easy too: just supply null as schema cache object:
$ldap->registerSchemaCache(null);
?>
The object that gets passed to registerSchemaCache() must implement the Net_LDAP2_SchemaCache interface which demands two methods. Initialisation of the cache object is dependent on the class itself but should be handled inside the cache class constructor, however this may vary. Please refer to the cache class documentation for those details.
| Method | Parameter | Return value | Description |
|---|---|---|---|
| loadSchema() | none |
Net_LDAP2_Schema,
Net_LDAP2_Error or false |
Returns the cached schema object. Net_LDAP2 will consider anything returned invalid, except a valid Net_LDAP2_Schema object. In case you return a Net_LDAP2_Error, this error will be routed to the return of the $ldap->schema() call. If you return something else, Net_LDAP2 will fetch a fresh Schema object from the LDAP server and tries to cache it via store(). You may also want to implement a cache aging mechanism here too. |
| storeSchema() | Net_LDAP2_Schema object | true or (in special cases) Net_LDAP2_Error |
Stores a schema object in the cache. This method will be called, if Net_LDAP2 has fetched a fresh schema object from LDAP and wants to init or refresh the cache. In case of errors you may return a Net_LDAP2_Error which will be routet to the client. Note that doing this prevents, that the schema object fetched from LDAP will be given back to the client, so only return errors if storing of the cache is something crucial (e.g. for doing something else with it). Normaly you dont want to give back errors in which case Net_LDAP2 needs to fetch the schema once per script run and use the error functionality of loadSchema(). |
Packaged schema cache classes
As of Net_LDAP2 2.0.0, there is one default schema caching class: Net_LDAP2_SimpleFileSchemaCache to make your life a little easier. Caching to files should also be the most commonly used case.
This cache class is built to be flexible yet simple to use and may serve as example to write own caching classes. This cache stores the schema object in a flat file. The path is freely configurable. It also servers a cache aging mechanism that can be used to invalidate the cached schema after some time so it will be refreshed regularly.
To use this cache, you firstly need to initialize and configure a fresh cache object. Then the cache must be registered with the Net_LDAP2 instance. After that, Net_LDAP2 will use the cache.
Initializing the SimpleFileSchemaCache
<?php
$myCacheConfig = array(
'path' => '/tmp/Net_LDAP_Schema.cache', // may reside on an linux tmpfs for improved performance
'max_age' => 1200 // in seconds, use 0 for endlessly
);
$myCacheObject = new Net_LDAP2_SimpleFileSchemaCache($myCacheConfig);
$ldap->registerSchemaCache($myCacheObject);
?>
| Option | Mandatory? | Default | Description |
|---|---|---|---|
path |
No | /tmp/Net_LDAP_Schema.cache |
The full path to the cache file. To improve the caches performance under linux, you can place the cache file in a tmpfs mounted directory. This will put the file in the computers memory instead on disk, enabling nearly instant access. |
max_age |
No | 1200 |
Maximum cache age in seconds. The age of the cache is determined by the files
last change time. If max_age is reached, Net_LDAP2 will fetch
a fresh Net_LDAP2_Schema object which is then stored in the cache file again.
Setting this to "0" will make the cache endlessly valid.
|
Writing own schema cache classes
However this is basicly an easy task, this is beyond the scope of this manual. If you want to write your
own custom schema cache, please refer to the detailed example at
/your/pear/path/docs/Net_LDAP2/examples/schema_cache.php as well as the source/APIdoc of
the interface Net_LDAP2_SchemaCache.