DOCSEARCHbyAlgolia
Submit Docs

Pathfinder

repository·master·Indexed 19 days ago

https://github.com/exodus4d/pathfinder

A system mapping tool for EVE ONLINE that provides spatial data visualization and mapping capabilities. Built as a PHP application using the Fat-Free Framework (F3), it utilizes ESI/SISI data sources and includes a client-side application using RequireJS.

Tokens
5K
Snippets
13
Records
23
Agent score
65%

What's inside pathfinder-eve

  1. Understand the Pathfinder project structure

    master

    Pathfinder is a PHP-based application built on the Fat-Free Framework (F3). The project is organized into several key directories for application logic, configuration, and static assets:

    Application Logic (app/)

    • Controller/: Controller classes for AJAX endpoints (defined in routes.ini).
    • Cron/: Controller classes for cronjob endpoints (defined in cron.ini).
    • Data/: Data handling classes.
    • Db/: Database handling classes.
    • Model/: ORM (Object-Relational Mapping).
    • Lib/: Libraries.
    • Exception/: Custom exception classes.

    Configuration Files (app/*.ini)

    • config.ini: F3 core configuration (SystemVariables).
    • cron.ini: Configuration for cronjobs.
    • environment.ini: System environment configuration.
    • pathfinder.ini: Pathfinder-specific configuration.
    • plugin.ini: Custom plugin configuration.
    • requirements.ini: System requirements configuration.
    • routes.ini: Application routing configuration.

    Static Assets and Public Files

    • public/: Production-ready static resources (minified CSS, JS, fonts, images, and templates).
    • export/: Static data, including csv/ for the /setup page and sql/ for database imports (e.g., eve_universe.sql.zip).
    • js/: JavaScript source files (used for development, not production).
    • sass/: SCSS source files (used for development, not production).
    • tmp/: Cache folders for PHP templates and PHP cache.

    Infrastructure and Environment

    • .htaccess: Apache-specific rerouting and caching rules.
    • index.php: Application entry point.
    • composer.json: Composer package definitions.
    • package.json: Node.js dependency definitions.

  3. Understand Cache Eviction Strategies

    master

    The Cache class uses a strategy pattern to decide which entries to remove when the maxSize is reached. You select a strategy via the strategy config option.

    Supported Strategies:

    • 'FIFO' (First In First Out): Evicts entries in the exact order they were added, regardless of how often or how recently they were accessed.
    • 'LFU' (Least Frequently Used): Evicts entries that have the lowest hitCount (the fewest number of successful get() calls).
    • 'LRU' (Least Recently Used): Evicts entries that have not been accessed for the longest period of time, based on the timestamp of the most recent hit.

  4. Configure Pathfinder via Environment Variables

    master

    Pathfinder supports custom configuration through environment variables. To avoid collisions, use the prefix PF- (defined by PF_PREFIX_KEY).

    Variables are parsed into a nested structure based on the delimiter - (defined by PF_ARRAY_DELIMITER). For example, an environment variable named PF-DATABASE-HOST will be accessible as a nested array/object under the key DATABASE with a sub-key HOST.

    Numeric values in environment variables are automatically type-cast to int or float.

  5. How LocalStore scoping and key prefixing works

    master

    The LocalStore class automatically transforms keys based on the instance configuration to prevent collisions and organize data:

    1. Scope Prefixing: If store.scope is set to myScope, a call to getItem('key') internally looks for myScope.key.
    2. Numeric Key Prefixing: If a key is an integer or a string starting with an integer, it is prefixed with the store's name followed by an underscore (e.g., if name is data and key is 123, the internal key becomes data_123).
    3. Nested Paths: Keys containing dots (.) are treated as paths into objects. setItem('a.b', 'val') will find the object at root key a, and set property b to 'val'.

  6. Initialize Pathfinder via index.php

    master

    Pathfinder is initialized through a central entrypoint that sets up the session, loads Composer dependencies, configures the Fat-Free Framework (F3) instance, and loads configuration files.

    To use Pathfinder in a project, ensure that vendor/autoload.php exists (by running composer install) and that your configuration files are placed according to the application structure. The entrypoint performs the following steps:

    1. Sets the session name to pathfinder_session.
    2. Requires the Composer autoloader.
    3. Initializes the Base (F3) instance and sets the NAMESPACE.
    4. Loads the main configuration from app/config.ini.
    5. Initializes environment-dependent configuration via Lib\\Config::instance($f3).
    6. Initiates cron jobs via Lib\\Cron::instance().
    7. Executes the application via $f3->run().
    <?php
namespace Exodus4D\\Pathfinder;

use Exodus4D\\Pathfinder\\Lib;

session_name('pathfinder_session');

$composerAutoloader = 'vendor/autoload.php';
if(file_exists($composerAutoloader)){
    require_once($composerAutoloader);
}else{
    die("Couldn't find '$composerAutoloader'. Did you run `composer install`?");
}

$f3 = \Base::instance();
$f3->set('NAMESPACE', __NAMESPACE__);

// load main config
$f3->config('app/config.ini', true);

// load environment dependent config
Lib\\Config::instance($f3);

// initiate cron-jobs
Lib\\Cron::instance();

$f3->run();

  7. Configure Pathfinder application environment and paths

    master

    The Pathfinder client-side application uses RequireJS for module loading. The application entry point (js/app.js) dynamically configures the baseUrl and module paths based on attributes present in the <body> tag of the HTML document.

    To control the application's behavior, ensure the following data attributes are set on the <body> element:

    • data-script: The path to the main application script (the entry point).
    • data-js-path: The base URL for JavaScript files. This should point to the js directory in development or the build_js directory in production.

    When these attributes are set, the application reconfigures the RequireJS baseUrl to match data-js-path before loading the main script.

    <body data-script="app/main.js" data-js-path="js">
  <!-- Application content -->
</body>

  8. Initialize the Pathfinder client-side application

    master

    The app.js file serves as the entrypoint for the Pathfinder client-side application. It uses requirejs to configure the module loading environment and bootstrap the application.

    To ensure the application loads correctly, the <body> element of your HTML must contain two specific data attributes:

    1. data-script: The path to the main application script to be executed.
    2. data-js-path: The base URL for JavaScript assets.

    The script automatically configures requirejs with a set of internal paths for application modules (like conf, dialog, layout, module, login, mappage, setup, and admin) and various third-party libraries (jQuery, Bootstrap, DataTables, etc.).

    <body data-script="app/main" data-js-path="/js/">
  <!-- Application content -->
</body>

  9. Configure LocalStore instances

    master

    When creating a LocalStore (typically via LocalStoreManager.newStore(name)), you can provide configuration objects to customize its behavior.

    LocalStore Config

    Passed as the first argument to the LocalStore constructor:

    • name: A unique identifier for the store (used for key prefixing if keys are integers/numeric strings).
    • debug: Boolean. If true, enables debug logging to the console.

    LocalForage Config

    Passed as the second argument to the LocalStore constructor. This configures the underlying localForage instance:

    • name: The name of the database (defaults to PathfinderDB [name]).
    • driver: An array of drivers to attempt (defaults to [INDEXEDDB, WEBSQL, LOCALSTORAGE]).

  10. Configure a Cache instance

    master

    To create a Cache instance, pass a configuration object to the constructor. The configuration allows you to define the cache's identity, expiration behavior, capacity, and eviction policy.

    Configuration Options:

    • name (string): A unique identifier for the cache instance (used in debug logs).
    • ttl (number): Default Time-To-Live in seconds for cache entries. Use a value < 0 to disable expiration for all entries.
    • maxSize (number): The maximum number of entries allowed in the cache before eviction is triggered.
    • bufferSize (number): The percentage of the total maxSize to be removed when the cache reaches its limit (e.g., 10 removes 10% of the capacity to prevent immediate subsequent evictions).
    • strategy (string): The eviction policy to use. Supported values: 'FIFO', 'LFU', 'LRU'.
    • debug (boolean): If true, enables detailed logging of cache operations (SET, HIT, MISS, EXPIRED, TRIM) to the console.
    const myCache = new Cache({
    name: 'UserSessionCache',
    ttl: 3600,
    maxSize: 100,
    bufferSize: 15,
    strategy: 'LRU',
    debug: true
});

  11. Gracefully delete a LocalStore instance

    master

    To completely remove a LocalStore instance and its associated data from the underlying storage (e.g., IndexedDB), use the dropInstance() method. This method also notifies the LocalStoreManager to remove the store from its registry.

    Note: Using LocalStoreManager.deleteStore(name) only removes the reference from the manager; it does not delete the actual data in the browser's storage. Use dropInstance() for a full cleanup.

    const manager = new LocalStoreManager();
const store = manager.newStore('temp_data');

// This removes the store from the manager AND wipes the database
await store.dropInstance();

  12. Configure Plugin settings

    master

    Plugins are configured via the PLUGIN hive key. Use Config::getPluginConfig($key, $checkEnabled = true) to retrieve a plugin's configuration array.

    If $checkEnabled is true, the method checks if a hive key PLUGIN.{KEY}_ENABLED exists and evaluates to true before returning the configuration. Plugin settings are typically defined in plugin.ini.

    // Returns the config array for 'my_plugin' if 'PLUGIN.MY_PLUGIN_ENABLED' is true
$pluginConfig = \Exodus4D\Pathfinder\Lib\Config::getPluginConfig('my_plugin');