hi-folks/milk-sdk-php

Milk SDK PHP is a (fluent) open-source PHP library that makes it easy to integrate your PHP application with location services like Geocode, Route, Isoline, Search Places and Address, location data ...

milk-sdk-php's Issues

CI/CD add syntax checker for PHP

Add in the Yml file for the GitHub Actions workflow the syntax checker for php

    - name: PHP Syntax Checker (Lint)
      uses: StephaneBour/[email protected]
      with:
        dir: './src'

Fix for php 7.2 compatibility XyzSpaceStatistics.php

Fix for php 7.2 compatibility:

Parse error: syntax error, unexpected 'bool' (T_STRING), expecting function (T_FUNCTION) or const (T_CONST) in ./src/Here/Xyz/Space/XyzSpaceStatistics.php on line 16
Errors parsing ./src/Here/Xyz/Space/XyzSpaceStatistics.php

Implement Endpoint Weather API

Implement Endpoint integration for Weather API https://developer.here.com/documentation/destination-weather/dev_guide/topics/overview.html

API Documentation URL: https://developer.here.com/documentation/destination-weather/dev_guide/topics/resource-report.html

Method: GET

Parameters to implement:

• product
• name
• zip code
• metric
• language
• oneobservation
• latitude
• longitude

fix phpunit.xml.dist file

Running tests (PHPUnit 8) we have:

  Warning - The configuration file did not pass validation!
  The following problems have been detected:

  Line 25:
  - Element 'log', attribute 'charset': The attribute 'charset' is not allowed.
  - Element 'log', attribute 'yui': The attribute 'yui' is not allowed.
  - Element 'log', attribute 'highlight': The attribute 'highlight' is not allowed.

  Test results may not be as expected.

For now is it enough to replace this line:

<log type="coverage-html" target="build/coverage" charset="UTF-8" yui="true" highlight="true"/>

with this one:

<log type="coverage-html" target="build/coverage"/>

Add inItaly() method to Discover class

Add inItaly() method, a kind of shortcut for:

        $this->inCountry("ITA");
        $this->at(41.902782, 12.496366);

in Discover class

phpstan analyse src --level=5

Fix code following phpstan warning (level 5)

Type declaration for properties in src/Here/RestApi/RoutingV8.php

In src/Here/RestApi/RoutingV8.php file, replace type declaration for all properties.
For example from:

    /**
     * @var string
     */
    private $originAddress = "";

to:

private string $originAddress = "";

Add the missing parameter departureTime to Routing API V8

Add the missing parameter departureTime to Routing API V8
API Documentation URL: https://developer.here.com/documentation/routing-api/8.9.1/api-reference-swagger.html

Method: GET

Parameters to implement:

• departureTime

Value for the parameter:

• Specifies the time of departure as defined by either date-time or full-date T partial-time in RFC 3339, section 5.6 (for example, 2019-06-24T01:23:45).

File : src/Here/RestApi/RoutingV8.php

Add the missing parameter avoid to Routing API V8

Add the missing parameter avoid to Routing API V8
API Documentation URL: https://developer.here.com/documentation/routing-api/8.9.1/api-reference-swagger.html

Method: GET

Parameters to implement:

• avoid

Value for the parameter:

• Avoid routes that violate certain features of road network or that go through user-specified geographical bounding box.

Specify properties using array notation like avoid[features]=controlledAccessHighway,tunnel

avoid[features]

A comma separated list of features that routes will avoid.

• seasonalClosure
• tollRoad
• controlledAccessHighway
• ferry
• carShuttleTrain
• tunnel
• dirtRoad
• difficultTurns

avoid[areas]

A pipe separated list of user defined areas that routes will avoid to go through.

Format: {shape1}|{shape2}|{shape3}...

Supported shape format:

Bounding box - A rectangular area on earth defined by a comma separated list of two latitude and two longitude values.
Format: bbox:{west},{south},{east},{north}
{west} - Longitude value of the westernmost point of the area.
{south} - Latitude value of the southernmost point of the area.
{east} - Longitude value of the easternmost point of the area.
{north} - Latitude value of the northernmost point of the area.
Example: bbox:13.082,52.416,13.628,52.626 - Bounding box of Berlin

Implement Endpoint geocode

Implement Endpoint integration for geocode
Geocode endpoint documentation: https://developer.here.com/documentation/geocoding-search-api/dev_guide/topics/endpoint-geocode-brief.html
API Documentation URL: https://developer.here.com/documentation/geocoding-search-api/api-reference-swagger.html

Method: GET

Parameters to implement:

• at :
• in
• limit
• q
• qq
• lang

Start creating src/Here/RestApi/Geocode.php from src/Here/RestApi/RoutingV8.php

Avoid duplicate code for adding api key in src/Here/RestApi/* files

In:

• Geocode.php
• Isoline.php
• MapImage.php
• ReverseGeocode.php
• RoutingV8.php
• Weather.php

There is a duplicate code

        $cred = $this->c->getCredentials();
        if (! $cred->isBearer()) {
            if ($cred->getApiKey() !== "") {
                $retString = $this->addQueryParam($retString, "apiKey", $cred->getApiKey());
            }
            if ($cred->getAppId() !== "" && $cred->getAppCode() !== "") {
                $retString = $this->addQueryParam($retString, "app_id", $cred->getAppId());
                $retString = $this->addQueryParam($retString, "app_code", $cred->getAppCode());
            }
        }

Create a method in the parent class (RestClient) to return the $retString with the right query params (for the method implementation, reuse the duplicate piece of code and then in the "caller", call the method instead of that piece of code)
The method name : makeCredentialQueryParams($retString,): returns $retString with appended credentials

CI/CD: GitHub Actions add cache for PHP packages

Add cache in workflow to:

• based on composer.lock changes, cache vendor/ dir using actions/cache@v2
• based on composer.lock changes, cache composer cache package directory using actions/cache@v2

A good yml sample for caching is: https://github.com/roberto-butti/laravel7-ghactions/blob/master/.github/workflows/laravel_db_manual.yml

Add Map Image API usage documentation in Readme.md

In readme file, after "Isoline API" section and before "Useful reference" section add "Map Image API" to show some usage of MapImage class.
Use examples/20_map_image.php file to see some example of MapImage usage.

Add phpcs to composer.json

Add the codesniffer package in dev section.
In composer.json , in require-dev section, add squizlabs/php_codesniffer package:

{
    "require-dev": {
        "squizlabs/php_codesniffer": "3.*"
    }
}

So after that you can execute vendor/bin/phpcs.

Implement Endpoint Discover

• Implement Endpoint integration for https://discover.search.hereapi.com/v1/discover
• Documentation: https://developer.here.com/documentation/geocoding-search-api/dev_guide/topics/endpoint-discover-brief.html
• API Documentation URL: https://developer.here.com/documentation/geocoding-search-api/api-reference-swagger.html

Method: GET

Parameters to implement:

• q
• at
• in (for country)
• limit
• lang

Type declaration for properties in src/Here/RestApi/Isoline.php

In src/Here/RestApi/Isoline.php file, replace type declaration for all properties.
For example from:

    /**
     * @var LatLong|null
     */
    private $paramDestination = null;

to:

private ?LatLong $paramDestination = null;

Extend compatibility for guzzle, phpdotenv, phpunit

Extend compatibility for this library:
"guzzlehttp/guzzle": "^6.3|^7.0",
"vlucas/phpdotenv": "^3.3|^4.0|^5.2"
"phpunit/phpunit": "^7.5.15|^8.4|^9.0"

In this way we could install it with Laravel 8, Laravel 7 and Laravel 6

RoutingV8: export actions in GeoJSON string

RoutingV8: export actions in GeoJSON string

Makefile for unit test, phpstan and phpcs

Create a Make file with some tasks for:

• launching unit tests:

vendor/bin/phpunit --coverage-text

• executing phpstan with configuration from phpstan.neon

phpstan analyse

• executing phpcs for PSR12 standard

phpcs --standard=PSR12 src

update .env.dist

Update .env.dist with sample parameters needed by the sdk.

Improve Makefile

• add .PHONY

.PHONY: help phpstan test coverage phpcs allcheck

• add help section:

help:           ## Show this help.
	@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'

This is a good example:
https://github.com/Hi-Folks/rando-php/blob/master/Makefile

Php 7.2 compatibility XyzCredentials.php

Php 7.2 compatibility:

Parse error: syntax error, unexpected 'string' (T_STRING), expecting function (T_FUNCTION) or const (T_CONST) in ./src/Here/Xyz/Common/XyzCredentials.php on line 7
Errors parsing ./src/Here/Xyz/Common/XyzCredentials.php

Php 7.2 compatibility XyzSpaceFeatureEditor.php

Php 7.2 compatibility

Parse error: syntax error, unexpected 'array' (T_ARRAY), expecting function (T_FUNCTION) or const (T_CONST) in ./src/Here/Xyz/Space/XyzSpaceFeatureEditor.php on line 17
Errors parsing ./src/Here/Xyz/Space/XyzSpaceFeatureEditor.php

Fix standard=PSR12

Fix waring / error following indications provided by:

phpcs --standard=PSR12 src

Update contributing.md for hacktoberfest

Replace Requirements section in CONTRIBUTING.md file with:

## Open a Pull Request

In order to maintain consistency in the source code we are following PSR12 coding standard, and using PHP stan for static code analysis.
You can use the command:

make allcheck

to launch
- **[PSR-12 Coding Standard](https://www.php-fig.org/psr/psr-12/)**, under the hood is used [PHP Code Sniffer](https://pear.php.net/package/PHP_CodeSniffer);
- **PHPstan** with [level 7](https://phpstan.org/user-guide/rule-levels)
- **Phpunit** to execute all tests from ./tests/*

I suggest to launch *make allcheck* before to commit or before to create PR.

If you want to work on a PR, I suggest you to creating a new branch starting from **master branch**, and use it also when you will submit your new **P**ull **R**equest on the original repository.

If you want to contribute with an high quality PR, I suggest you to focus not just on the source code but also:

- **Add tests!** - Your patch won't be accepted if it doesn't have tests.

- **Document any change in behaviour** - Make sure the `README.md` and any other relevant documentation are kept up-to-date.

- **Consider our release cycle** - We try to follow [SemVer v2.0.0](https://semver.org/). Randomly breaking public APIs is not an option.

- **One pull request per feature** - If you want to do more than one thing, send multiple pull requests.

- **Send coherent history** - Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please [squash them](https://www.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages) before submitting.

Fix for php 7.2 compatibility, array

Fix for php 7.2 compatibility:

Parse error: syntax error, unexpected 'array' (T_ARRAY), expecting function (T_FUNCTION) or const (T_CONST) in ./src/Utils/GeoJson.php on line 7
Errors parsing ./src/Utils/GeoJson.php

Improve documentation for Weather API in readme.md

In readme.md file, in Weather API section, add some information about Weather class methods like:

• productObservation()
• productAlerts()
• productForecast7days()
• productForecast7daysSimple()
• productForecastAstronomy()
• productForecastHourly()
• productNwsAlerts()

Considering these notes:

     * Set the product for the Weather API
     * A parameter identifying the type of report to obtain.
     * The possible values are as follows:
     * - observation – current weather conditions from the eight closest locations to the specified location
     * - forecast_7days – morning, afternoon, evening and night weather forecasts for the next seven days.
     * - forecast_7days_simple – daily weather forecasts for the next seven days
     * - forecast_hourly – hourly weather forecasts for the next seven days
     * - forecast_astronomy – information on when the sun and moon rise and set,
     * and on the phase of the moon for the next seven days
     * - alerts – forecasted weather alerts for the next 24 hours
     * - nws_alerts – all active watches and warnings for the US and Canada

Type declaration for properties in src/Here/RestApi/Geocode.php

In src/Here/RestApi/Geocode.php file, replace type declaration for all properties.
For example from:

    /**
     * @var string
     */
    private $paramQ;

to:

private string $paramQ = "";

Implement Endpoint HERE Map Image API

Implement Endpoint integration for HERE Map Image API
API Documentation URL: https://developer.here.com/documentation/map-image/dev_guide/topics/what-is.html

Example:
https://image.maps.ls.hereapi.com/mia/1.6/mapview
?apiKey={YOUR_API_KEY}
&c=47.8,13.033

Method: GET

Parameters to implement:

• c center in format lat,lng
• h hight if image
• w width
• u (10k) zoom in terms of km

For base url, path etc:
https://developer.here.com/documentation/map-image/dev_guide/topics/request-constructing.html

Implement Endpoint Reverse Geocode

Implement Endpoint integration for Reverse Geocode.
Reverse Geocode endpoint documentation: https://developer.here.com/documentation/geocoding-search-api/dev_guide/topics/endpoint-reverse-geocode-brief.html
API Documentation URL: https://developer.here.com/documentation/geocoding-search-api/api-reference-swagger.html

Method: GET
BASE URL: https://revgeocode.search.hereapi.com/v1/revgeocode

Parameters to implement:

• at (required) "float,float" (url encode for comma) example: 48.2181679%2C16.3899064
• limit "int": default is 1
• lang "string" BCP47 compliant Language Codes

Start creating src/Here/RestApi/ReverseGeocode.php from src/Here/RestApi/Geocode.php

phpstan: Create a phpstan.neon configuration file

Create a phpstan.neon configuration file.
In order to execute phpstan always with same parameters set a file in the project directory named phpstan.neon :

parameters:
	level: 6
	fileExtensions:
		- php
	paths:
		- src
	treatPhpDocTypesAsCertain: false

So you are able to execute phpstan analyse (the parameters are loaded from phpstan.neon file)

create Env class to read safe environment variables

Instead of using getenv use $_ENV for reading environment varibles.
To to that , in a safe way , create Env class with getenv method

public static function getenv($parameter, $default = "")

XyzConfig.php use Environment::getEnv() instead of getenv()

In XyzConfig we are still using getenv().
Replace getenv function:

$this->hostname = getenv("XYZ_API_HOSTNAME") ?: self::HOST_PROD;

with the new method:

$this->hostname = Environment::getEnv("XYZ_API_HOSTNAME", self::HOST_PROD);

In order to use Environment class you need to import the right class:

use HiFolks\Milk\Utils\Environment;

phpstan level 6

Update code in order to resolve all warnings provided by phpstan with level=6

Add the missing parameter via to Routing API V8

Add the missing parameter via to Routing API V8
API Documentation URL: https://developer.here.com/documentation/routing-api/8.9.1/api-reference-swagger.html

Method: GET

Parameters to implement:

• via

Value for the parameter:

• A location defining a via waypoint.

A via waypoint is a location between origin and destination. The route will do a stop at the via waypoint.

Multiple waypoints can also be specified using multiple via parameters like via=...&via=..., in which case the route will traverse these waypoints sequentialy in the order specified in the request.

File: src/Here/RestApi/RoutingV8.php