PHP 的 Eloquent 不支持空间查询，需用 MySQL GIS 函数配合 POINT 字段、SRID 4326、ST_PointFromText 插入及 ST_Distance_Sphere 计算球面距离，并添加 SPATIAL 索引。
PHP 本身不支持空间查询，Eloquent 的
或原生 SQL 才是实际执行地理计算的载体；Laravel 官方 Eloquent 不内置空间类型支持，必须依赖 MySQL/MariaDB 的 GIS 函数 + 正确字段类型 + 手动绑定参数。
MySQL 表必须用
字段类型，不能用
或
PostGIS 是 PostgreSQL 的扩展，MySQL 的空间能力靠
类型和
函数支撑。若把经纬度存成两个
字段或拼成字符串，
会直接报错或返回
。
建表时用
：
插入数据必须用
：
给
加空间索引（否则查询极慢）：
是唯一靠谱的球面距离函数，别用
在 MySQL 中默认按平面欧氏距离算，北京到上海会得出几百公里的错误结果；
才基于 WGS84 椭球模型，单位是米，且要求两点都带 SRID 4326。
查 5km 内的门店（Laravel 查询构造器写法）：
必须显式传入
和
，顺序不能反（
）
如果表里
没设 SRID（比如建表时漏了
），
返回
，但不会报错 —— 这是最常被忽略的静默失败点
Eloquent 模型要禁用自动类型转换，否则
字段会被转成字符串
Laravel 默认对所有字段做
处理，遇到
这类二进制 GIS 类型，会调用
导致数据损坏。必须在模型中明确排除：
PHP 8.5.5
PHP 8.5.5 是 PHP 8.5 分支的维护更新版本。该版本延续了“小步快跑”的迭代逻辑，通过深度错误修复、底层性能微调以及安全加固，旨在为开发者提供一个更健壮、更高效的运行环境。该版本严格遵守语义化版本规范，不包含破坏性变更。
下载
立即学习
“
PHP免费学习笔记（深入）
”；
在模型里加：
或者更安全的做法：完全禁用该字段的 cast：
并在访问时手动用
提取坐标
读取经纬度时别用
直接取值 —— 它是二进制 blob，要用：
真正麻烦的不是写那几行 SQL，而是字段类型、SRID 声明、索引、函数选型这四个点只要漏一个，查询就静默失效或性能崩盘。尤其
必须从建表、插入、查询全程一致，中间任何环节没带上，
就等于没跑。
whereRawPOINTJSONTEXTGEOMETRYST_*DECIMALST_Distance_SphereNULLPOINTALTER TABLE locations ADD COLUMN position POINT SRID 4326;ST_PointFromTextINSERT INTO locations (position) VALUES (ST_PointFromText('POINT(116.48 39.92)', 4326));positionALTER TABLE locations ADD SPATIAL INDEX idx_position (position);ST_Distance_SphereST_DistanceST_DistanceST_Distance_SphereLocation::selectRaw('*, ST_Distance_Sphere(position, POINT(?, ?)) AS distance', [$lng, $lat])
->having('distance', '<', 5000)
->orderBy('distance')
->get();$lng$latPOINT(long lat)positionSRID 4326ST_Distance_SphereNULLPOINTcastPOINT__toString()protected $casts = [
'position' => 'string', // 强制当字符串处理，避免自动序列化
];protected $casts = [];DB::raw('ST_AsText(position)')$model->positionDB::selectOne("SELECT ST_X(position) AS lng, ST_Y(position) AS lat FROM locations WHERE id = ?", [$id]);SRID 4326ST_Distance_Sphere