Building Your Startup With PHP: Geolocation and Google Places

Final product image
What You'll Be Creating

This is part three of the Building Your Startup With PHP series on Tuts+. In this series, I'm guiding you through launching a startup from concept to reality using my Meeting Planner app as a real life example. Every step along the way, we'll release the Meeting Planner code as open source examples you can learn from.

In this part, we're going to build some of the underlying infrastructure for the concept of Places where people can schedule meetings. We'll cover the basics of working with Places, building on our database schema, integrating HTML5 Geolocation and APIs for Google Maps and Google Places. The idea is to use these features to make choosing the location for your meetings quick and easy. We con't cover all of the fit and finish in this episode—but we'll cover more of that in an upcoming tutorial.

All of the code for Meeting Planner is written in the Yii2 Framework for PHP and leverages Bootstrap and JavaScript. If you'd like to learn more about Yii2, check out our parallel series Programming With Yii2 at Tuts+.

Just a reminder, I do participate in the comment threads below. I'm especially interested if you have different approaches or additional ideas, or want to suggest topics for future tutorials. Feature requests for Meeting Planner are welcome as well.

Building the Places Functionality

Before users can schedule meetings, we need them to be able to find and suggest their favorite places. Initially, for simplicity, we'll build Place searching and creation functionality separately from the scheduling feature.

There are three ways for users to add places:

  1. Using HTML5 Geolocation, they can look up their current location via WiFi and add this as a place.
  2. Using the Google Places API, they can search for a place in the Places database using the autocomplete. Eventually, when we know their current location, we can restrict the search results to nearby places.
  3. Manual entry. Users can enter an address and description for their own place, like an office or home.

Extending the Place Schema

Here's the schema for Places we developed in Part Two:

Note, there isn't any geolocation associated with a Place in this table. That's because the MySQL InnoDB engine doesn't support spatial indexes. So I've created a secondary table using the MyISAM table for Places' geolocation coordinates. It's the Place_GPS table:

As I'm in rapid prototyping mode, I'm going to extend the schema using Yii's migrations and I may ultimately make future adjustments as well.

To extend the schema, we create a new migration in Yii:

And provide the following code:

This will add columns for slug, website, full_address, vicinity, and notes. The slug is a URL-friendly address for displaying the Place view page which Yii can generate for us automatically. The other fields will sometimes be updated by users and other times populated from the Google Places API.

To run the migration, we enter the following:

You should see the following:

Updating the CRUD Code

If you visit the Places page, e.g. http://localhost:8888/mp/index.php/place/create, you'll see the default Yii2 auto-generated form with all of our schema fields:

Create Place The Default Yii2 Form

For this tutorial, I re-ran Yii's code generator, Gii, using the steps from Part Two to build code for the new database schema. I instructed Gii to overwrite the CRUD code from earlier. 

Note: It may be easiest for you to replace your sample source from part two with sample source from this part. See the Github link to the upper right.

You also will need to update our vendor libraries with composer to integrate support for the 2amigOS Yii2 Google Maps and Places libraries. Here's a portion of our composer.json file:

Then, run composer update to download the files:

Three Different Ways to Add Places

We're actually going to build three different controller actions and forms for each of these types of places. Remember that we must also integrate the related model, PlaceGPS, to store the GPS coordinates for each place no matter how the user adds it.

Adding Places to the Navigation Bar

To add a Places link to the navigation bar, edit /views/layouts/main.php. This is the default page layout which Yii wraps all of our view files with. It includes the header, Bootstrap navigation bar, and footer.

Below in $menuItems, I add an array entry for the Place menu:

The Place Index View

The Place Index View will look like this after we add buttons for the three ways to add Places:

Meeting Planner Place Index Page

In /views/place/index.php, we can add the three add place buttons:

And, we can customize the columns that appear in the view, including building a custom column to a Place method that displays the friendly name for Place Type:

Here's a subset of the Place Type methods in /models/Place.php:

Notice, we've not yet addressed login state or user ownership of places. We'll revisit this in the next tutorial. Because of the complexity and scope of this stage, we'll leave a handful of finish items for a later tutorial.

Adding Places With HTML5 Geolocation

One scenario for adding places is to create a place for your home or office. Rather than require that users type this information in by hand, we can often automatically generate this with HTML5 Geolocation.

HTML5 Geolocation uses your WiFi address to determine GPS points for your current location. It does not work with cellular / mobile connections and it's not foolproof. 

The user will likely need to grant permission to their browser for geolocation for this feature to work. Look for a popup below the address bar as shown below:

Chrome Browser Asking Permission for Geolocation

I'm using the geoposition script from estebanav to support HTML5 Geolocation with the widest possible browser support.

Adding the Place Controller Action for Geolocation

In frontend/controllers/PlaceController.php, we'll create a new method for the Create_geo action:

Because the form is not yet being submitted, Yii will render the create_geo view to display the form.

In frontend/views/place/create_geo.php, we'll include _formGeolocate.php:

Let's look at the first part of _formGeolocate. We have to include the JavaScript for Geoposition.js as well as our own custom geolocation code to integrate geoposition with our form. The way Yii does this is with Asset Bundles. You define an Asset Bundle for different pages and this allows you to optimize which JS and CSS is loaded on different areas of your application. We'll create LocateAsset first:

In frontend/assets/LocateAsset.php, we'll define the JavaScript we need to include:

LocateAsset preloads the Google Maps API, the geoPosition library and our custom Locate.js code which is shown below:

Basically, geolocation is initiated when the user triggers beginSearch. The Geoposition code calls the success function when it returns with the user's location. We customize the success function to display a map at the location and to populate our hidden form fields with the latitude and longitude returned. When the user posts the form, the location coordinates will be available to our Web app. 

Here's the code within Success() which populates the form fields with the location coordinates:

The rest of _formGeolocate.php is split into two equal halves. On the left side, we provide the form fields for the user to enter in with the Geolocation data and the hidden fields we need to support the JavaScript. On the right side, we leave space for a button to trigger Geolocation and for displaying the Map. The success() function fills the <article> tag with the map.

Here's what the form looks like initially:

Meeting Planner Create Place by Geolocation Form

Click on the Lookup Location button to initiate geolocation. Again, look for a permissions request in the browser navigation bar.

Once your location is found, we'll show your location on a map:

Meeting Planner Create Place by Geolocation After Mapping

Note: I've set the delay for Geolocation to five seconds, but sometimes you'll need to reload the page to get the correct response after granting permission. Certain WiFi locations are less determinate than others.

Let's take a look at the Meeting Controller form submit code:

For now, we're just putting in a placeholder for the created_by user and leaving error handling for later (sorry purists, that's not the focus of this tutorial at the moment).

When the form posts and a Place is created, we'll grab the geolocation point from the form (those hidden fields filled by the Locate.js script) and add a row to the related Place table PlaceGPS

As I mentioned in part two, we separate the geolocation data in a different table because the MySQL InnoDB engine doesn't support spatial indexes. This will also improve the performance of queries to find the closest meeting places between two users. 

Here's the addGeometryByPoint method in the Place.php model:

Here's what the Place Index page should look like after the record is saved:

Meeting Planner Place Index Page with New Places

If you'd like to see another implementation of HTML5 Geolocation for Yii 1.x, check out How to Use Zillow Neighborhood Maps and HTML5 Geolocation.

Displaying Places on Google Maps

If you click the view command icon associated with our new place in the index view above, you'll see this:

Meeting Planner View A Place With Google Maps

We've customized the Gii-generated view page and added code to draw the Google Map using the Yii2 Google Maps extension.

Here's the View action in PlaceController.php:

Here's the getLocation method in the Place.php model. It fetches the location coordinates from the PlaceGPS table:

Here's a portion of the view file which renders the page. The left side consists of a standard Yii2 DetailView widget for now. The right side generates the code which draws the map:

Adding From the Google Places API

The Google Places autocomplete feature is an incredibly fast and simple way for users to add meeting places. I'm using the Yii2 Google Places extension by 2amigOS.

Meeting Planner The Google Place Autocomplete Service

In PlaceController.php, we'll add an action for Create_place_google:

The /frontend/views/place/create_place_google.php file will display the form and initialize the JavaScript needed to support autocomplete:

Developer Petra Barus provided a Google Places extension for Yii1.x. For this tutorial, I hand coded the basic support for Yii2. However, Barus was kind enough to release a Yii2 extension just a few days afterwards. I haven't yet integrated his code. Here's his latest Yii2 Google Places Autocomplete extension.

Here's the MapAsset bundle I'm creating for the associated JavaScript that will be needed:

Here's the _formPlaceGoogle.php form code:

There is a searchbox field which will accept the user's autocompletion input. There are also a variety of hidden fields which our JavaScript will load with the results from the Google Places service.

Here is the create_place.js which accomplishes all the "magic":

The setupListeners() method links our searchbox field to the Google Places autocomplete service. When a place_changed event occurs, populateResult() is called to fill the hidden fields on the form with data from Google and load the map which is displayed in the right half of the form.

Meeting Planner Add From Google Place Autocomplete After LoadMap

You can use the browser debugger to inspect the hidden fields after they've been filled in with form data via JavaScript. This data will be posted with the form on submission so we can add them to the Place database.

Meeting Planner Hidden Fields from Google Places Autocomplete

Here's the remaining element of the PlaceController Create_place_google save action:

It's quite similar to the Create_geo action. We have a separate Place.php model method to simplify the location data collection. Here's addGeometry():

Setting Geographic Boundary Filters for Autocomplete Search

The Places Autocomplete service also allows you to setup a geographic bounding rectangle to filter your search within. When the user begins to type, the autocomplete will only use places within ten miles of them. Since we haven't set up the user's current location as a session variable, I'm not implementing the bounding rectangle at the moment. But we can do this later. Here's an example of setupBounds():

Manually Adding Places

The third way users can add places is by manually providing details and address information. When they submit the form, we'll try to look up the address and obtain the geolocation data, but it's okay if we can't find that. The manual approach will allow users to add places such as their house or an office which they may not want to associate with Google mapping data.

Here's what the form looks like:

Meeting Planner Manually Add Place

Here's what the PlaceController.php submission action code looks like. We're using the 2Amigos Maps Geocoding client to look up the location from full_address. There are obviously a lot of improvements we can make to encourage the user to enter in the full address or perhaps lets them connect a Google Places location at a later date.

What's Next? 

The scope of this tutorial proved quite large. I wanted to show you various components involved in geolocation and map usage without skipping over too many elements of the coding process. So, obviously, there are a lot of shortcuts at the moment. In the next tutorial, we'll continue to refine Places within the overall system, focusing on user permissions, access controls, adding support for the user's favorite places, and other refinements.

Please feel free to post your questions and comments below. I'm especially interested if you have different approaches or additional ideas, or want to suggest topics for future tutorials. You can also reach me on Twitter @reifman or email me directly. Follow my Tuts+ instructor page to see future articles in this series.

Related Links

Tags:

Comments

Related Articles