Have Views Proximity filters optionally return negative integers instead of 0 or NULL for various error conditions

This is mainly of interest to users of RdeBoer’s GeoField Proximity-to-Polygon module, but I can see it of being useful in general, so I’m suggesting it here since it really needs to be implemented at the GeoField Views Proximity Handler level.

There are any of a number of error conditions that can arise. At present, they all appear to return either zero or null. Since GeoField Proximity-to-Polygon (“GF-P2P” from here on out) also returns (or is supposed to return) zero if the reference point is contained within one or more of the current row’s specified GeoField’s polygons or multipolygons, there’s currently no way to distinguish that from an error condition.

Since this is a change that could break existing site functionality (say, a site builder uses a GeoField Proximity filter and specifies “≠ 0” to filter out error conditions — implementing this would cause erroneous values to start being returned in such views), I also propose an administrative configuration checkbox to enable or disable this functionality. Default to enabled on a new install, but to disabled on an upgrade install, meaning all non-fatal errors return zero or null as they currently do so that there won’t be any time during which erroneous results would be returned for those upgrading from the current version.

When enabled, error conditions would return specific negative integers (as so many other things do in computer science). I propose that error values from −1 – −99 be reserved for GeoField and its bundled views proximity handlers proper, with values from −100 and beyond be grouped in groups of 100 and assigned to other modules that integrate with GeoField Proximity Views Handlers. For instance, −500 – −599 could be assigned to GF-P2P.

Proposed examples for GeoField proper:

• −1: General non-fatal error, undetermined cause.
• −10: Current User specified as reference point source, general error, undetermined cause.
• −13: Current User’s specified GeoField is empty.
• −14: Current User’s specified GeoField contains a value other than a single Point (e.g. a MultiPoint, Line, PolyLine, Polygon, etc.).
• −20: Entity from URL specified as reference point source, general error, undetermined cause.
• −21: Entity from URL specified as reference point source, referenced Entity does not exist.
• −22: Entity from URL specified as reference point source, referenced Entity exists, but current user lacks View permission on it and/or its GeoField (access denied).
• −23: Entity from URL specified as reference point source, referenced Entity exists and user has View permission on the Entity and its GeoField, but specified GeoField is empty for that Entity.
• −24: Entity from URL specified as reference point source, referenced Entity exists and user has View permission on the Entity and its GeoField, specified GeoField is not empty, yet contains a value other than a single Point.
• ⋮
• −87: Manually specified Point (similar would exist for Exposed, Point From URL, etc.) exists but is not in the correct format (two positive numeric values separated by a comma, followed by optional radius value separated by a space [!?])
• −88: Manually specified Point (…) exists and is in the correct format, but either the Latitude or Longitude is (or both are) invalid i.e. out-of-range
  [ abs(lat) > 90° || abs(long) > 180° ]
• −90: Current Views Row’s specified GeoField has some sort of general error of undetermined cause.
• −92: Current Views Row’s specified GeoField exists, but current user lacks View permission on it (access denied).
• −93: Current Views Row’s specified GeoField exists, and user has View permission on it, but the GeoField is empty.
• −94: Current Views Row’s specified GeoField exists, user has View permission on it, and the GeoField isn’t empty, yet its value is not a single Point.

Following this pattern, other modules could be assigned a “hundred” range. So if, for instance, as specified above, GF-P2P were assigned the −5xx range, it could add some of its own, keeping the above pattern as much as possible, such as:

Proposed examples specific to GeoField Proximity-to-Polygon:

• −515: In “Reversed” mode², Current User’s specified GeoField contains a value that is not one or more Polygons or Mutipolygons (e.g. a single point, multiple points, line(s), polyline(s), etc.)
• −525: In “Reversed” mode², Entity from URL is a valid Entity with a valid non-empty specified GeoField, but it contains a value that is not one or more Polygons or Mutipolygons.
• ⋮
• −595: In “Normal” mode¹, Current Views Row’s specified GeoField is non-empty and user has View permissions on it, but it contains a value that is not one or more Polygons or Mutipolygons.
• ⋮

¹ “Normal” mode is the only mode that GF-P2P currently offers, in which the Views Row GeoFields are Polygons, and the proximity is checked to the Reference Point, which if contained within the Polygon is supposed to return a Proximity of zero (0). If not, it currently returns the proximity to the nearest vertex (hopefully nearest edge someday).

² “Reversed” mode is one I proposed in #2937497: Allow reversing of parameters to proximity algorithm, plus Intersection test. which swaps these, treating the Reference (which would have to be a GeoField [either from Current User or Entity from URL or some such] or maybe user-specified GeoJSON or WKT instead of a URL-specified point) as one or more Polygons, and the GeoFields from the Views Rows as points, and again returns zero for each point contained within the reference polygon, or distance to nearest vertex for each point outside the reference polygon.

Minimizing Backwards Incompatibility

As I said above, such a change would, if enabled immediately on module upgrade, may cause existing Views expecting zero results on error to malfunction. So, there should be an admin configuration option to enable negative numeric error codes, which should default to disabled on upgrade installs (it can default to enabled for new installs, or maybe the install script can be intelligent and default to disabled only if [A] it’s an upgrade install, [B] there are one or more existing Views that use GeoField Proximity as Filters, and [C] at least one of those currently tests for “=0” or “≠0” — of course, subsequent versions after the version that introduces this setting should detect if the version being upgraded from is a version that already has this setting, and if so, don’t modify its current status).

A user who wishes to use this functionality (say, for debugging purposes) could do the following even on a live site and prevent malfunction:

1. Upgrade the module.
2. In any Views that filter out empty or erroneous results by filtering to allow proximities ≠ 0, change it to > 0, then Save the View.
3. Activate the negative integer result-on-error functionality in the Admin configuration.
4. Optional, for users of GF-P2P or similar add-on modules:
   • Edit any GF-P2P-using Views and change filter to ≥ 0, and Save the View(s).