PHP bindings of the libdogma library.
C PHP
Switch branches/tags
Clone or download
Latest commit d4467ba Aug 25, 2015

README.md

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.