Download the PHP package salesrender/plugin-core-geocoder without Composer

Plugin Core Geocoder

Type-specific core framework for SalesRender GEOCODER plugins

Overview

salesrender/plugin-core-geocoder is a specialized core library that extends the base salesrender/plugin-core to build Geocoder-type plugins. Geocoder plugins resolve addresses to geographic coordinates, timezones, and structured address data.

This core provides:

• A GeocoderInterface that the developer must implement with actual geocoding logic
• A GeocoderContainer for registering the geocoder implementation
• An HTTP endpoint (POST /protected/geocoder/handle) for processing geocoding requests
• A GeocoderResult value object for returning structured results (address, timezone, info)
• A Timezone class supporting both named timezones and UTC offsets
• A GeocoderAction that parses requests and invokes the configured geocoder

Installation

Requirements

• PHP >= 7.4
• ext-json
• salesrender/plugin-core ^0.4.0 (installed automatically)
• salesrender/component-address ^1.0.0 (installed automatically)
• adbario/php-dot-notation ^2.2 (installed automatically)

Architecture

How This Core Extends plugin-core

plugin-core-geocoder overrides both factory classes from the base plugin-core:

WebAppFactory (extends \SalesRender\Plugin\Core\Factories\WebAppFactory):

• Adds CORS support
• Registers the GeocoderAction at POST /protected/geocoder/handle with protected middleware

ConsoleAppFactory (extends \SalesRender\Plugin\Core\Factories\ConsoleAppFactory):

• Inherits all base commands without adding new ones (geocoding is synchronous, no queue needed)

Request Flow

Getting Started: Creating a Geocoder Plugin

Step 1: Project Setup

Create a new project and add the dependency:

Create the directory structure:

Step 2: Bootstrap Configuration

Create bootstrap.php in the project root. This file configures all plugin components:

Key geocoder-specific configuration points:

• PluginType::GEOCODER -- identifies this plugin as a Geocoder type
• countries -- array of ISO 3166-1 alpha-2 country codes that this geocoder supports (e.g., ['RU'], ['RU', 'KZ'])
• GeocoderContainer::config() -- registers your GeocoderInterface implementation

Step 3: Implement GeocoderInterface

This is the core of your geocoder plugin. Create a class that implements GeocoderInterface:

The handle() method receives two parameters:

• $typing -- free-form text typed by the user (for autocomplete-style address search)
• $address -- a structured Address object with fields like region, city, address_1, address_2, postcode, countryCode, and location

It must return an array of GeocoderResult objects. Each result contains a resolved Address, an optional Timezone, and an optional info string.

Step 4: Create Web Entry Point

Create public/index.php:

Create public/.htaccess:

Step 5: Create Console Entry Point

Create console.php:

Step 6: Create Settings Form

Create src/SettingsForm.php:

Step 7: Create .env

Create example.env (copy to .env for local development):

Step 8: Initialize & Deploy

HTTP Routes

Routes added by \SalesRender\Plugin\Core\Geocoder\Factories\WebAppFactory:

Additionally, all base plugin-core routes are inherited:

Request Format

POST /protected/geocoder/handle expects the following JSON body:

Response Format

Returns a JSON array of geocoder results:

Error Responses

CLI Commands

The geocoder core does not add any new CLI commands beyond those inherited from the base plugin-core:

Key Classes & Interfaces

GeocoderInterface

Namespace: SalesRender\Plugin\Core\Geocoder\Components\Geocoder\GeocoderInterface

The primary interface that every geocoder plugin must implement:

GeocoderResult

Namespace: SalesRender\Plugin\Core\Geocoder\Components\Geocoder\GeocoderResult

A value object that represents a single geocoding result. Implements JsonSerializable.

GeocoderContainer

Namespace: SalesRender\Plugin\Core\Geocoder\Components\Geocoder\GeocoderContainer

Static container for registering and retrieving the GeocoderInterface implementation.

Timezone

Namespace: SalesRender\Plugin\Core\Geocoder\Components\Geocoder\Timezone

Represents a timezone, accepting either a named timezone or a UTC offset. Implements JsonSerializable.

Examples:

The offset format must match the pattern UTC[+-]\d{2}:\d{2} (e.g., UTC+03:00, UTC-05:00). Named timezones must be valid PHP DateTimeZone identifiers.

GeocoderAction

Namespace: SalesRender\Plugin\Core\Geocoder\GeocoderAction

HTTP action that handles POST /protected/geocoder/handle. Implements ActionInterface. Parses the request body using dot notation (via Adbar\Dot), constructs an Address object with optional Location, and invokes the geocoder.

The action:

1. Retrieves the geocoder from GeocoderContainer::getHandler()
2. Extracts typing from the request body
3. Constructs an Address from the address.* fields, including optional Location (latitude/longitude)
4. Calls GeocoderInterface::handle($typing, $address)
5. Returns the result array as JSON

Exceptions

Example Plugin

See the reference implementation: plugin-example-geocoder

Dependencies

See Also

• salesrender/plugin-core -- Base plugin framework
• salesrender/component-address -- Address component
• plugin-example-geocoder -- Example geocoder plugin implementation