Project-GC (LUA Sandbox)
Static Public Member Functions | Public Attributes | Static Public Attributes | List of all members
PGC_LUA_Sandbox Class Reference

API functions from PGC towards the Sandbox. The sandbox is not allowed to use more than 1G memory or execute for longer than 60 seconds. More...

Static Public Member Functions

static CollectErrors ($errno, $errstr, $errfile, $errline)
 
static GetCollectedErrors ()
 
static SetUserPremiumState ($premium)
 
static SetQueueToken ($token)
 
static AddOutput ($output)
 
static GetOutput ()
 
static Log ()
 Log a string that can be retrieved if the script timeouts. More...
 
static GetFinds ($profileId, $params=array())
 Returns an associative array with the finds from given profileId. More...
 
static GetHides ($profileId, $params=array())
 Returns an associative array with the hides from given profileId. More...
 
static GetBookmarklist ($bmcode, $params=array())
 Retuns an array with gccodes from a bookmark list. More...
 
static HTMLEscape ($string)
 Returns an HTML escaped string. More...
 
static CreateHTMLTable ($data)
 Returns a HTML table created from the data you provide. More...
 
static ProfileName2Id ($profileName)
 Returns the Profile ID of a user from given Profile name. More...
 
static ProfileId2Name ($profileId)
 Returns the Profile name of a user from given Profile ID. More...
 
static UTF8ToUpper ($string)
 Converts string to upper case. More...
 
static UTF8ToLower ($string)
 Converts string to lower case. More...
 
static UTF8SubStr ($string, $start, $length)
 Gets a part of a string. More...
 
static UTF8StrLen ($string)
 Returns length of string. More...
 
static Gccode2CacheName ($gccode)
 Returns a Cache name from a gccode. More...
 
static DistanceVincenty ($latitude1, $longitude1, $latitude2, $longitude2)
 Returns distance in meters. More...
 
static DistanceHaversine ($latitude1, $longitude1, $latitude2, $longitude2)
 Returns distance in meters. More...
 
static GetPublishers ($profileId, $params=array())
 Retuns an associative array with cache_id, gccode, publisher_id, publisher_name, publish_date, visitdate, log_id for each find. More...
 
static GetSouvenirs ($profileId, $params=array())
 Retuns an associative array with date_discovered, souvenir_guid, image_path, thumb_path, title for each souvenir. More...
 
static GetFavorites ($favoriteType='points', $params=array())
 Retuns an associative array with cache data. More...
 
static GetOldestCaches ($params=array())
 Retuns an associative array with cache data for the oldest caches according to the filter. Based on hidden date. More...
 
static GetAttributeList ()
 Get list of all known attributes. More...
 
static GetNumTrackablesDiscovered ($profileId)
 Get number of discovered trackables. More...
 
static GetMembershipCreatedDate ($profileId)
 Gets the date the user registered at Geocaching.com. More...
 
static GetNumCachesInArea ($params)
 Gets the number of caches in a defined area. More...
 
static GetBadgeGenData ($profileId, $params)
 Get BadgeGen badges and belt for specified user. More...
 
static GetJsonData ($lookupKey)
 Get a json blob from the PGC servers. More...
 
static GetFPInfoForUser ($profileId)
 Get FP information for user. More...
 
static GetFPDetailsForUser ($profileId)
 Returns a list of all gccodes the user has favorited. More...
 
static GetSimplifiedRegionPolygons ($country)
 Returns polygons region used for the MapRegions and MapCounties map. More...
 
static GetSimplifiedCountyPolygons ($country)
 Returns polygons county used for the MapRegions and MapCounties map. More...
 
static GetNumberOfRegionsInCountry ($country)
 Returns number of regions in a country. More...
 
static GetNumberOfCountiesInCountry ($country)
 Returns number of counties in a country. More...
 
static GetNumberOfCountiesInRegion ($country, $region)
 Returns number of counties in a region. More...
 
static GetIntersectedPolygonSize ($polygon, $params)
 Returns number of counties in a region. More...
 

Public Attributes

const MAXMEM = 1024*1024*1024
 
const MAXCPUTIME = 60
 

Static Public Attributes

static $sandbox = NULL
 

Detailed Description

API functions from PGC towards the Sandbox. The sandbox is not allowed to use more than 1G memory or execute for longer than 60 seconds.

Member Function Documentation

◆ CreateHTMLTable()

static PGC_LUA_Sandbox::CreateHTMLTable (   $data)
static

Returns a HTML table created from the data you provide.

At this point, there is no options to design the table. Neither can headers be provided. It's WIP.

Parameters
[in]array$dataAn associative array of the data you want back as HTML.
Returns
An HTML string with the data.

◆ DistanceHaversine()

static PGC_LUA_Sandbox::DistanceHaversine (   $latitude1,
  $longitude1,
  $latitude2,
  $longitude2 
)
static

Returns distance in meters.

Returns distance between two set of coordinates according to the Haversine formula. Haversine is less accurate than Vincenty You must handle that latitude and longitude will be nil on premium caches for non premium users

Parameters
[in]float$latitude1
[in]float$longitude1
[in]float$latitude2
[in]float$longitude2
Returns
Distance between the coordinates in meters, as a float.

◆ DistanceVincenty()

static PGC_LUA_Sandbox::DistanceVincenty (   $latitude1,
  $longitude1,
  $latitude2,
  $longitude2 
)
static

Returns distance in meters.

Returns distance between two set of coordinates according to the Vincenty formula. Vincenty is more accurate than Haversine You must handle that latitude and longitude will be nil on premium caches for non premium users

Parameters
[in]float$latitude1
[in]float$longitude1
[in]float$latitude2
[in]float$longitude2
Returns
Distance between the coordinates in meters, as a float.

◆ Gccode2CacheName()

static PGC_LUA_Sandbox::Gccode2CacheName (   $gccode)
static

Returns a Cache name from a gccode.

Parameters
[in]string$gccodeThe gccode (GCxxxxx).
Returns
The cache name as a string, or false if the cache isn't known.

◆ GetAttributeList()

static PGC_LUA_Sandbox::GetAttributeList ( )
static

Get list of all known attributes.

Returns
An associative array (attributeName, groupId, groupName, imageFaded, imageSet, imageUnset) with all known attributes, indexed by attribute id.

◆ GetBadgeGenData()

static PGC_LUA_Sandbox::GetBadgeGenData (   $profileId,
  $params 
)
static

Get BadgeGen badges and belt for specified user.

Parameters
[in]int$profileIdAn integer with the users profile id.
[in]array$paramsAn optional associative array with extra options.
Returns
data array.

◆ GetBookmarklist()

static PGC_LUA_Sandbox::GetBookmarklist (   $bmcode,
  $params = array() 
)
static

Retuns an array with gccodes from a bookmark list.

Parameters
[in]string$bmcodeA bookmark list bmcode.
[in]array$paramsAn optional array of options.
  • useCache (bool): Defaults to true, use cached list data if it exists. The cached data is never more than 1 hour old.
Returns
An associative array with the data.

◆ GetFavorites()

static PGC_LUA_Sandbox::GetFavorites (   $favoriteType = 'points',
  $params = array() 
)
static

Retuns an associative array with cache data.

Parameters
[in]string$favoriteTypeCan be one of points, percentage, wilson. Defaults to points.
[in]array$paramsAn optional associative array of options for filtering/limit.
  • limit (integer): Max number of rows to return (default=100, max=1000)
  • dontCountArchivedTowardsLimit: (bool) defaults to true
  • dontCountDisabledTowardsLimit: (bool) defaults to false
  • filter (array): An associative array with filters
    • country (string or array)
    • region (string or array)
    • county (string or array)
    • types (array): An array of valid types
    • sizes (array): An array of valid sizes
    • difficulties (array): An array of valid values
    • terrains (array): An array of valid values
    • excludeOwner (int): Exclude caches by this ownerId
    • excludeDisabled (bool): Exclude disabled caches, defaults to false
    • excludeArchived (bool): Exclude archived caches, defaults to false
    • requiredFP (int): Required favorite points. Will default to 10 when using favoriteType = percentage, to match the top list, otherwise 0. Note that this is in pure points regardless of type, and not in percent or wilson score.
    • radius (array): An associative array, the "great circle formula" will be used
      • distance (integer): Number of meters.
      • latitude (float): Latitude.
      • longitude (float): Longitude.
Returns
An associative array with the data.

◆ GetFinds()

static PGC_LUA_Sandbox::GetFinds (   $profileId,
  $params = array() 
)
static

Returns an associative array with the finds from given profileId.

Coordinates for Premium caches will not be returned if the logged in user is not a Premium member with Groundspeak.

Parameters
[in]int$profileIdAn integer with the users profile id.
[in]array$paramsAn optional associative array of options for filtering/sorting/limit.
  • limit (integer): Max number of rows to return
  • order: NEWESTFIRST to sort with the newest finds first, or OLDESTFIRST for the opposite
  • fields (array): An array with fields names that you want in your return result. If you expect more than 5000 finds you more or less need to use this to decrease the memory usage.
    • gccode, cache_id, cache_name, type, difficulty, terrain, size, owner_id, placed_by, latitude, longitude, elevation, hidden, last_publish_date, country, region, county, archived, disabled, premium, attributes_set, attributes_unset, last_find_date, last_archive_date, num_finds, latest_logs, favorite_points, favorite_points_pct, favorite_points_wilson, last_cache_harvest, last_log_harvest, log_id, visitdate, length, words, ftf, cache_description
  • filter (array): An associative array with filters
    • country (string or array)
    • region (string or array)
    • county (string or array)
    • minVisitDate (string): YYYY-MM-DD, the date will be included, ie: >= date
    • maxVisitDate (string): YYYY-MM-DD, the date will be included, ie: <= date
    • minHiddenDate (string): YYYY-MM-DD, the date will be included, ie: >= date
    • maxHiddenDate (string): YYYY-MM-DD, the date will be included, ie: <= date
    • gccodes (array): List of gccodes
    • types (array): An array of valid types
    • sizes (array): An array of valid sizes
    • difficulties (array): An array of valid values
    • terrains (array): An array of valid values
    • minFavoritePoints (int): Minimum amount of favorite points required
    • minFavoritePointsPercent (int): Minimum amount of favorite points percent required
    • minFavoritePointsWilson (int): Minimum amount of favorite points wilson score required
    • monthnames (array): List of January/February/March/April/May/June/July/August/September/October/November/December
    • daynames (array): List of Monday/Tuesday/Wednesday/Thursday/Friday/Saturday/Sunday
    • radius (array): An associative array
      • algorithm (string): Can be any value of ['Vincenty', 'Haversine']. Defaults to 'Vincenty'.
      • distance (integer): Number of meters.
      • latitude (float): Latitude.
      • longitude (float): Longitude.
      • minMax (string): Can be any value of ['min', 'max']. Defaults to 'max'.
Returns
An associative array with the data.

◆ GetFPDetailsForUser()

static PGC_LUA_Sandbox::GetFPDetailsForUser (   $profileId)
static

Returns a list of all gccodes the user has favorited.

Since Project-GC does not detect FP changes very fast, this list might be quite inaccurate if the user has spent or removed favorite points without logging the caches lately.

Parameters
[in]int$profileId
Returns
An array of gccodes

◆ GetFPInfoForUser()

static PGC_LUA_Sandbox::GetFPInfoForUser (   $profileId)
static

Get FP information for user.

If Project-GC does not yet have this data for the user, FALSE is returned. When this method was published, it was the case for almost every user. The user can correct this by using Self-Support, Refresh number of finds.

Parameters
[in]int$profileId
Returns
An associative array (fpAvailable, fpTotal). The difference are the used FP.

◆ GetHides()

static PGC_LUA_Sandbox::GetHides (   $profileId,
  $params = array() 
)
static

Returns an associative array with the hides from given profileId.

Coordinates for Premium caches will not be returned if the logged in user is not a Premium member with Groundspeak.

Parameters
[in]int$profileIdAn integer with the users profile id.
[in]array$paramsAn optional associative array of options for filtering/sorting/limit.
  • limit (integer): Max number of rows to return
  • fields (array): An array with fields names that you want in your return result. Use this to save memory.
    • gccode, cache_id, cache_name, type, difficulty, terrain, size, placed_by, latitude, longitude, elevation, hidden, last_publish_date, country, region, county, archived, disabled, premium, attributes_set, attributes_unset, last_find_date, last_archive_date, num_finds, latest_logs, favorite_points, favorite_points_pct, favorite_points_wilson, last_log_harvest
  • includeLogs (bool): If set to true, will return log data as well. Defaults to false.
Returns
An associative array with the data.

◆ GetIntersectedPolygonSize()

static PGC_LUA_Sandbox::GetIntersectedPolygonSize (   $polygon,
  $params 
)
static

Returns number of counties in a region.

Returns the amount of m2 in an intersected area. Project-GC does not have country polygon data right now, so it must be for either a region or a county. Names of counties should be unique per country in Project-GC so there is no need to send both region and county (in fact you shouldn't, due to how Project-GC stores the polygons). This api method only works for areas where Project-GC has polygon data. Note that for some areas, the polygon data stretches out in the sea, others not. In the future we will fix this, but it's not determined when.

Parameters
[in]arraypolygon - An array (3+ elements) of none associative lat,lon pairs. The last element should be the same as the first (closed polygon)
[in]arrayparams - Associative array, country => country, region => region OR county => county

◆ GetJsonData()

static PGC_LUA_Sandbox::GetJsonData (   $lookupKey)
static

Get a json blob from the PGC servers.

This function is a bit special. If you have larger data-sets, you can ask support to have it stored on the Project-GC servers, and then retrieve it like this. This is to avoid having several kilobytes or megabytes of data inside the LUA scripts.

Parameters
[in]string$lookupKeyA lookup string for the json data you want returned.
Returns
The json data decoded into an array.

◆ GetMembershipCreatedDate()

static PGC_LUA_Sandbox::GetMembershipCreatedDate (   $profileId)
static

Gets the date the user registered at Geocaching.com.

Parameters
[in]int$profileIdAn integer with the users profile id.
Returns
A string with a date in ISO format, can also return FALSE if the date is unknown

◆ GetNumberOfCountiesInCountry()

static PGC_LUA_Sandbox::GetNumberOfCountiesInCountry (   $country)
static

Returns number of counties in a country.

The number returned is based on Project-GC's polygon data. If no such data exists, a FALSE will be returned.

Parameters
[in]stringcountry

◆ GetNumberOfCountiesInRegion()

static PGC_LUA_Sandbox::GetNumberOfCountiesInRegion (   $country,
  $region 
)
static

Returns number of counties in a region.

The number returned is based on Project-GC's polygon data. If no such data exists, a FALSE will be returned.

Parameters
[in]stringcountry
[in]stringregion

◆ GetNumberOfRegionsInCountry()

static PGC_LUA_Sandbox::GetNumberOfRegionsInCountry (   $country)
static

Returns number of regions in a country.

The number returned is based on Project-GC's polygon data. If no such data exists, a FALSE will be returned.

Parameters
[in]stringcountry

◆ GetNumCachesInArea()

static PGC_LUA_Sandbox::GetNumCachesInArea (   $params)
static

Gets the number of caches in a defined area.

Parameters
[in]array$paramsAn optional associative array of options for filtering.
  • filter (array): An associative array with filters
    • country (string or array) Required
    • region (string or array)
    • county (string or array) Note that some countries has several counties with the same name. It's best practice to include the region name as well.
    • types (array): An array of valid types
    • sizes (array): An array of valid sizes
    • difficulties (array): An array of valid values
    • terrains (array): An array of valid values
    • excludeDisabled (bool): Exclude disabled caches, defaults to false
    • excludeArchived (bool): Exclude archived caches, defaults to false
    • excludeOwner (int): Exclude caches by this ownerId
    • minHiddenDate (string): YYYY-MM-DD, the date will be included, ie: >= date
    • maxHiddenDate (string): YYYY-MM-DD, the date will be included, ie: <= date
Returns
An integer with number of geocaches

◆ GetNumTrackablesDiscovered()

static PGC_LUA_Sandbox::GetNumTrackablesDiscovered (   $profileId)
static

Get number of discovered trackables.

Parameters
[in]int$profileIdAn integer with the users profile id.
Returns
An associative array (trackablesDiscovered, travelbugsDiscovered, coinsDiscovered) where travel bugs are defined by BadgeGen's rules.

◆ GetOldestCaches()

static PGC_LUA_Sandbox::GetOldestCaches (   $params = array())
static

Retuns an associative array with cache data for the oldest caches according to the filter. Based on hidden date.

Can return more than limit rows. Will first figure out the newest hidden date allowed, and then fetch all geocaches matching the filters before that date.

Parameters
[in]array$paramsAn optional associative array of options for filtering/limit.
  • limit (integer): Max number of rows to return (default=100, max=1000)
  • dontCountArchivedTowardsLimit: (bool) defaults to true
  • dontCountDisabledTowardsLimit: (bool) defaults to false
  • filter (array): An associative array with filters
    • country (string or array)
    • region (string or array)
    • county (string or array)
    • types (array): An array of valid types
    • sizes (array): An array of valid sizes
    • difficulties (array): An array of valid values
    • terrains (array): An array of valid values
    • excludeOwner (int): Exclude caches by this ownerId
    • excludeDisabled (bool): Exclude disabled caches, defaults to false
    • excludeArchived (bool): Exclude archived caches, defaults to false
    • requiredFP (int): Required favorite points.
    • minHiddenDate (string): YYYY-MM-DD, the date will be included, ie: >= date. Defaults to 2000-05-03.
Returns
An associative array with the data.

◆ GetPublishers()

static PGC_LUA_Sandbox::GetPublishers (   $profileId,
  $params = array() 
)
static

Retuns an associative array with cache_id, gccode, publisher_id, publisher_name, publish_date, visitdate, log_id for each find.

Note that a cache can be published multiple times and will then be returned once for each publisher (or twice if it was the same publisher). One should also be aware of that "Publish listing" is a log type that haven't always existed, not all caches has a publisher.

Parameters
[in]int$profileIdAn integer with the users profile id.
[in]array$paramsAn optional array of options for filtering.
  • type: Can be set to finds or hides, defaults to finds. Will make this method get the publishers for either the users finds, or hides. Some filters (visitdate) will not work together with types=hides, and may result in errors or unexpected results.
  • order: NEWESTFIRST to sort with the newest publishes first, or OLDESTFIRST for the opposite
  • filter (array): An associative array with filters (implementation not tested)
    • country: Only caches located in this country
    • region: Only caches located in this region
    • county: Only caches located in this county
    • minVisitDate (YYYY-MM-DD): Minimum visit date (inclusive)
    • maxVisitDate (YYYY-MM-DD): Maximum visit date (inclusive)
Returns
An associative array with the data.

◆ GetSimplifiedCountyPolygons()

static PGC_LUA_Sandbox::GetSimplifiedCountyPolygons (   $country)
static

Returns polygons county used for the MapRegions and MapCounties map.

These polygons are variants of Project-GC's polygons, but with a reduced number of vertices. The purpose is to reduce the size and make them fairly fast when using on maps.

Parameters
[in]stringcountry

◆ GetSimplifiedRegionPolygons()

static PGC_LUA_Sandbox::GetSimplifiedRegionPolygons (   $country)
static

Returns polygons region used for the MapRegions and MapCounties map.

These polygons are variants of Project-GC's polygons, but with a reduced number of vertices. The purpose is to reduce the size and make them fairly fast when using on maps.

Parameters
[in]stringcountry

◆ GetSouvenirs()

static PGC_LUA_Sandbox::GetSouvenirs (   $profileId,
  $params = array() 
)
static

Retuns an associative array with date_discovered, souvenir_guid, image_path, thumb_path, title for each souvenir.

Parameters
[in]int$profileIdAn integer with the users profile id.
[in]array$paramsAn optional associative array of options for filtering/sorting/limit.
  • order: NEWESTFIRST to sort with the newest finds first, or OLDESTFIRST for the opposite
Returns
An associative array with the data.

◆ HTMLEscape()

static PGC_LUA_Sandbox::HTMLEscape (   $string)
static

Returns an HTML escaped string.

This should be used on all data contributed from users that will be outputed as HTML. Including data from Geocaching.com, for example cache names.

Parameters
[in]array$stringA string that should be escaped.
Returns
An escaped string.

◆ Log()

static PGC_LUA_Sandbox::Log ( )
static

Log a string that can be retrieved if the script timeouts.

Max amount of log per checker run is 100 kB. The log entries will be available for 1 hour. Normally all in-parameters are concatenated to a single string. New-line isn't added automatically. But! If the first argument is an array, that argument, and only that argument, will be converted to a readable blob

◆ ProfileId2Name()

static PGC_LUA_Sandbox::ProfileId2Name (   $profileId)
static

Returns the Profile name of a user from given Profile ID.

Parameters
[in]integer$profileIdThe Profile ID to convert to a Profile name.
Returns
Profile Name as a string. Can also return FALSE in case the name is unknown (GDPR optout for example)

◆ ProfileName2Id()

static PGC_LUA_Sandbox::ProfileName2Id (   $profileName)
static

Returns the Profile ID of a user from given Profile name.

Parameters
[in]string$profileNameThe Profile name to convert to an ID.
Returns
Profile ID as an integer.

◆ UTF8StrLen()

static PGC_LUA_Sandbox::UTF8StrLen (   $string)
static

Returns length of string.

Implemented since LUA doesn't have unicode support in their functions (for example string.len).

Parameters
[in]string$stringThe UTF-8 string to extract from.
Returns
Number of characters.

◆ UTF8SubStr()

static PGC_LUA_Sandbox::UTF8SubStr (   $string,
  $start,
  $length 
)
static

Gets a part of a string.

Implemented since LUA doesn't have unicode support in their functions (for example string.substr).

Parameters
[in]string$stringThe UTF-8 string to extract from.
[in]int$startPosition of the first character to use. 1-based (first character is number 1).
[in]int$lengthMaximum number of characters to use from string.
Returns
An uppercase UTF-8 string.

◆ UTF8ToLower()

static PGC_LUA_Sandbox::UTF8ToLower (   $string)
static

Converts string to lower case.

Implemented since LUA doesn't have unicode support in their functions (for example string.lower).

Parameters
[in]string$stringThe UTF-8 string to convert to lower case.
Returns
An uppercase UTF-8 string.

◆ UTF8ToUpper()

static PGC_LUA_Sandbox::UTF8ToUpper (   $string)
static

Converts string to upper case.

Implemented since LUA doesn't have unicode support in their functions (for example string.upper).

Parameters
[in]string$stringThe UTF-8 string to convert to upper case.
Returns
An uppercase UTF-8 string.