PHPackages                             mapsight/tile-proxy - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. mapsight/tile-proxy

ActiveLibrary[Utility & Helpers](/categories/utility)

mapsight/tile-proxy
===================

Simple tile proxy

v2.1.2(4w ago)215MITPHPPHP ^8.2.0CI passing

Since May 24Pushed 4w agoCompare

[ Source](https://github.com/open-mapsight/tile-proxy)[ Packagist](https://packagist.org/packages/mapsight/tile-proxy)[ Docs](https://github.com/open-mapsight/mapsight-tile-proxy)[ RSS](/packages/mapsight-tile-proxy/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependencies (15)Versions (9)Used By (0)

Tile proxy
==========

[](#tile-proxy)

Tile proxy is a PHP-based server for processing and caching tiles.

Usage
-----

[](#usage)

You can initialize the proxy by providing a configuration array or by pointing to a JSONC (JSON with comments) configuration file.

### Initialization

[](#initialization)

Use `Proxy` when a single config serves both raster tile pipelines and Mapbox style assets. It routes style asset requests under `mapAssetBasePath` to `MapboxStyleProxy` and everything else with an `ops` pipeline to `Base`.

#### Combined or JSONC configuration

[](#combined-or-jsonc-configuration)

```
use OpenMapsight\TileProxy\Proxy;

Proxy::runFromJsonConfigFile('/path/to/config.jsonc');
```

#### Raster tiles only

[](#raster-tiles-only)

```
use OpenMapsight\TileProxy\Base;

Base::runFromJsonConfigFile('/path/to/config.jsonc');
```

#### Mapbox style assets only

[](#mapbox-style-assets-only)

```
use OpenMapsight\TileProxy\MapboxStyleProxy;

MapboxStyleProxy::run($config, $_SERVER['REQUEST_URI']);
```

#### Using array configuration

[](#using-array-configuration)

```
use OpenMapsight\TileProxy\Proxy;

$config = [
    // ... configuration ...
];

Proxy::run($config);
```

Both `Proxy`, `Base`, and `MapboxStyleProxy::run()` send HTTP status, cache, and content headers automatically. Use `MapboxStyleProxy::handleRequest()` or `Base::handleTileRequest()` when you need the `HttpResponse` object without sending output.

Configuration
-------------

[](#configuration)

The configuration defines the behavior of the proxy.

- `cacheServerPath`: Base directory for caching tiles and map assets.
- `ops`: (Raster tiles) Operation pipeline for bitmap tile requests.
- `mapAssetBasePath`: (Mapbox styles) URL path prefix for proxied style JSON, vector tiles, sprites, and glyphs.
- `styles`: (Mapbox styles) Named style configurations for `MapboxStyleProxy`.
- `laxContentTypes`: (Mapbox styles) When `true`, accept `application/octet-stream` for vector tile and glyph upstream responses in addition to the expected protobuf type. Set per style or at the config root. Can also be an array of additional MIME types to accept for any validated upstream fetch in that style.
- `upstreamHttp`: (Optional) Shared HTTP client settings for upstream fetches in tile and Mapbox style proxying.
- `logErrors`: (Optional) If set to `true`, log upstream fetch warnings and request handler failures to PHP's `error_log`.
- `prefixArgName`: (Optional) Name of the GET parameter to use for prefixing (e.g., to support different map styles).
- `allowedPrefixes`: (Optional) List of allowed values for the prefix argument.

### Combined raster tiles and Mapbox styles

[](#combined-raster-tiles-and-mapbox-styles)

Use one JSONC file and `Proxy::runFromJsonConfigFile()` when you need both bitmap tiles and Mapbox/MapLibre style assets. Root-level settings such as `cacheServerPath`, `upstreamHttp`, and `logErrors` apply to both modes.

```
{
    "cacheServerPath": "/var/cache/mapsight-tile-proxy",
    "upstreamHttp": {
        "timeout": 30
    },
    "logErrors": true,

    "ops": [
        {
            "cacheServerName": "base-map",
            "urls": ["https://tile.openstreetmap.org/{z}/{x}/{y}.png"],
            "mimeType": "image/png",
            "cacheBrowserTtl": 3600,
            "cacheServerTtl": 86400
        }
    ],

    "mapAssetBasePath": "/map-assets",
    "styles": {
        "city-default": {
            "upstreamStyleUrl": "https://example.com/styles/base.json",
            "allowedHosts": ["example.com"],
            "allowedPathPrefixes": [
                "/styles/",
                "/tiles/",
                "/sprites/",
                "/fonts/"
            ]
        }
    }
}
```

`Proxy` routes by request path:

```
/tile-proxy.php?z=12&x=2200&y=1340              → raster pipeline (`ops`)
/map-assets/styles/city-default.json            → Mapbox style proxy (`styles`)
/map-assets/tiles/city-default/source/0/12/2200/1340.pbf  → vector tile from style proxy

```

Raster tiles use `x`, `y`, and `z` query parameters. Mapbox assets use path segments under `mapAssetBasePath`. Keep those URL spaces separate so `Proxy` can pick the right handler.

### Upstream HTTP settings

[](#upstream-http-settings)

Both the tile `src` operation and `MapboxStyleProxy` use the same optional `upstreamHttp` configuration for outbound requests. HTTP(S) fetches go through Guzzle; `file://` URLs are read from disk. Supported keys map to [Guzzle request options](https://docs.guzzlephp.org/en/stable/request-options.html): `proxy`, `timeout`, `connect_timeout`, `allow_redirects`, and `headers`.

```
"upstreamHttp": {
    "proxy": "tcp://proxy.example.com:8080",
    "timeout": 30,
    "connect_timeout": 10,
    "allow_redirects": true,
    "headers": {
        "User-Agent": "mapsight-tile-proxy"
    }
}
```

For tile pipelines, set `upstreamHttp` at the root of the config. A `src` operation can override it with its own `upstreamHttp` block.

### Error logging

[](#error-logging)

Most failures are handled gracefully in HTTP responses, but are otherwise silent unless logging is enabled.

When `logErrors` is `true`, or a PSR-3 logger is wired via `Log::setLogger()`, the library logs:

- **Warnings** for upstream transport failures (invalid proxy URI, timeouts, unreadable `file://` URLs, content-type mismatches)
- **Errors** for uncaught request handler failures that become HTTP 500 responses (cache write failures, missing extensions, pipeline misconfiguration)

HTTP 4xx client errors and missing upstream tiles are not logged by default.

Enable PHP `error_log` output in config:

```
"logErrors": true
```

For production, wire a PSR-3 compatible logger before handling requests. The library calls `warning()` for upstream issues and `error()` for request handler failures.

#### Plain PHP entry file with Monolog

[](#plain-php-entry-file-with-monolog)

Install Monolog in your project (`composer require monolog/monolog`), then use a small front script such as `public/tile-proxy.php`:

```