Support receiving Expression as a parameter in SpatialBuilder methods

[Riley19280]

Currently, the column parameters on the SpatialBuilder class are typehinted as string, so when passing a DB::raw(...) expression into the builder, it gets casted to a string first, then re-wrapped as a column value. This causes issues when attempting a query like
->whereWithin(DB::raw('point(longitude, latitude)'), MultiPolygon::fromWkt(...)),
resulting in point(longitude, latitude) being treated as a column name in sql. By avoiding the string cast, the actual raw value passed is used.

The fix for this was to add the Expression typehint (what DB::raw returns) so that the implicit string cast does not happen. This is then picked up by the $this->getQuery()->getGrammar()->wrap calls (see here, and then here) resulting in a correct raw value in the sql.

[MatanYadaev]

Hi @Riley19280 , thanks for the PR.

1. Can you add tests?
2. Please update the typehint in the API.md file
3. Do you think the second parameter should also accept expression?

[Riley19280]

Yeah, I can add tests. It does probably make sense for the second one to do so as well, and also run the first parameter through the toExpression function as well, so that it can also handle geometries.

[Riley19280]

@MatanYadaev I made the changes requested, including expanding support for DB::raw and Geometry for both parameters for all functions. The unit tests for the toExpressionString method should suffice for this support, but also added a real world test for my use case.

[MatanYadaev]

Thanks!

Can you update the method signatures on API.md?

[Riley19280]

Can you update the method signatures on API.md?

Updated, I left off the ExpressionContract as I feel it clutters the docs and is something that anyone could reasonably expect to be supported if they need to use it.

[MatanYadaev]

Thanks for the contribution @Riley19280 🙏