Laravel Vector Tiles Laravel Package

Getting Started

Start by installing the package and publishing its config, then point it at a PostGIS-enabled database connection. Before defining any layers, run:

php artisan vector-tiles:doctor

This is the first thing to look at on a new install. It is read-only and checks the PostGIS extension, source tables, geometry columns, SRID consistency, declared properties, and whether a spatial index is actually being used. Fix anything it reports before debugging tile rendering.

Define a first layer with a source table, geometry column, SRID, exposed properties, and maxZoom. Then use the TileJSON endpoint as the map client entry point and the GeoJSON endpoint as a quick debugging/export path. A good first use case is a single-layer MapLibre or Leaflet map consuming the TileJSON URL, with vector-tiles:benchmark run across a few zooms to confirm render time and tile size are acceptable.

Implementation Patterns

Layer definitions are the main integration surface. Use filterByZoom() to constrain tile queries to the zoom levels where a layer is actually relevant, and simplify() to reduce geometry detail below the layer’s maxZoom. These compose naturally: high-zoom tiles keep full detail, lower-zoom tiles get simplified geometry and narrower queries.

Use TileCache::remember() around tile rendering so cache population is consistent and version-aware. The cache flush race fixed in this release is exactly the kind of issue this API is meant to centralize, so avoid hand-rolled cache writes where possible.

For advanced filtering or custom tile SQL, PostgisTileDriver::tileQuery() is the extension point. Keep custom queries aligned with the layer’s declared properties and SRID so the doctor and TileJSON metadata stay accurate.

Treat vector-tiles:benchmark as a pre-deploy or CI check for expensive layers. Because it only measures zooms where the layer has data, use it to choose maxZoom and simplification tolerances rather than guessing. Pair it with vector-tiles:doctor in CI or a deploy health check.

Use TileJSON for client configuration, but remember it now honors layer middleware. If layers are protected, the TileJSON request must pass the same authorization path as tile requests. The GeoJSON endpoint remains useful for debugging bbox behavior and geometry output, including EPSG:3857 layers.

Gotchas and Tips

• simplify() tolerance is expressed in screen pixels below the layer’s maxZoom, not in map units. Tune it per layer and verify with the benchmark rather than assuming a universal value.
• filterByZoom() can silently produce empty or unexpected tiles if its ranges do not line up with maxZoom and client zoom requests. Check the generated tile queries when tiles are missing.
• The TileJSON endpoint now applies layer middleware. Previously exposed protected-layer metadata should now be gated, but verify every protected layer’s middleware is actually configured.
• A bbox query parameter supplied as an array now returns 422 instead of 500. Validate client input, but also update tests that expected a server error.
• The EPSG:3857 GeoJSON bbox failure at ±90° latitude is fixed, but edge-case bboxes near the poles and antimeridian are still worth testing explicitly.
• Cache flushes during rendering no longer store stale tiles under a new version, but custom caching outside TileCache::remember() will not get that protection.
• vector-tiles:doctor is read-only, so it is safe in production, but it will not fix missing indexes or SRID mismatches. Treat its spatial-index check as a hard requirement for large tables.
• vector-tiles:benchmark only measures zooms with data. A fast benchmark does not prove empty or sparse zooms are cheap; test representative areas.