README

PHP library to read and write ESRI Shapefiles with full Cyrillic charset support, compatible with WKT and GeoJSON.

This is a modernized fork of gasparesganga/php-shapefile with enhanced Cyrillic text handling and PHP 8.3+ compatibility.

Features

• ✅ Full PHP 8.3+ support with typed properties, constants, and return types
• ✅ Cyrillic charset support - automatic detection and repair of broken encodings (Windows-1251, ISO-8859-1)
• ✅ Read and write ESRI Shapefiles (.shp, .shx, .dbf, .dbt, .prj, .cpg)
• ✅ Support for all standard shape types (Point, Polyline, Polygon, MultiPoint, Z/M variants)
• ✅ WKT (Well-Known Text) and GeoJSON conversion
• ✅ DBF field types: CHAR, DATE, LOGICAL, MEMO, NUMERIC, FLOAT
• ✅ Fluent interface for method chaining
• ✅ PSR-12 code style compliant
• ✅ No external dependencies

Requirements

• PHP >= 8.3.0 (for older PHP versions, use gasparesganga/php-shapefile)
• mbstring extension (usually enabled by default)

Installation

composer require deadbyback/php-cyrillic-shapefile

Quick Start

Reading a Shapefile

use CyrillicShapefile\ShapefileReader;

$shapefile = new ShapefileReader('path/to/file.shp');

foreach ($shapefile as $record) {
    // $record is a Geometry object (Point, Linestring, Polygon, etc.)
    $data = $record->getDataArray();
    $coords = $record->getArray();

    echo "Record: " . json_encode($data) . "\n";
}

Writing a Shapefile

use CyrillicShapefile\ShapefileWriter;
use CyrillicShapefile\Shapefile;
use CyrillicShapefile\Geometry\Point;

$shapefile = new ShapefileWriter('path/to/output.shp');

// Define structure
$shapefile->setShapeType(Shapefile::SHAPE_TYPE_POINT);
$shapefile->addCharField('NAME', 50);
$shapefile->addNumericField('POPULATION', 10, 0);

// Add records
$point = new Point(30.5164, 50.4536);
$point->setData('NAME', 'Київ');
$point->setData('POPULATION', 4700000);
$shapefile->writeRecord($point);

// Shapefile is automatically finalized and closed

Cyrillic Support

The library automatically detects and handles Cyrillic text in multiple encodings:

use CyrillicShapefile\ShapefileHelper;

// Automatic charset detection and repair
$fixed = ShapefileHelper::tryRepairStringCharset($brokenString);

// Supported charsets: Windows-1251, ISO-8859-1, UTF-8

What's New in v4.0.0

This major version brings full PHP 8.3 compatibility with breaking changes:

• Typed constants: All class constants now have explicit types
• Full type safety: Parameter types and return types on all methods
• Modern PHP: Union types, nullable types, static return types
• Bug fixes: Fixed Iterator compatibility, undefined variables, namespace issues

See CHANGELOG.md for complete details.

Documentation

For detailed documentation and examples, visit the original project:

• Original documentation by Gaspare Sganga

Differences from Original

This fork extends the original gasparesganga/php-shapefile with:

1. PHP 8.3+ compatibility - uses modern PHP features (typed constants, properties, etc.)
2. Cyrillic charset handling - enhanced support for Cyrillic text in DBF files
3. Namespace change - from Shapefile to CyrillicShapefile
4. Bug fixes - fixed several issues with undefined variables and type compatibility

License

MIT License - Same as the original project

Credits

• Original library: Gaspare Sganga
• Cyrillic support and PHP 8.3 upgrade: deadbyback

Contributing

Issues and pull requests are welcome!