Skip to content
PHP bindings of the libdogma library.
C PHP
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore
COPYING
README.md
config.m4
dogma.c
php_dogma.h
test-common.php
test-core.php
test-extra.php

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.

You can’t perform that action at this time.