{"id":27341922,"url":"https://github.com/cyrildewit/php-maps-urls","last_synced_at":"2025-04-12T16:28:48.245Z","repository":{"id":54780827,"uuid":"133079607","full_name":"cyrildewit/php-maps-urls","owner":"cyrildewit","description":"Build URL's for the Google Maps URL API in PHP","archived":false,"fork":false,"pushed_at":"2025-01-19T06:44:20.000Z","size":86,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"1.x","last_synced_at":"2025-03-22T13:38:45.495Z","etag":null,"topics":["google-maps-api","google-maps-url-api","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cyrildewit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-11T19:17:32.000Z","updated_at":"2025-01-31T23:00:41.000Z","dependencies_parsed_at":"2022-08-14T02:50:27.677Z","dependency_job_id":null,"html_url":"https://github.com/cyrildewit/php-maps-urls","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrildewit%2Fphp-maps-urls","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrildewit%2Fphp-maps-urls/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrildewit%2Fphp-maps-urls/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrildewit%2Fphp-maps-urls/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cyrildewit","download_url":"https://codeload.github.com/cyrildewit/php-maps-urls/tar.gz/refs/heads/1.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248596131,"owners_count":21130642,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["google-maps-api","google-maps-url-api","php"],"created_at":"2025-04-12T16:28:47.585Z","updated_at":"2025-04-12T16:28:48.234Z","avatar_url":"https://github.com/cyrildewit.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PHP Google Maps URLs\n\n[![Packagist](https://img.shields.io/packagist/v/cyrildewit/php-maps-urls.svg?style=flat-square)](https://packagist.org/packages/cyrildewit/php-maps-urls)\n[![run-tests](https://github.com/cyrildewit/php-maps-urls/workflows/run-tests/badge.svg)](https://github.com/cyrildewit/php-maps-urls/actions)\n[![StyleCI](https://styleci.io/repos/133079607/shield?style=flat-square)](https://styleci.io/repos/133079607)\n[![Codecov branch](https://img.shields.io/codecov/c/github/cyrildewit/php-maps-urls/master.svg?style=flat-square)](https://codecov.io/gh/cyrildewit/php-maps-urls)\n[![Total Downloads](https://img.shields.io/packagist/dt/cyrildewit/php-maps-urls.svg?style=flat-square)](https://packagist.org/packages/cyrildewit/php-maps-urls)\n[![License](https://img.shields.io/github/license/cyrildewit/php-maps-urls.svg?style=flat-square)](https://github.com/cyrildewit/php-maps-urls/blob/1.x/LICENSE)\n\nThis package allows you to build URLs for the [Google Maps URLs API](https://developers.google.com/maps/documentation/urls/guide).\n\nHere's a quick example:\n\n```php\nuse CyrildeWit\\MapsUrls\\UrlGenerator;\nuse CyrildeWit\\MapsUrls\\Actions\\SearchAction;\nuse CyrildeWit\\MapsUrls\\Actions\\DirectionsAction;\n\n$searchAction = (new SearchAction())\n    -\u003esetQuery('The Netherlands Amsterdam');\n$searchUrl = (new UrlGenerator($searchAction))-\u003egenerate();\n\n$directionsAction = (new DirectionsAction())\n    -\u003esetOrigin('The Netherlands Amsterdam')\n    -\u003esetDestination('The Netherlands Utrecht');\n$directionsUrl = (new UrlGenerator($directionsAction))-\u003egenerate();\n```\n\n## Overview\n\nThis package provides a convenient way to generate URLs for the Google Maps URLs API. Each action has its own abstraction that can be used to generate a URL. For more information about this API, head over to the [Google Maps URLs API documentation](https://developers.google.com/maps/documentation/urls/guide).\n\n## Documentation\n\n### Table of contents\n\n1. [Getting Started](#getting-started)\n    * [Requirements](#requirements)\n    * [Installation](#installation)\n2. [Usage](#usage)\n   * [Generating a URL](#generating-a-url)\n   * [Actions](#actions)\n      * [Search](#search)\n      * [Directions](#directions)\n      * [Displaying a map](#displaying-a-map)\n      * [Display a Street View panorama](#display-a-street-view-panorama)     \n3. [Credits](#credits)\n4. [License](#license)\n\n## Getting Started\n\n### Requirements\n\nThis package requires **PHP 7.4+**.\n\n#### Version information\n\n| Version | Status         | PHP Version    |\n|---------|----------------|----------------|\n| ^1.0    | Active support | \u003e= 7.4.0       |\n\n### Installation\n\nYou can install this package via Composer using:\n\n```sh\ncomposer require cyrildewit/php-maps-urls\n```\n\n## Usage\n\n### Generating a URL\n\nThe `CyrildeWit\\MapsUrls\\UrlGenerator` class is responsible for generation the URLs. The constructor accepts an instance of an action class. Action classes extends `CyrildeWit\\MapsUrls\\Actions\\AbstractAction`.\n\n```php\nuse CyrildeWit\\MapsUrls\\UrlGenerator;\nuse CyrildeWit\\MapsUrls\\Actions\\SearchAction;\n\n$searchAction = (new SearchAction())\n    -\u003esetQuery('Eindhoven, Nederland');\n$searchUrl = (new UrlGenerator($searchAction))-\u003egenerate();\n```\n\nOutput `$searchUrl`: `https://www.google.com/maps/search/?api=1\u0026query=Eindhoven,%20Nederland`\n\n### Actions\n\nThe Google Maps URLs API allows you to generate a URL that performs a certain actions. These actions can be configured by using one of the provided action classes.\n\n#### Search\n\nFrom the official documentation: \"Launch a Google Map that displays a pin for a specific place, or perform a general search and launch a map to display the results.\"\n\n###### Query\n\nTo set the query of the search action, you can call the `setQuery(string $query)` method.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\SearchAction;\n\n$searchAction = (new SearchAction())\n    -\u003esetQuery('Eindhoven, Nederland');\n```\n\nThe query parameter may also consist of latitude/longitude coordinates. You can add them together yourself or make use of the `setCoordinates(float $latitude, float $longitude)` method.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\SearchAction;\n\n$searchAction = (new SearchAction())\n    -\u003esetQueryCoordinates(47.5951518, -122.3316393);\n```\n\n###### Query Place ID\n\nIf you want to specify the optional place ID for a search action, you can add it using the `setQueryPlaceId(string $placeId)` method.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\SearchAction;\n\n$searchAction = (new SearchAction())\n    -\u003esetQueryPlaceId('ChIJn8N5VRvZxkcRmLlkgWTSmvM');\n```\n\n###### Magic make constructor\n\nTo instantiate a search action with initial query parameters values, you can make use of the magic `SearchAction::make(array $options)` method.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\SearchAction;\n\n$searchAction = SearchAction::make([\n    'query' =\u003e 'Eindhoven, Nederland',\n    'query_place_id' =\u003e 'ChIJn8N5VRvZxkcRmLlkgWTSmvM',\n]);\n```\n\n#### Directions\n\nFrom the official documentation: \"Request directions and launch Google Maps with the results.\"\n\n###### Origin\n\nThe origin can be defined using method `setOrigin(string $origin)`.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DirectionsAction;\n\n$directionsAction = (new DirectionsAction())\n    -\u003esetOrigin('Eindhoven, Nederland');\n```\n\n###### Origin Place ID\n\nThe origin place ID can be defined using method `setOriginPlaceId(string $placeId)`.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DirectionsAction;\n\n$directionsAction = (new DirectionsAction())\n    -\u003esetOrigin('Eindhoven, Nederland')\n    -\u003esetOriginPlaceId('ChIJn8N5VRvZxkcRmLlkgWTSmvM');\n```\n\n###### Destination\n\nThe destination can be defined using method `setDestination(string $destination)`.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DirectionsAction;\n\n$directionsAction = (new DirectionsAction())\n    -\u003esetDestination('Monnickendam, Nederland');\n```\n\n###### Destination Place ID\n\nThe destination place ID can be defined using method `setDestinationPlaceId(string $placeId)`.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DirectionsAction;\n\n$directionsAction = (new DirectionsAction())\n    -\u003esetDestination('Monnickendam, Nederland')\n    -\u003esetDestinationPlaceId('ChIJTZfQeLgFxkcRQhAYGf9HbrU');\n```\n\n###### Travel Mode\n\nThe travel mode can be defined using method `setTravelMode(string $travelmode)`. The valid options are:\n\n* `driving`\n* `walking`\n* `bicycling`\n* `transit`\n\nThese options can be referenced using the constants defined in `CyrildeWit\\MapsUrls\\Enums\\TravelMode`.\n\n```php\nCyrildeWit\\MapsUrls\\Enums\\TravelMode::DRIVING;\nCyrildeWit\\MapsUrls\\Enums\\TravelMode::WALKING;\nCyrildeWit\\MapsUrls\\Enums\\TravelMode::BICYCLING;\nCyrildeWit\\MapsUrls\\Enums\\TravelMode::TRANSIT;\n```\n\nExample:\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DirectionsAction;\nuse CyrildeWit\\MapsUrls\\Enums\\TravelMode;\n\n$directionsAction = (new DirectionsAction())\n    -\u003esetTravelmode(TravelMode::BICYCLING);\n```\n\nThe `CyrildeWit\\MapsUrls\\Exceptions\\InvalidTravelMode` exception will be thrown when an invalid travel mode is provided.\n\n###### Direction Action\n\nThe direction action can be defined using method `setDirectionAction(string $directionAction)`. The only valid option is `navigate`. You can use the `NAVIGATE` constant in `DirectionAction` class for convenience.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DirectionsAction;\nuse CyrildeWit\\MapsUrls\\Enums\\DirectionAction;\n\n$directionsAction = (new DirectionsAction())\n    -\u003esetDirectionAction(DirectionAction::NAVIGATE);\n```\n\nThe `CyrildeWit\\MapsUrls\\Exceptions\\InvalidDirectionAction` exception will be thrown when an invalid direction action is provided.\n\n###### Waypoints\n\nThe waypoints can be defined using method `setWaypoints(array $waypoints)`.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DirectionsAction;\n\n$directionsAction = (new DirectionsAction())\n    -\u003esetWaypoints([\n        'Berlin,Germany',\n        'Paris,France'\n    ]);\n```\n\n###### Waypoint place IDs\n\nWaypoint place IDs can be defined using method `setWaypointPlaceIds(array $placeIds)`.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DirectionsAction;\n\n$directionsAction = (new DirectionsAction())\n    -\u003esetWaypoints([\n        'Berlin,Germany',\n        'Paris,France'\n    ])\n    -\u003esetWaypointPlaceIds([\n        'ChIJAVkDPzdOqEcRcDteW0YgIQQ',\n        'ChIJD7fiBh9u5kcRYJSMaMOCCwQ'\n    ]);\n```\n\n###### Magic make constructor\n\nTo instantiate a directions action with initial query parameters values, you can make use of the magic `DirectionsAction::make(array $options)` method.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DirectionsAction;\nuse CyrildeWit\\MapsUrls\\Enums\\TravelMode;\nuse CyrildeWit\\MapsUrls\\Enums\\DirectionAction;\n\n$directionsAction = DirectionsAction::make([\n    'origin' =\u003e 'Eindhoven, Nederland',\n    'origin_place_id' =\u003e 'ChIJn8N5VRvZxkcRmLlkgWTSmvM',\n    'destination' =\u003e 'Monnickendam, Nederland',\n    'destination_place_id' =\u003e 'ChIJTZfQeLgFxkcRQhAYGf9HbrU',\n    'travelmode' =\u003e TravelMode::DRIVING,\n    'dir_action' =\u003e DirectionAction::NAVIGATE,\n    'waypoints' =\u003e [\n        'Berlin,Germany',\n        'Paris,France'\n    ],\n    'waypoint_place_ids' =\u003e [\n        'ChIJAVkDPzdOqEcRcDteW0YgIQQ',\n        'ChIJD7fiBh9u5kcRYJSMaMOCCwQ'\n    ],\n]);\n```\n\n#### Displaying a map\n\nFrom the official documentation: \"Launch Google Maps with no markers or directions.\"\n\n###### Map action\n\nThe `map_action` query parameter is required and is therefore added by default with value `map`.\n\n###### Center\n\nThe center of the map can be defined by setting the coordinates using method `setCenter(float $latitude, float $longitude)`.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DisplayMapAction;\n\n$displayMapAction = (new DisplayMapAction())\n    -\u003esetCenter(-33.8569, 151.2152);\n```\n\n###### Zoom\n\nThe zoom level of the map can be defined by using method `setZoom(int $zoom)`.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DisplayMapAction;\n\n$displayMapAction = (new DisplayMapAction())\n    -\u003esetZoom(10);\n```\n\n###### Base Map\n\nThe base map can be defined using method `setBaseMap(string $baseMap)`. The valid options are:\n\n* `none`\n* `traffic`\n* `bicycling`\n\nThese options can be referenced using the constants defined in `CyrildeWit\\MapsUrls\\Enums\\TravelMode`.\n\n```php\nCyrildeWit\\MapsUrls\\Enums\\BaseMap::NONE;\nCyrildeWit\\MapsUrls\\Enums\\BaseMap::TRAFFIC;\nCyrildeWit\\MapsUrls\\Enums\\BaseMap::BICYCLING;\n```\n\nExample:\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DisplayMapAction;\nuse CyrildeWit\\MapsUrls\\Enums\\BaseMap;\n\n$displayMapAction = (new DisplayMapAction())\n    -\u003esetBaseMap(BaseMap::TRAFFIC);\n```\n\nThe `CyrildeWit\\MapsUrls\\Exceptions\\InvalidBaseMap` exception will be thrown when an invalid base map is provided.\n\n###### Layer\n\nThe layer can be defined using method `setLayer(string $layer)`. The valid options are:\n\n* `none`\n* `transit`\n* `traffic`\n* `bicycling`\n\nThese options can be referenced using the constants defined in `CyrildeWit\\MapsUrls\\Enums\\Layer`.\n\n```php\nCyrildeWit\\MapsUrls\\Enums\\Layer::NONE;\nCyrildeWit\\MapsUrls\\Enums\\Layer::TRANSIT;\nCyrildeWit\\MapsUrls\\Enums\\Layer::TRAFFIC;\nCyrildeWit\\MapsUrls\\Enums\\Layer::BICYCLING;\n```\n\nExample:\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DisplayMapAction;\nuse CyrildeWit\\MapsUrls\\Enums\\Layer;\n\n$displayMapAction = (new DisplayMapAction())\n    -\u003esetLayer(Layer::TRAFFIC);\n```\n\nThe `CyrildeWit\\MapsUrls\\Exceptions\\InvalidLayer` exception will be thrown when an invalid layer is provided.\n\n###### Magic make constructor\n\nTo instantiate a display street view panorama action with initial query parameters values, you can make use of the magic `DirectionsAction::make(array $options)` method.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DirectionsAction;\nuse CyrildeWit\\MapsUrls\\Enums\\BaseMap;\nuse CyrildeWit\\MapsUrls\\Enums\\Layer;\n\n$displayMapAction = DirectionsAction::make([\n     'center' =\u003e [-33.8569, 151.2152],\n     'zoom' =\u003e 10,\n     'basemap' =\u003e BaseMap::BICYCLING,\n     'layer' =\u003e Layer::TRANSIT,\n]);\n```\n\n#### Display a Street View panorama\n\nFrom the official documentation: \"Launch an interactive panorama image.\"\n\n###### Map action\n\nThe `map_action` query parameter is required and is therefore added by default with value `pano`.\n\n###### Viewpoint\n\nThe viewpoint can be defined using method `setViewpoint(float $latitude, float $longitude)`.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DisplayStreetViewPanoramaAction;\n\n$displayStreetViewPanoramaAction = (new DisplayStreetViewPanoramaAction())\n    -\u003esetViewpoint(48.857832, 2.295226);\n```\n\n###### Panorama ID\n\nThe panorama ID can be defined using method `setPanoramaId(string $id)`.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DisplayStreetViewPanoramaAction;\n\n$displayStreetViewPanoramaAction = (new DisplayStreetViewPanoramaAction())\n    -\u003esetPanoramaId('tu510ie_z4ptBZYo2BGEJg');\n```\n\n###### Heading\n\nThe heading can be defined using method `setHeading(int $degrees)`. Only values from 180 to 360 degrees are expected.\n\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DisplayStreetViewPanoramaAction;\n\n$displayStreetViewPanoramaAction = (new DisplayStreetViewPanoramaAction())\n    -\u003esetHeading(120);\n```\n\nThe `CyrildeWit\\MapsUrls\\Exceptions\\InvalidHeading` exception will be thrown when an invalid heading is provided.\n\n###### Pitch\n\nThe pitch can be defined using method `setPitch(int $degrees)`. Only values from -90 to 80 degrees are expected.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DisplayStreetViewPanoramaAction;\n\n$displayStreetViewPanoramaAction = (new DisplayStreetViewPanoramaAction())\n    -\u003esetPitch(40);\n```\n\nThe `CyrildeWit\\MapsUrls\\Exceptions\\InvalidPitch` exception will be thrown when an invalid heading is provided.\n\n###### Fov\n\nThe pitch can be defined using method `setFov(int $degrees)`. Only values from -10 to 100 degrees are expected.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DisplayStreetViewPanoramaAction;\n\n$displayStreetViewPanoramaAction = (new DisplayStreetViewPanoramaAction())\n    -\u003esetFov(80);\n```\n\nThe `CyrildeWit\\MapsUrls\\Exceptions\\InvalidFov` exception will be thrown when an invalid heading is provided.\n\n###### Magic make constructor\n\nTo instantiate a display street view panorama action with initial query parameters values, you can make use of the magic `DirectionsAction::make(array $options)` method.\n\n```php\nuse CyrildeWit\\MapsUrls\\Actions\\DirectionsAction;\n\n$displayStreetViewPanoramaAction = DirectionsAction::make([\n    'viewpoint' =\u003e [48.857832, 2.295226],\n    'pano' =\u003e 'tu510ie_z4ptBZYo2BGEJg',\n    'heading' =\u003e 120,\n    'pitch' =\u003e 40,\n    'fov' =\u003e 80,\n]);\n```\n\n## Credits\n\n* **Cyril de Wit** - _Creator_ - [cyrildewit](https://github.com/cyrildewit)\n\nSee also the list of [contributors](https://github.com/cyrildewit/php-maps-url/graphs/contributors) who participated in this project.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyrildewit%2Fphp-maps-urls","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyrildewit%2Fphp-maps-urls","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyrildewit%2Fphp-maps-urls/lists"}