# Using Dinkey Pro/FD with PHP

Protection checks in PHP are implemented using a PHP extension to communicate with the dongle. You should use DinkeyAdd to lock this extension with the API protection method as described in the user manual, and distribute the locked file(s) with your software.

If you are not already familiar with using PHP extensions, it is strongly recommended that you read the PHP documentation on the subject. The Dinkey Pro/FD SDK includes a large number of different PHP extension files. Which one(s) you need to use depends on several factors, including operating system, PHP version, architecture (e.g. x86 or x64) and thread safety. This sample code includes a script, extensionhelper.php, that detects these factors, indicates which extension is appropriate, and provides basic installation instructions.

It is important that you consider which system configuration(s) your protected software will support, and distribute the corresponding PHP extension(s). You may wish to distribute extensionhelper.php along with your software to help your users to install the correct extension for their system. See Supported Versions below for full information on the platforms supported by Dinkey Pro/FD.

Do not specify a calling program when locking the PHP extensions. The calling program for PHP code is the user's web server (or PHP CLI), which will be different for different users.

Before you distribute your PHP code, you must protect it from modification using a third-party tool such as SourceGuardian.

## API Reference

See Modifying Your Code in the user manual for general information about the Dinkey Pro/FD API. In PHP, `DDProtCheck()` and the `DRIS` structure are not directly accessible. Instead, the PHP API provides two sets of functions: wrappers to `DDProtCheck()` that also take parameters that set DRIS input fields; and functions that access DRIS output fields.

### Protection Check Functions

These functions each provide a wrapper to `DDProtCheck()` using a different `function` value. Each function's return value is the return value of `DDProtCheck()` - zero on success, or a value indicating the cause of the error on failure.

#### DDSimpleCheck ( int $flags ) : int

Sets the `flags` DRIS field and calls `DDProtCheck()` with the `PROTECTION_CHECK` function.

#### DDSimpleCheckEx ( int $flags , int $execs_decrement, string $alt_licence_name ) : int

Sets the `flags`, `execs_decrement` and `alt_licence_name` DRIS fields and calls `DDProtCheck()` with the `PROTECTION_CHECK` function.

#### DDSimpleCheckAlg ( int $flags , int $alg_num , int $var_a , int $var_b , int $var_c , int $var_d , int $var_e , int $var_f , int $var_g , int $var_h ) : int

Sets the `flags`, `alg_num` and `var_a` to `var_h` DRIS fields and calls `DDProtCheck()` with the `EXECUTE_ALGORITHM` function.

#### DDSimpleCheckAlgEx ( int $flags , int $execs_dec, string $alt_licence_name , int $alg_number , int $var_a , int $var_b , int $var_c , int $var_d , int $var_e , int $var_f , int $var_g , int $var_h ) : int

Sets the `flags`, `execs_decrement`, `alt_licence_name`, `alg_num` and `var_a` to `var_h` DRIS fields and calls `DDProtCheck()` with the `EXECUTE_ALGORITHM` function.

#### DDWriteString ( int $flags , int $rw_offset , string $rw_data ) : int

Sets the `flags`, `rw_offset` and `rw_data` DRIS fields and calls `DDProtCheck()` with the `WRITE_DATA_AREA` function.

`$rw_data` must be an ASCII string. To write binary data, first encode it using `base64_encode()`. The `rw_length` DRIS field is automatically set to the length of `$rw_data`.

#### DDReadString ( int $flags , int $rw_offset , int $rw_length , string &$rw_data) : int

Sets the `flags`, `rw_offset` and `rw_length` DRIS fields and calls `DDProtCheck()` with the `READ_DATA_AREA` function. The data read is returned in `$rw_data`.

Only use this function to read data that represents an ASCII string. If you read bytes that do not represent ASCII characters, the string value returned in `$rw_data` may be unpredictable. To read binary data, store it in the dongle data area as a base64-encoded sequence and use `base64_decode()` on the string returned in `$rw_data`.

### DDGet...() Functions

Each `DDGet...()` function takes one parameter by reference sets it to the value of the relevant DRIS element. See Structures > DRIS Structure in the user manual for more information about the DRIS and its fields. These functions return `TRUE` on success, or `FALSE` if the internal DRIS has not been populated by a call to one of the `DDProtCheck()` wrapper functions above.

- `DDGetExtendedError ( int &$ext_err ) : bool`
- `DDGetType ( int &$type ) : bool`
- `DDGetModel ( int &$model ) : bool`
- `DDGetSDSN ( int &$sdsn ) : bool`
- `DDGetProdCode ( string &$prodcode ) : bool`
- `DDGetDongleNumber ( int &$dongle_number ) : bool`
- `DDGetUpdateNumber ( int &$update_number ) : bool`
- `DDGetDataAreaSize ( int &$data_area_size ) : bool`
- `DDGetMaxAlgNum ( int &$max_alg_num ) : bool`
- `DDGetExecs ( int &$execs ) : bool`
- `DDGetExpDay ( int &$exp_day ) : bool`
- `DDGetExpMonth ( int &$exp_month ) : bool`
- `DDGetExpYear ( int &$exp_year ) : bool`
- `DDGetFeatures ( int &$features ) : bool`
- `DDGetNetUsers ( int &$net_users ) : bool`
- `DDGetAlgAnswer ( int &$alg_answer ) : bool`
- `DDGetFDCapacity ( int &$fd_capacity ) : bool`
- `DDGetFDDrive ( string &$fd_drive ) : bool`
- `DDGetSWKeyType ( int &$swkey_type ) : bool`
- `DDGetSWKeyExpDay ( int &$swkey_exp_day ) : bool`
- `DDGetSWKeyExpMonth ( int &$swkey_exp_month ) : bool`
- `DDGetSWKeyExpYear ( int &$swkey_exp_year ) : bool`

## PHP Example Files

- dpsample.php - various examples of using the Dinkey Pro/FD PHP API. This script outputs HTML and so is best used in a web server, but it can also be run using the PHP CLI.
- extensionhelper.php - a script that detects system configuration to determine the appropriate PHP extension to use, and where it should be located. This script outputs HTML when used in a web server and plain text when executed by the PHP CLI.

## Supported Versions

The Dinkey Pro/FD SDK includes extensions for PHP versions 5.1 and newer on Windows and Linux. The x86 and x64 architectures are both supported, and extensions are provided for both Thread Safe (TS) and Non-Thread Safe (NTS) builds of PHP. Due to the large number of combinations of PHP version, OS, architecture and TS/NTS PHP builds, the exact extension for your system may not be included in the SDK. In this case, please contact us with full details of your platform.

## Try It Yourself

The sample code is designed to teach you how to use the Dinkey Pro/FD API in PHP programs. Do not copy the examples verbatim into your own code. Experiment with the sample code to understand how the API works, and read the chapter Increasing Your Protection in the user manual for many suggestions on how to make the best use of the API features.

To execute the sample code you will first need to use DinkeyAdd to produce a locked copy of the PHP extension for your system, and program a dongle (if you are using Plus or Net dongles). Place the locked extension in your PHP extensions directory. Use extensionhelper.php to determine the correct extension and the location of the extensions directory for your system.

dpsample.php gives simple examples of performing a protection check, as well as using various other features of Dinkey Pro/FD. Browse the examples at the top of dpsample.php to see how different features can be used, and uncomment the relevant lines to enable them.

Not all features are supported by all dongle models. See the user manual for more information.