issue #628 save_user_coords

[hxdimpf]

This is about adding a new service endpoint. The platforms (opencaching.xx) provide the capabilities to maintain a personal cache notes field for each cache. In addition with this there is also a capability to store user provided coordinates for instance the coordinates that are the result of solving a puzzle.

The OKAPI provides a service to retrieve the personal caches notes and also the user_coords. It also provides a service to update the personal cache notes but not the user coords.

I have implemented a new service to fill this gap. First I thought about extending the already existing service

:: services/caches/save_personal_notes

however, to make sure that this doesn't create any adverse side effects for existing client applications I decided to implement a new service:
:: services/caches/save_user_coords.

[bekuno]

If you want a feedback from c:geo side, please open an issue there.

[stefopl]

OCPL cache_mod_cords table does not contain an id column.

create table cache_mod_cords
(
	cache_id int not null,
	user_id int not null,
	date timestamp default current_timestamp() not null,
	longitude double not null,
	latitude double not null,
	primary key (cache_id, user_id)
)

it should look something like this:

else # oc.pl branch
{
    Db::query("
        INSERT INTO cache_mod_cords (
            cache_id,
            user_id,
            latitude,
            longitude,
            date
        ) VALUES (
            '".Db::escape_string($cache_id)."',
            '".Db::escape_string($user_id)."',
            '".Db::escape_string($latitude)."',
            '".Db::escape_string($longitude)."',
            NOW()
        )
        ON DUPLICATE KEY UPDATE
            latitude = VALUES(latitude),
            longitude = VALUES(longitude),
            date = NOW()
    ");
}

Additionally, in OCPL only some cache types support user coordinates:
https://github.com/opencaching/opencaching-pl/blob/30ae3a4681c6840fe5aad454ccdb50fdb1340603/src/Controllers/ViewCacheController.php#L646-L648

[hxdimpf]

I have commited your suggested else path.

With respect go the cache types that support user coordinates: in OCDE all do. I don't know how to access ocpl source code so pls send me the list of cache types that do support it then I will add the filtering.

[stefopl]

The documentation should also be updated to include these changes.

[stefopl]

Suggested change

	'fields' => 'internal_id'
	'fields' => 'internal_id|type'

[stefopl]

Suggested change

	self::validate_cache_type($geocache['type']);

[stefopl]

Suggested change

	private static function validate_cache_type($cache_type)
	{
	if (Settings::get('OC_BRANCH') != 'oc.pl') {
	return;
	}
	$allowed_types = array(
	'Other',
	'Quiz',
	'Multi',
	);
	if (!in_array($cache_type, $allowed_types, true)) {
	throw new InvalidParam(
	'cache_code',
	"User coordinates are not supported for cache type '$cache_type'."
	);
	}
	}

[hxdimpf]

Thanks @stefopl — all suggestions applied in d27f91d:

• Fetching type alongside internal_id so the cache type is available before the DB write.
• Added validate_cache_type() which gates on oc.pl only, rejecting Traditional, Virtual, Event, Webcam, Moving, Podcast, and Own with HTTP 400 — matching OCPL's ViewCacheController restriction to Multi, Quiz, and Other.
• docs.xml updated to document the OCPL-specific type restriction.

(Personally I think OCPL should support user coordinates for all cache types, but that's a separate discussion — scoping it to the platform constraint for now.)