JumpGate App Walkthrough: Set Up


Introduction

In this walk through we will be building a simple to do app starting with JumpGate. It really should not take too long so feel free to follow along.

During this walkthrough I will be assuming you are using the prerequisites listed below and your set up using valet. If you are using homestead or something else, modify the valet sections to suit your environment.

{info} You can see the source code at GitHub.

This step is stored as a branch called set up.

Prerequisites

  1. Node
    1. npm install npm@latest -g
  2. Yarn
    1. npm install -g yarn
  3. Composer
  4. Homebrew
  5. PHP/MySql
    1. Homestead
    2. Valet
      1. brew update
      2. brew install homebrew/php/php70
      3. brew install php701.xdebug
      4. brew install mariadb
      5. composer global require laravel/valet
      6. valet install
      7. valet domain dev
    3. Sequel Pro

Directories

First, go make the directory you want your projects to live in. I use ~/Code/ but use anything you want.

In your terminal go into that directory (cd ~/Code) and run valet park. This will let valet start sharing the directory. Make a directory inside this one with your project name. We will be using ToDo.

cd ~/Code
valet park
mkdir ToDo
cd Todo

Now we will bring in JumpGate.

Start Installation

To begin, we need to pull it in and get the basic files set up.

git clone git@github.com:JumpGateio/JumpGate.git ./
composer install
php artisan jumpgate:setup --social-users --force

This is doing a few simple things. We grab the web app from github and install all of it's dependencies. Next, we let jumpgate do the tasks we need. This will create our .env file, generate a site key, run yarn and npm run dev.

Since we want users in our to-do app, we tell jumpgate to set up with users using the --social-users flag. Using --social-users gets the jumpgate/users package and also the laravel/socialite package for us. Also, since this is a fresh app, we use --force to allow the users package to overwrite some of our existing files.

Once this is done, we need to set up our database before continuing.

{info} Have a look at the overview to see what packages and versions are included.

Database

With installation started, lets look to the database. Since we will need one we should work on the design that we will need and get teh database set up.

Open up sequel pro and set up a connection to localhost. It should have a host of 127.0.0.1, a username of root and that's it. Save and connect to the host and click the "Choose database..." drop down to select "Add Database". Name it "todo" and click "Add". That's it! You now have a database waiting for data.

In your project, open .env and add the database details as follows.

DB_CONNECTION=mysql
DB_HOST="127.0.0.1"
DB_PORT=3306
DB_DATABASE=todo
DB_USERNAME=root
DB_PASSWORD=

Now, we need to configure how we want our users to work.

User Config

We need to tell the user package how we want users to work. In this app, I want to allow social authentication through google and not allow standard registration. So I want to change the following settings in the config/jumpgate/users.php file.

'require_email_activation' => false,
'enable_social' => true,
'social_auth_only' => true,

This will tell the package that we don't need to activate, we will be using social auth and we will not be using standard auth. Enabling social auth adds some migrations and seeds to our app for us.

{primary} Before moving on, you could look at the config/jumpgate/acl.php to see if you want to change how the acl tables are set up.

Finish Installation

Now that we have our configs how we want them, it's time to finish installation. By default, the users package adds a set of links to our navbar to allow standard login. Since we are using social auth through google, we need to change this. Open app/Http/Composers/Menu.php. You need to change the default generateRightMenu() method to a more social friendly set of links.

You want the method to look like this when done

    /**
     * Adds items to the menu that appears on the right side of the main menu.
     */
    private function generateRightMenu()
    {
        $rightMenu = \Menu::getMenu('rightMenu');

        if (auth()->guest()) {
            $rightMenu->link('login', function (Link $link) {
                $link->name = 'Login';
                $link->url  = route('auth.social.login', ['google']);
            });
        }

        if (auth()->check()) {
            $rightMenu->dropdown('user', auth()->user()->display_name, function (DropDown $dropDown) {
                $dropDown->link('user_logout', function (Link $link) {
                    $link->name = 'Logout';
                    $link->url  = route('auth.logout');
                });
            });
        }
    }

In this method we are now allowing users to log in through google. This is how the users package expects social auth links to look. The extra parameter is the provider you are letting them log in through. This could be anything, but for our app we are using google. Since we disabled registration, we removed that link entirely.

{info} You can learn more about the link package by viewing the quick start guide.

Now that everything else is done, we need to get our database set up to handle users. To do this we call one simple command.

php artisan jumpgate:user-database 

The user-database command handles setting up all the database tables for users and seeding them for you. As of now, our site and database are ready to get started. You should be able to see your site at http://todo.dev.

Social Auth

Thanks to using --social-users we already have laravel socialite, so we don't need to require/discover any new packages. However, if you only used --users and now want social users, run the following commands.

composer require laravel/socialite
php artisan package:discover

Socialite is a laravel package that makes dealing with social authentication very easy. A community has formed around this package and they create authentication helpers for many common APIs. You can find all the options at the Laravel Socialite Providers site. Since we want google we get off a bit easy. It's included in Laravel Socialite already.

Let's generate our site's API details. We have a full guide on this you can follow to get your details set up. This guide will walk you through generating your client details and setting up all of your .env file values.

Now we need to set it up in our configs. There are two places we add social provider details to: config/services.php and config/jumpgate/users.php.

The services one is pretty straight forward. This file is used if you want to interact with the API.

    'google'     => [
        'client_id'     => env('GOOGLE_KEY'),
        'client_secret' => env('GOOGLE_SECRET'),
        'redirect'      => env('GOOGLE_REDIRECT_URI'),
    ],

In the user's config file, we need to give it a bit more detail. This file is used to determine how we connect to a given provider through Socialite.

    'providers' => [
        [
            'driver' => 'google',
            'scopes' => [
                'https://www.googleapis.com/auth/userinfo.email',
            ],
            'extras' => [
                'approval_prompt' => 'auto',
                'access_type'     => 'offline',
            ],
        ],
        [
            'driver' => 'github',
            'scopes' => [],
            'extras' => [],
        ],
    ],

This is a fairly standard set of options for google auth. Feel free to change it however you need to.

So as of now, we have everything we need for the configs. Now we need the User model to understand our social set up. Open App\Models\User and add the \JumpGate\Users\Traits\HasSocials trait to the class.

use \JumpGate\Users\Traits\HasSocials;

class User extends BaseModel
{
    use HasSocials;
}

That's all it takes to get our users to interact with social auth. You should take the time to test this. Go to your homepage (http://todo.dev/) and click "Login" in the top right. It should redirect you to the Google auth page. Select your email and click "Allow". This should redirect you back to your site as a logged in user. You should also see your email in the top right as a drop down.

Gravatar

If you would rather it show a gravatar icon instead of your email. It's pretty easy to do. First, add the following method to your User model.

    /**
     * Generate a gravatar from a user's email.
     *
     * @return string
     */
    public function getGravatarAttribute()
    {
        $google    = $this->getProvider('google');
        $emailHash = md5(strtolower(trim($google->email)));

        return 'https://www.gravatar.com/avatar/' . $emailHash;
    }

Next, open up app/Http/Composers/Menu.php and change the user drop down.

It should look like this when done

if (auth()->check()) {
     $rightMenu->dropdown('user', auth()->user()->gravatar, function (DropDown $dropDown) {
         $dropDown->type  = 'auth';
         $dropDown->right = true;

         $dropDown->link('user_logout', function (Link $link) {
             $link->name = 'Logout';
             $link->url  = route('auth.logout');
         });
     });
 }

The menu views already handle this for you. So just refresh your app and you will see the gravatar icon instead of text.

Next up, let's start writing code!

{info} The walkthrough continues in Setting up your database.