php-dogma

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 COPYING file.

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

Contact: artefact2@gmail.com

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

API documentation

Unless otherwise stated in the section below, all the functions in dogma.h and dogma-extra.h are defined in PHP with exactly the same prototype and behaviour.

API notes

Here is a list of differences between the libdogma C API and the provided PHP API :

Core

All PHP functions can return false instead 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_context() and 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_context() or dogma_free_fleet_context() will still free the context as expected, even if it is still referenced (just like fclose()).
PHP has no union types, so arguments of type dogma_location_t are 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,
  … ]
```
Where key1, key2 are members of the dogma_location_t structure (or the unions inside it), and the location type can be accessed as $array[0]. The keys will be processed in the order they are defined in the dogma_location_t structure; 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_character_attribute, 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).

Extra

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_s structure. 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
(
    [0] => Array
        (
            [id] => 3363
            [destid] => 190
            [value] => 50
            [operator] => +
            [order] => 3
            [flags] => 0
        )

    [1] => 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_t structure. 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
(
    [52491280] => Array
        (
            [capacity] => 0
            [delta] => 0
            [stable] => 1
            [stable_fraction] => 1
        )

)

*/
```
The function dogma_free_affector_list() and 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.

osmium-org/php-dogma

php-dogma

API documentation

API notes

Core

Extra