PHP bindings of the libdogma library.
Released under the GNU Affero General Public License, version 3 or
later. The full license text is included in the
Requires libdogma ≥ 1.2.0 and pkg-config (and probably PHP ≥ 5.4 and a
C11-aware compiler, like
clang ≥ 3.1 or
gcc ≥ 4.7).
Main libdogma repository: https://github.com/Artefact2/libdogma
Compiling and using the extension:
phpize ./configure make # Run tests php -d "extension=modules/dogma.so" test-core.php php -d "extension=modules/dogma.so" test-extra.php make install # You can now add extension=dogma.so to your php.ini
Unless otherwise stated in the section below, all the functions in
dogma-extra.h are defined in PHP with exactly the same
prototype and behaviour.
Here is a list of differences between the libdogma C API and the provided PHP API :
All PHP functions can return
falseinstead of the usual
DOGMA_*constants, this happens when the supplied arguments did not match expectations (and you will generally get a warning message). So be sure to use
===to check the return values.
There is no
dogma_init()in PHP, this is taken care of for you during module initialization.
Unlike C, PHP has a garbage collector. The contexts created by
dogma_init_fleet_context()are not persistent and will be automatically freed when no longer referenced by anything (just like file handles, database connections, etc…). Calling
dogma_free_fleet_context()will still free the context as expected, even if it is still referenced (just like
PHP has no union types, so arguments of type
dogma_location_tare specified differently in PHP: they can be either one of the
DOGMA_LOC_*constants, or an array of this form :
[ DOGMA_LOC_*, key1 => value1, key2 => value2, … ]
key2are members of the
dogma_location_tstructure (or the unions inside it), and the location type can be accessed as
$array. The keys will be processed in the order they are defined in the
dogma_location_tstructure; values defined last will have precedence, regardless of the specified type. Here are examples of location arguments:
DOGMA_LOC_Char // OK [ DOGMA_LOC_Char ] // OK [ DOGMA_LOC_Module, "module_index" => 1 ] // OK [ "module_index" => 1, DOGMA_LOC_Module ] // OK [ DOGMA_LOC_Charge, "module_index" => 1, "drone_typeid" => 2488 ] // OK, but will use drone_typeid // to overwrite module_index DOGMA_LOC_Module // Undefined behaviour (needs module_index) [ DOGMA_LOC_Module, 1 ] // Not OK [ 3 => DOGMA_LOC_Skill, "skill_typeid" => 3496 ] // Not OK
In general usage, it is recommended to use the more specialized functions (like
dogma_get_module_attribute, etc…) as they will be a tiny bit faster (since the location is hardcoded and does not need to be constructed from the array every time).
The extension provides a helper function,
dogma_get_hashcode(), which returns an integer value. This is useful for comparing contexts (you can also use
===on the context resources).
dogma_get_affectors()only take three arguments (instead of four): a dogma context resource, a location and the third parameter is a reference that will be set to an array of affectors. Each element of the array will have the same fields as the
dogma_simple_affector_sstructure. Here is an example for reference:
dogma_init_context($ctx); dogma_get_affectors($ctx, DOGMA_LOC_Char, $arr); print_r($arr); /* Gives something similar to: Array (  => Array ( [id] => 3363 [destid] => 190 [value] => 50 [operator] => + [order] => 3 [flags] => 0 )  => Array ( [id] => 3731 [destid] => 190 [value] => 250 [operator] => + [order] => 3 [flags] => 0 ) etc… ) */
dogma_get_capacitor_all()only takes three arguments: a dogma context resource, a boolean (whether to include reload time) and a reference that will be set to an array of results. The result will have keys that are hashcodes of contexts, and the values will be arrays resembling the
dogma_simple_capacitor_tstructure. Here is an example for reference:
dogma_init_context($ctx); dogma_get_capacitor_all($ctx, false, $arr); var_dump(dogma_get_hashcode($ctx)); print_r($arr); /* Gives something similar to: int(52491280) Array (  => Array ( [capacity] => 0 [delta] => 0 [stable] => 1 [stable_fraction] => 1 ) ) */
dogma_free_capacitor_list()are not present in PHP, as the list is copied to the array and freed internally. The generated array will be garbage collected just like any other PHP array.