# phpgeo for Precise PHP Distance and Geometry Calculations

> phpgeo is a PHP library for coordinates, geometry objects, ellipsoid-aware distance calculations, geofences, intersections, and formatted output. It fits applications that need local geographic computation without adopting a larger mapping platform.

**mjaschen/phpgeo** — Simple Yet Powerful Geo Library for PHP

- Repository: https://github.com/mjaschen/phpgeo
- Website: https://phpgeo.marcusjaschen.de
- Stars: 1,612 · Forks: 196
- Language: PHP
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/mjaschen-phpgeo

## Why phpgeo Exists for PHP Geographic Logic

phpgeo targets a specific gap between basic language functionality and full spatial software. It represents geographical coordinates and several geometry types as PHP objects, then provides calculations around those objects without requiring the application to implement every formula itself. The intended audience is PHP developers working with location data, GPS tracks, polygons, distances, geofences, or intersections.

The supported model is broader than a single coordinate pair. The README lists `Coordinate`, `Line`, `Polyline`, and `Polygon`, with a polyline specifically associated with GPS tracks. It also documents different ellipsoids, including WGS-84. That makes the library applicable when a basic flat calculation would discard information that matters to the application.

The scope is still a library, not a mapping service. The repository documentation describes geometry abstractions, calculations, comparisons, and formatting. It does not claim to provide map rendering, street routing, address geocoding, tile delivery, or a spatial database. Applications needing those capabilities would still need separate components. The useful question is therefore not whether phpgeo replaces a GIS platform, but whether it can own the in-process geographic calculations that sit inside one.

## phpgeo Coordinates, Ellipsoids, and Geometry Objects

The library starts with geographic coordinates and builds more expressive objects from them. `Line` represents the relationship between two points, while `Polyline` and `Polygon` support sequences and enclosed areas. This object model gives application code a place to hold geographic intent instead of passing unlabeled latitude and longitude arrays through every calculation.

Ellipsoid support is a more important design detail than the short feature list initially suggests. Earth is not represented as a perfect sphere by every calculation, and phpgeo explicitly documents support for choices such as WGS-84. The README also lists Haversine and Vincenty implementations for length, distance, and perimeter calculations. Selecting an algorithm is consequently part of using the library correctly. The documentation identifies the available choices, but the README does not prescribe one universal choice for all application types.

The geometry abstraction also participates in comparisons and output. phpgeo documents geofence checks that determine whether a point belongs to an area or polygon, plus intersection checks between different geometries. Its formatting features cover GeoJSON and human-readable strings such as `18° 54′ 41″ -155° 40′ 42″`. This permits the same object to serve computational and presentation paths, although consumers still need to choose the appropriate output format rather than assume that formatting is automatic.

## Distance, Geofence, and Intersection Calculation Paths

phpgeo separates geographic inputs from the operations applied to them. A distance or perimeter calculation receives geometry built around coordinates, while an ellipsoid-aware implementation determines how the calculation treats Earth. This makes a calculation path visible at the application boundary: create the relevant geometry, select the calculation behavior, and pass the objects into the operation.

Two named distance approaches are enough to show that the library does not expose a single hard-coded formula. The README names Haversine and Vincenty. It does not claim that either is universally correct or interchangeable, and it gives no numerical accuracy table in the README. Developers should therefore make algorithm selection based on their documented requirements and the phpgeo documentation rather than infer a guarantee from the phrase “high precision” in the project description.

Geofence calculation answers a containment-style question for a point and a polygon. Intersection checks cover comparisons between geometry objects. These operations are useful for local application rules, such as deciding whether a supplied location belongs to a defined area. They do not automatically resolve ambiguous boundaries, invalid input, coordinate ordering, or coordinate reference systems. The README does not document policies for any of those cases, so they must be checked in the relevant API documentation before production adoption.

The README feature list ends during a description of bearing-angle functionality and does not provide a complete description of that API. Claims beyond the documented distance, geofence, intersection, ellipsoid, geometry, and formatting features should not be inferred from that fragment.

## Installing phpgeo 6.x on PHP 8.2 or Newer

The current 6.x line requires PHP 8.2 as its minimum. The README states that it is tested up to PHP 8.5. Install the package in an existing Composer-managed PHP project with this command:

```bash
composer require mjaschen/phpgeo
```

Composer resolves the phpgeo version appropriate to the project and records the dependency in the project's Composer configuration. The compatibility table maps PHP 8.2, 8.3, 8.4, and 8.5 to phpgeo 6.x. It marks phpgeo 5.x as security-only for PHP 8.1 and phpgeo 4.x as security-only for PHP 8.0 and PHP 7.4. Applications on older lines therefore face an explicit support trade-off rather than an automatic upgrade path.

For a first real calculation, begin with the geometry type required by the data, then consult the linked documentation for its constructor and the corresponding calculation page. The README links separate documentation for coordinate, line, polyline, polygon, ellipsoid, distance, geofence, and intersection APIs. The README does not include a complete first-use PHP snippet, so this article does not invent class names, constructor arguments, or method calls that are not shown there. The documentation site is the authoritative place to confirm the exact 6.x API before writing the first calculation.

The package can be updated through Composer. To request the 6.x line explicitly, the README gives this command:

```bash
composer require mjaschen/phpgeo:^6.0
```

That constraint matters for applications that need to stay on the documented PHP 8.2 or newer line.

## Upgrading Through phpgeo's Breaking Version Changes

The upgrade policy has a direct effect on maintenance cost. The README says that new features go only into the main branch and are not backported. There are also no GitHub releases listed for the repository, so users cannot rely on a GitHub release history when deciding how a deployment was packaged. Composer and the compatibility table provide the visible installation paths instead.

Version 6.x introduces two interface-related changes. `Line`, `Polygon`, and `Polyline` now implement `GeometryLinesInterface`, which provides `getSegments()`. Code that only consumes those classes is not described as requiring changes. Code that extends them may still need to account for the new interface. In addition, `GeometryInterface` adds `getBounds()`, so any custom class implementing that interface must expose that method.

The 6.x line also drops PHP 8.1 support. Applications can move to PHP 8.2 or newer or remain on phpgeo 5.x. Version 5.x had already removed `setPoint1()` and `setPoint2()` from `Line` because the class became immutable. It also dropped PHP 7.3, 7.4, and 8.0 support. These changes suggest that adoption should be evaluated with the whole dependency and runtime version in view. A package update can require application edits even when the library performs a familiar geographic calculation.

Starting with version 2.0.0, the README identifies the license as MIT. Older versions were GPL-licensed, so applications considering historical releases must check the applicable version rather than applying the current license status retroactively.

## phpgeo Scope Boundaries and Alternative Approaches

The clearest limitation is also the project's main strength: phpgeo operates on geographic objects and calculations inside PHP. It does not present itself as a complete geospatial stack. The README does not document map rendering, spatial indexing, address lookup, navigation, tile hosting, or persistence. A team needing those features would have to combine it with other software or choose a broader platform.

A real alternative is to store coordinates in a database with spatial types and execute spatial queries near the data. That changes the execution model. A database approach can keep large datasets indexed and centralize concurrency and access control, while phpgeo keeps calculation logic in PHP objects and methods. The README does not compare query performance or feature depth between phpgeo and a database, so neither can be presented as universally better.

Another alternative is a general geospatial service or framework that combines geometry, indexing, analysis, and data management. phpgeo is narrower: its documented feature set concentrates on coordinates, geometry, ellipsoids, distance, geofences, intersections, and output. This narrower surface can be attractive for a PHP application with a small number of calculations, but it also means the library does not remove the need to select data storage, define coordinate semantics, or decide how edge cases should behave.

## Repository Checks for phpgeo Maintainers and Integrators

The repository includes a CI workflow, PHPUnit configuration, PHPStan configuration, and a Makefile with targets for linting, coding standards, static analysis, and unit tests. The Makefile defines `ci` as a combined target and also provides documentation targets using `uv` and MkDocs. This gives maintainers explicit project-specific checks rather than leaving validation to an informal manual process.

The `Dockerfile` is documentation-focused. It starts from `nginx:alpine` and copies `build/documentation` into `/usr/share/nginx/html`. It does not package phpgeo as an application server or provide a runtime deployment image for consuming PHP projects. That distinction matters for teams looking for a containerized mapping service: this repository's documented container path serves generated documentation.

The README states that the project is tested across the supported PHP versions listed in the compatibility matrix, but it does not expose individual test results or coverage figures. A potential adopter should inspect the CI configuration and tests for the precise checks performed on a chosen PHP version. For documentation changes, `make docs` builds the site into `build/documentation`; `make serve-docs` starts the MkDocs development server. These are repository maintenance commands, not application runtime commands.

## Conclusion

PHP developers should consider phpgeo when their application needs local coordinate, distance, geofence, or intersection logic and can work with PHP 8.2 or newer. It is not the right choice for projects that need a mapping interface, spatial database, routing service, or a complete GIS platform. Check the selected 6.x APIs against the upgrade notes, confirm the required ellipsoid and distance algorithm for each calculation, and verify how custom classes implementing `GeometryInterface` expose `getBounds()` before upgrading.

## FAQ

### What PHP version does phpgeo 6.x require?

phpgeo 6.x requires PHP 8.2 or newer, and the README says it is tested up to PHP 8.5. Older PHP versions correspond to earlier phpgeo lines.

### How do I install phpgeo with Composer?

Run `composer require mjaschen/phpgeo` from a Composer-managed PHP project. To request the 6.x line explicitly, the README documents `composer require mjaschen/phpgeo:^6.0`.

### What geographic calculations does phpgeo support?

The README lists distance, length, and perimeter calculations using Haversine or Vincenty approaches. It also documents geofence checks, intersections, ellipsoid support, geometry objects, and GeoJSON or formatted output.

## Sources

- [Issues](https://github.com/mjaschen/phpgeo/issues)
- [License: MIT](https://github.com/mjaschen/phpgeo/blob/main/LICENSE)
- [mjaschen/phpgeo on GitHub](https://github.com/mjaschen/phpgeo)
- [Project website](https://phpgeo.marcusjaschen.de)
- [README](https://github.com/mjaschen/phpgeo/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mjaschen-phpgeo