Introduction

There are several new classes now available in Yapeal for application developers to use in classes/util/*.php that should make integrating Yapeal much easier. These classes provide simple OOP(object-oriented programming) interface to the underlaying tables and make managing them much easier.

Note

The first thing you might wanna read is this section: Util Database Table Dependences, since it contains information on how the util* tables works in your database and might help you understand a bit more of the content in this guide. If you have followed the Starter Guide you might already have read utilRegistered* sections in that wiki since it have been referred to from Starter Guide.

NOTE: You can skip utilSections part in Util Database Table Dependences for now, since it will be covered in a later guide.

Details

This guide and it's code is based on the setting registered_mode in yapeal.ini is set to optional. How this works is described in Util Database Table Dependences as mentioned above.

Now lets start showing you what is required to make all the util classes work.

The Basic

In any of your PHP files where you will be using any of the util classes you will need to include this code before using them:

<?php
/**
 * test.php that is located in the root folder of Yapeal.
 */

// Define short name for directory separator which always uses unix '/'.
if (!defined('DS')) {
  define('DS', '/');
}

// Get the base dir of Yapeal.
$dir = str_replace('\\', DS, dirname(__FILE__)) . DS;

// Load basic files for utils to run.
require_once $dir . 'inc' . DS . 'common_paths.php';
// Only needed if your existing custom autoload doesn't work for Yapeal.
// See note below.
require_once YAPEAL_CLASS . 'YapealAutoLoad.php';
require_once YAPEAL_INC   . 'getSettingsFromIniFile.php';

// Activate Yapeal auto loader to load classes automatic.
// Note this is optional if you have an existing autoloader that will
// also handle the classes and interfaces for Yapeal.
YapealAutoLoad::activateAutoLoad();

// Get settings from yapeal.ini
$iniVars = getSettingsFromIniFile();

// Define from Yapeal settings if Yapeal trace is enabled.
if (!defined('YAPEAL_TRACE_ENABLED')){
  define('YAPEAL_TRACE_ENABLED', $iniVars['Logging']['trace_enabled']);
}

// Let Yapeal know what settings to use to connect to the database.
YapealDBConnection::setDatabaseSectionConstants($iniVars['Database']);

// Clean up settings that we don't need any more.
unset($iniVars);
?>

That is the basic code needed to get each util class to work. The code comments should give you hints to what they do.

Back To Top | Back to Handling Sections Guide

class RegisteredKey

RegisteredKey is used to add/edit the CAK (Customizable API Key) for the utilRegisteredKey table so Yapeal has the key information it needs to be able to pulling data from the EVE APIs for you.

You'll need to get the key information so you can add it to Yapeal. It is recommended you make a new CAK key at EVE API for Yapeal.

Adding a new API

Let me start with an example showing how to add the key to the utilRegisteredKey table.

<?php
// Make a new RegisteredKey instance.
$regKey = new RegisteredKey(1156);
// Add the vCode to keyID 1156.
$regKey->vCode = 'abc123';
// Add the API Mask to keyID 1156.
$regKey->activeAPIMask = 8388608;
// Activate the API key.
$regKey->isActive = 1;
// Save the new API Key into the database.
if ($regKey->store()) {
  print 'Registered new API Key: ' . $regKey->keyID . ' to the database.' . PHP_EOL;
} else {
  print "API Key couldn't be added!" . PHP_EOL;
}
// Release everything.
$regKey = NULL;
unset($regKey);
?>

Now let me explain in a bit more detail what the above code does.

$regKey = new RegisteredKey(1156);

The number 1156 is your keyID. The keyID is the ID you find on EVE API. When running this line it will check if there is an existing record (row) with that ID in the utilRegisteredKey table of the database and if not it will create a new record when you use the store() function as shown at the end of the code.

$regKey->vCode = 'abc123';

This will set the vCode column in utilRegisteredKey table to 'abc123'. The vCode is the Verification Code you find on EVE API.

$regKey->activeAPIMask = 8388608;

This will set the activeAPIMask column in utilRegisteredKey table to 8388608. The activeAPIMask is the Access Mask you find on EVE API. NOTE: This is optional and you don't need to add this line as a default will be used if you don't include it here.

$regKey->isActive = 1;

This will ensure that the key you are about to add, is active so Yapeal will pull data for it. This allows you to have non-active keys stored in the table if you have a need to.

$regKey->store()

This will actually save the record into the utilRegisteredKey table. If you don't run this line, the data will not be saved and Yapeal will not retrieve any of the APIs for this key.

$regKey = NULL;
unset($regKey);

This just releases the resources since they aren't needed any more.

---

Editing existing API info

Next is an example on how to change existing key information in the utilRegisteredKey table.

<?php
// Make a new RegisteredKey instance.
$regKey = new RegisteredKey(1156);
// Make sure that the keyID already exist
if ($regKey->recordExists()) {
  // Add a Active API to activeAPIMask
  $regKey->addActiveAPI('FacWarStats','char');
  // Remove a Active API from activeAPIMask
  $regKey->deleteActiveAPI('KillLog','char');
  // Make sure that the edited key information has been activated.
  if ($regKey->isActive == 0){
    $regKey->isActive = 1;
  }
  // Save the new API Key into the database.
  if ($regKey->store()) {
    print 'Updated key information for keyID: ' . $regKey->keyID .  PHP_EOL;
  } else {
    print "Key information couldn't be updated!" . PHP_EOL;
  }
} else {
  print "keyID: " . $regKey->keyID . " did not exist in utilRegisteredKey table";
}
// Release everything.
$regKey = NULL;
unset($regKey);
?>

This looks similar to when adding a new CAK key to utilRegisteredKey table.

The key thing to note here is that we are still using this:

$regKey = new RegisteredKey(1156);

This is because the RegisteredKey function works in 2 ways. When it's ran it will first check the utilRegisteredKey table, to see if there already is a record in it with that keyID. If the keyID exist it will pull the data from the database so we can edit it. If it doesn't exist it will create a new one that we can add the new key information to.

The second thing to notice is that I used the:

if ($regKey->recordExists()) {

This checks if there is already a record in utilRegisteredKey table. The way I have written the code, it should only execute the code if there is an existing record in the table, since we aren't provide all the needed data to actually create a new one. For that we would need to add: $regKey->vCode = 'abc123'; as well. since the vCode is required when creating a new record in the table.

Now lets look at the first new function I have added:

$regKey->addActiveAPI('FacWarStats','char');

What this does is adding the API: Factional Warfare Stats to the activeAPIMask in utilRegisteredKey table for characters. It needs two values. The first one is the name of the API, in this case FacWarStats. The next one is the section value which can either be: account, char, or corp. Why not eve, map, or server? Well eve, map, and server are not CAK key related APIs and they don't use the information stored in the utilRegisteredKey table.

To get a list of the API names and their section names, you can take a look in the utilAccessMask table of your Yapeal database. The columns you'll need are section and api which corresponds to the above information. Please note the column: status. If the number is below 8, it does not work.

Here is a short list of what the numbers mean:

• 1: Not Working.
• 2: A XSD have been made but the API still isn't done.
• 4: WIP: Work is in progress on the API but probably is incomplete.
• 8: The API is complete but is still being tested.
• 16: Fully tested and working API.

Now lets look at the last function I have added:

$regKey->deleteActiveAPI('KillLog','char');

This works exactly the same as the function above, the only thing that is different, is that it will remove the API from the activeAPIMask in utilRegisteredKey table for the character.

If you have a complete list of APIs as a bitmap to be add it is probably easier to use something like this:

$apis = 8 | 4 | 1;
$regKey->activeAPIMask = $apis;

rather that using the the 2 above functions.

For more information on what functions there are, you should look at the class/util/RegisteredKey.php file. All the functions are well documented in there.

Before moving on, you should manually run yapeal.php from CLI to populate the account* tables

Back To Top

class RegisteredCharacter

RegisteredCharacter is used to add/edit a character in utilRegisteredCharacter table so Yapeal knows what to pull from EVE APIs for the specified character.

Adding a new character

Let me first show an example on how to add a character to the utilRegisteredCharacter table.

$char = new RegisteredCharacter(126891489);
$char->isActive = 1;
if ($char->store()) {
  print 'Added ' . $char->characterName . ' to the database.' . PHP_EOL;
} else {
  print "Character couldn't be added!" . PHP_EOL;
};
// Release everything.
$char = NULL;
unset($char);

The only thing that is really new here is that we use a new class name in the first line:

$char = new RegisteredCharacter(126891489);

The number represent the characterID that you can find in accountCharacters table. If your character is not in that table, then check if your API settings is set to active in utilRegisteredKey table and that you have ran yapeal.php at least once to pull the data.

You might have noticed the code is simpler than when registering a key in the utilRegisteredKey table, and that is because you only need to feed it a characterID before storing it. It can't get much simpler than that. ;-)

---

Editing existing character

Let me show an example about editing a existing character in the utilRegisteredCharacter table.

// Get a new character object
$char = new RegisteredCharacter(126891489);
$char->addActiveAPI('AccountBalance');
$char->deleteActiveAPI('WalletJournal');
if ($char->isActive == 0) {
  $char->isActive = 1;
};
if ($char->store()) {
  print 'Adding ' . $char->characterName . ' to the database.' . PHP_EOL;
} else {
  print "Character couldn't be added!" . PHP_EOL;
};
// Release everything.
$char = NULL;
unset($char);

The only thing to note here and from Editing existing API info is that the addActiveAPI and deleteActiveAPI functions now only takes one value which is the API name that is either being add or remove.

Again, if you have a complete list of APIs as a bitmap to be add it is probably easier to use something like this:

$apis = 8 | 4 | 1;
$char->activeAPIMask = $apis;

To get a list of the API names to use, you can take a look in the utilAccessMask table of your Yapeal database. Look at the api column where the section name is char, which correspondence to the above. Please note the column: status. If the number is below 8, it does not work.

For more information on what functions there are, you should look at the class/util/RegisteredCharacter.php file. All the functions are well documented in there.

Back To Top

class RegisteredCorporation

RegisteredCorporation is used to add/edit a corporation to the utilRegisteredCorporation table so Yapeal knows which APIs to pull from the EVE servers for the specified corporation.

This is handles exactly the same as class RegisteredCharacter except that instead of using:

$char = new RegisteredCharacter(126891489);

it would be:

$corp = new RegisteredCorporation(632257314);

and the number is the corporationID that you also can find in the accountCharacters table.

For more information on what functions there are, you should once again look at the class/util/RegisteredCorporation.php file. All the functions are well documented in there.

Back To Top

Summary

You have been shown how to use the util classes: RegisteredKey, RegisteredCharacter and RegisteredCorporation in this guide. If you run yapeal.php now you might wonder why your tables are not populating and there is a good reason for this.

You will need to turn on the sections that you want to pull data from in another util table and that will be explained in the next guide.

Back To Top

Next is: Handling Sections