Maps

Maps is the MediaWiki extension to visualize and work with geographical information. It has been maintained since 2009 and is installed on 1000+ wikis.

Features:

• Customizable and dynamic Leaflet maps
• Customizable and dynamic Google Maps
• Structured data and query integration with Semantic MediaWiki
• Visual map editor
• GeoJSON and KML support
• Parser functions for geocoding, coordinate formatting and geospatial operations
• Translations in over 100 languages, image layers, static maps and more

Missing a feature? Get software development via Professional.Wiki. Discounts for work that is open-sourced.

Documentation

For administrators

• Installation
• Configuration
• Release notes - detailed list of changes per release
• Platform compatibility - overview of PHP and MediaWiki support per release

For wiki users

• Feature overview
• Displaying Leaflet maps
• Customizing Leaflet maps
• Displaying Google maps
• Customizing Google Maps
• Semantic MediaWiki integration

Getting support

• Professional support and custom development: Professional.Wiki
• Ask a question on the mailing list
• File an issue on our issue tracker

On-wiki configuration

Most settings can be configured in LocalSettings.php (see the configuration documentation) or, for wiki administrators without server access, on the MediaWiki:Maps page. It holds JSON and, like other site configuration, is editable only by users with the editinterface and editsitejson rights. Settings are grouped by service and topic:

{
	"general": {
		"mapWidth": "100%",
		"mapHeight": "500px",
		"distanceUnit": "km"
	},
	"coordinates": {
		"notation": "float",
		"directional": false
	},
	"geocoding": {
		"service": "google"
	},
	"leaflet": {
		"defaultZoom": 5,
		"layerDefinitions": {
			"Historic 1904": {
				"url": "https://tiles.example.org/historic1904/{z}/{x}/{y}.png",
				"options": { "attribution": "Historic map tiles", "maxZoom": 18 }
			}
		}
	},
	"googleMaps": {
		"zoom": 5,
		"type": "satellite"
	}
}

The available groups and keys correspond to LocalSettings.php settings:

• general: mapWidth, mapHeight, defaultTitle, defaultLabel, resizableByDefault, rezoomForKml, allowExternalDataFiles, pagesWithMapsCategory, distanceUnits, distanceUnit, distanceDecimals
• coordinates: availableNotations, notation, directional
• geocoding: service (geonames, google or nominatim)
• semanticMediaWiki: showTitle, hideNamespace, template, coordinateFormat, coordinateDirectional
• leaflet: layerDefinitions, defaultLayers, defaultOverlays, availableLayers, availableOverlays, defaultZoom
• googleMaps: zoom, type, types, controls, typeControlStyle, zoomControlStyle, autoInfoWindows, layers, showPoi, language

The page is validated when saved and combined with LocalSettings.php, with the wiki value taking precedence. Most settings are replaced wholesale; only layerDefinitions, availableLayers and availableOverlays are merged per name, so the wiki only needs to list the entries it changes. Changes take effect the next time a page with a map is parsed.

Secrets (API keys), settings that run before a wiki page can be read, and other server-only options stay exclusive to LocalSettings.php. Set $egMapsEnableInWikiConfig to false to ignore the page entirely.

Project status

• Latest version
• Downloads on Packagist
• Continuous integration
• Open bugs and feature requests
• Maps on OpenHub
• Blog posts about Maps

Contributing

• File an issue
• Submit a pull request (tasks for newcomers)

Development

To ensure the dev dependencies get installed, have this in your composer.local.json:

{
	"require": {
		"vimeo/psalm": "^4",
		"phpstan/phpstan": "^1.4.9"
	},
	"extra": {
		"merge-plugin": {
			"include": [
				"extensions/Maps/composer.json"
			]
		}
	}
}

Project structure

The src/ contains the PHP code and follows PSR-4 autoloading.

• src/Map - Map display entry points (such as handling of #display_map) and their supporting code
• src/ParserHooks - Entry points for all parser hooks except #display_map
• src/Presentation - Presentation layer code that does not belong to a more specific directory
• src/DataAccess - Persistence layer code that does not belong to a more specific directory
• src/GeoJsonPages - Code that deals with pages in the GeoJson namespace
• src/LegacyModel - Badly designed and deprecated representations of map elements (markers, polygons, etc)
• src/SemanticMW - Semantic MediaWiki code except for the map entry point (which is in Map\SemanticFormat)
• src/WikitextParsers - Parsers for the wikitext definitions of map elements (like the LegacyModel)

JavaScript, CSS and other web resources go into resources/.

Tests for PHP go into tests/ where they are grouped by test type (ie unit, integration). Within those test type directories the tests should mirror the directory structure in src/.

Running the tests

You can use the Makefile by running make commands in the Maps directory.

• make ci: Run everything
• make test: Run all tests and static analysis
• make cs: Run all style checks

Alternatively, you can execute commands from the MediaWiki root directory:

• PHPUnit: php tests/phpunit/phpunit.php -c extensions/Maps/
• Style checks: vendor/bin/phpcs -p -s --standard=extensions/Maps/phpcs.xml
• PHPStan: vendor/bin/phpstan analyse --configuration=extensions/Maps/phpstan.neon --memory-limit=2G
• Psalm: php vendor/bin/psalm --config=extensions/Maps/psalm.xml

Be aware that, due to technical debt, some tests access the network.

Links

• Maps documentation wiki
• Maps on Professional Wiki
• Maps on OpenHub
• Maps on Packagist
• Maps on WikiApiary
• Maps on MediaWiki.org