Querying GitHub Projects V2 with GraphQL in Laravel

GitHub and GraphQL logos

Note: I previously wrote about using plain PHP to query GitHub Projects V2. In this post I offer some tips for querying using Laravel.

GitHub’s new Projects are not accessible via the older REST API. Working with them programmatically involves learning some GraphQL, which can be a headache, the first time you encounter it. Here’s my approach, using Laravel.

Authentication

Get a GitHub personal access token, limiting its permissions as appropriate to your app. Then add to your .env:

GH_TOKEN=[your token]

HTTP requests

We can standardise GitHub GraphQL queries by using an HTTP facade macro. In app/Providers/AppServiceProvider.php, add to the boot() method:

    /**
     * Make request to GitHub using the GraphQL API.
     *
     * $query - a GraphQL query string
     * $variables - an array of GraphQL variables
     *
     * Call like: $data = Http::githubGraphQL($query, $variables)->throw()->json()['data'];
     */
    Http::macro('githubGraphQL', function (string $query, array $variables) {
        return Http::withHeaders([
            'Accept' => 'application/vnd.github+json',
            'Authorization' => 'Bearer ' . env('GH_TOKEN')
        ])->post('https://api.github.com/graphql', [
            'query' => $query,
            'variables' => $variables,
        ]);
    });

GitHubProjects model

This sample app/Models/GitHubProjects.php shows you the sort of query you can run:

    <?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Facades\Http;

class GitHubProjects extends Model
{
    use HasFactory;

    /**
     * getFirstN - get first N projects for the GitHub organisation, ordered by
     * title
     *
     * @param integer $count - number of projects to return
     * @return array
     */
    public static function getFirstN(int $count = 20): array
    {
        $projects = Http::githubGraphQL(
            <<<EOD
            query getFirstN(\$count: Int) {
              organization(login: "MyOrg") {
                projectsV2(first: \$count, orderBy: {field: TITLE, direction: ASC}) {
                  nodes {
                    number
                    id
                    title
                  }
                }
              }
            }
EOD,
            [ "count" => $count ]
        )->throw()->json()['data'];
        return $projects['organization']['projectsV2']['nodes'];
    }


    /**
     * getFirstNIssues
     *
     * @param integer $projectNumber
     * @param integer $count
     * @return array
     */
    public static function getFirstNIssues(int $projectNumber = 1, int $count = 20): array
    {
        $projectId = GitHubProjects::getIdByNumber($projectNumber);
        $issues = Http::githubGraphQL(
            <<<EOD
            # Exclamation mark since projectId is required
            query getFirstNIssues(\$projectId: ID!, \$count: Int) {
              node(id: \$projectId) {
                ... on ProjectV2 {
                  items(first: \$count) {
                    nodes {
                      id
                      fieldValues(first: 8) {
                        nodes {
                          ... on ProjectV2ItemFieldTextValue {
                            text
                            field {
                              ... on ProjectV2FieldCommon {
                                name
                              }
                            }
                          }
                          ... on ProjectV2ItemFieldDateValue {
                            date
                            field {
                              ... on ProjectV2FieldCommon {
                                name
                              }
                            }
                          }
                          ... on ProjectV2ItemFieldSingleSelectValue {
                            name
                            field {
                              ... on ProjectV2FieldCommon {
                                name
                              }
                            }
                          }
                        }
                      }
                      content {
                        ... on DraftIssue {
                          title
                          body
                        }
                        ... on Issue {
                          title
                          assignees(first: 10) {
                            nodes {
                              login
                            }
                          }
                        }
                        ... on PullRequest {
                          title
                          assignees(first: 10) {
                            nodes {
                              login
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
EOD,
            [
              "projectId" => $projectId,
              "count" => $count
            ]
        )->throw()->json()['data'];
        return $issues['node']['items']['nodes'];
    }


    /**
     * getByTitle - search for projects by title
     *
     * @param string $title - search for
     * @return array
     */
    public static function getByTitle(string $title): array
    {
        $projects = Http::githubGraphQL(
            <<<EOD
            query getByName(\$title: String!) {
                organization(login: "MyOrg") {
                    projectsV2(
                        first: 20
                        orderBy: { field: TITLE, direction: ASC }
                        query: \$title
                    ) {
                        nodes {
                            number
                            id
                            title
                        }
                    }
                }
            }
              
EOD,
            [ "title" => $title ]
        )->throw()->json()['data'];
        return $projects['organization']['projectsV2']['nodes'];
    }


    /**
     * getIdByNumber
     *
     * @param integer $number - the integer identifier of the project
     * @return string - the internal GitHub project ID (e.g. PVT_kwDOBWQiz84AH53W)
     */
    private static function getIdByNumber(int $number = 1)
    {
        $project = Http::githubGraphQL(
            <<<EOD
            # Exclamation mark since number is required
            query getIdByNumber(\$number: Int!) {
              organization(login: "MyOrg") {
                projectV2(number: \$number) {
                  id
                }
              }
            }
EOD,
            ['number' => $number]
        )->throw()->json()['data'];
        return $project['organization']['projectV2']['id'];
    }


    /**
     * getProjectFields - get all the (custom) fields associated to a project
     *
     * @param string $projectID - GitHub's reference for the project
     * @return array
     */
    public static function getProjectFields(string $projectID): array
    {
          $fields = Http::githubGraphQL(
            <<<EOD
            query getProjectFields(\$node: ID!) {
              node(id: \$node) {
                ... on ProjectV2 {
                  fields(first: 20) {
                    nodes {
                      ... on ProjectV2Field {
                        id
                        name
                      }
                      ... on ProjectV2IterationField {
                        id
                        name
                        configuration {
                          iterations {
                            startDate
                            id
                          }
                        }
                      }
                      ... on ProjectV2SingleSelectField {
                        id
                        name
                        options {
                          id
                          name
                        }
                      }
                    }
                  }
                }
              }
            }
              
EOD,
            [ "node" => $projectID ]
        )->throw()->json()['data'];
        return $fields['node']['fields']['nodes'];
    }
}

Controller

This is a very basic sample controller method to get you started. In practice you’ll use views:

public function index()
{
    /*
        Search for "MyProject" in projects
        Project number is $projects[0]['number'];
        Project name is $projects[0]['title'];
        Project ID is $projects[0]['id'];
    */
    define('BR', "<br />\n");
    $projects = GitHubProjects::getByTitle('MyProject');

    if (isset($projects[0])) {
        $projectNumber = $projects[0]['number'];
        $issues = GitHubProjects::getFirstNIssues($projectNumber, 50);
        echo "<h1>First 50 issues in MyProject project</h1>\n";
        foreach ($issues as $issue) {
            echo '<b>ID:</b> ' . $issue['id'] . BR;
            echo '<b>Title:</b> ' . $issue['content']['title'] . BR;
            if (isset($issue['content']['assignees']['nodes'][0])) {
                echo '<b>Assignee:</b> ' . $issue['content']['assignees']['nodes'][0]['login'] . BR;
            }
            // Field types
            foreach ($issue['fieldValues']['nodes'] as $field) {
                if (isset($field['text']) && $field['field']['name'] != "Title") {
                    echo '<b>' . $field['field']['name'] . ':</b> ' . $field['text'] . BR;
                }
                if (isset($field['date'])) {
                    echo '<b>' . $field['field']['name'] . ':</b> ' . $field['date'] . BR;
                }
                if (isset($field['name'])) {
                    echo '<b>' . $field['field']['name'] . ':</b> ' . $field['name'] . BR;
                }
            }
            echo BR;
        }
    } else {
        echo "No projects found";
    }
}

Useful resources

The following are invaluable for working with GitHub’s GraphQL API:

Querying GitHub Projects v2 with GraphQL in PHP

Update: you may prefer my post about doing this in Laravel.

GitHub’s new Projects are not accessible via the older REST API. Working with them programmatically involves learning some GraphQL, which can be a headache, the first time you encounter it. Here’s my approach, using PHP.

Set up cURL

You can certainly use an HTTP request library, but sometimes it’s easiest to get your hands dirty with cURL. Here’s the setup:

$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Accept: application/vnd.github+json',
    'Authorization: Bearer '.$_ENV['GH_TOKEN']
));

// Fake user agent, to keep GitHub happy
curl_setopt($ch, CURLOPT_USERAGENT, 'Mozilla/5.0 (Windows NT 5.1; rv:31.0) Gecko/20100101 Firefox/31.0');

// Dev settings (PHP built-in server can't validate)
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

The “dev settings” are there since I’ve been using PHP’s built-in webserver during development. Don’t take those into production!

Generic API class

This class provides a simple wrapper around REST API and GraphQL calls. I’m passing in the cURL handler and calling most methods statically, since I’m not yet modelling the underlying objects.

class GitHub
{
    /**
     * API
     * Make request to GitHub using the standard REST API.
     * See: https://docs.github.com/en/rest
     *
     * @param [CurlHandle Object] $ch - curl handle
     * @param [string] $endpoint - the REST endpoint
     * @return array|stdClass
     */
    public static function api(\CurlHandle $ch, string $endpoint)
    {
        curl_setopt($ch, CURLOPT_URL, 'https://api.github.com/'.$endpoint);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

        $content = curl_exec($ch);
        if (curl_errno($ch)) {
            die("Error:".curl_error($ch));
        }
        return json_decode($content);
    }

    /**
     * GraphQL
     * Make request to GitHub using the newer GraphQL API.
     * See: https://docs.github.com/en/graphql/reference
     * GraphQL Explorer: https://docs.github.com/en/graphql/overview/explorer
     * GraphQL Formatter: https://jsonformatter.org/graphql-formatter
     *
     * @param CurlHandle $ch
     * @param string $query - a GraphQL query string
     * @param array $variables - an array of GraphQL variables
     * @return StdClass
     */
    public static function graphQL(\CurlHandle $ch, string $query, array $variables)
    {
        curl_setopt($ch, CURLOPT_URL, 'https://api.github.com/graphql');
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
        curl_setopt(
            $ch,
            CURLOPT_POSTFIELDS,
            json_encode(['query' => $query, 'variables' => $variables])
        );

        $content = curl_exec($ch);
        if (curl_errno($ch)) {
            die("Error:".curl_error($ch));
        }
        return json_decode($content);
    }
}

Projects class

Various simple methods for obtaining information about projects. I say “simple” but the GraphQL queries take some mastering.

class GitHubProjects
{
    /**
     * getFirstN - get first N projects for the GitHub organisation, ordered by
     * title
     *
     * @param \CurlHandle $ch
     * @param integer $count - number of projects to return
     * @return array
     */
    public static function getFirstN(\CurlHandle $ch, int $count = 20): array
    {
        $projects = GitHub::graphQL(
            $ch,
            <<<EOD
            query getFirstN(\$count: Int) {
              organization(login: "MyOrg") {
                projectsV2(first: \$count, orderBy: {field: TITLE, direction: ASC}) {
                  nodes {
                    number
                    id
                    title
                  }
                }
              }
            }
EOD,
            [ "count" => $count ]
        );
        return $projects->data->organization->projectsV2->nodes;
    }


    /**
     * getFirstNIssues
     *
     * @param \CurlHandle $ch
     * @param integer $projectNumber
     * @param integer $count
     * @return array
     */
    public static function getFirstNIssues(\CurlHandle $ch, int $projectNumber = 1, int $count = 20): array
    {
        $projectId = GitHubProjects::getIdByNumber($ch, $projectNumber);
        $issues = GitHub::graphQL(
            $ch,
            <<<EOD
            # Exclamation mark since projectId is required
            query getFirstNIssues(\$projectId: ID!, \$count: Int) {
              node(id: \$projectId) {
                ... on ProjectV2 {
                  items(first: \$count) {
                    nodes {
                      id
                      fieldValues(first: 8) {
                        nodes {
                          ... on ProjectV2ItemFieldTextValue {
                            text
                            field {
                              ... on ProjectV2FieldCommon {
                                name
                              }
                            }
                          }
                          ... on ProjectV2ItemFieldDateValue {
                            date
                            field {
                              ... on ProjectV2FieldCommon {
                                name
                              }
                            }
                          }
                          ... on ProjectV2ItemFieldSingleSelectValue {
                            name
                            field {
                              ... on ProjectV2FieldCommon {
                                name
                              }
                            }
                          }
                        }
                      }
                      content {
                        ... on DraftIssue {
                          title
                          body
                        }
                        ... on Issue {
                          title
                          assignees(first: 10) {
                            nodes {
                              login
                            }
                          }
                        }
                        ... on PullRequest {
                          title
                          assignees(first: 10) {
                            nodes {
                              login
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
EOD,
            [
              "projectId" => $projectId,
              "count" => $count
            ]
        );
        return $issues->data->node->items->nodes;
    }

    
    /**
     * getByTitle - search for projects by title
     *
     * @param \CurlHandle $ch
     * @param string $title - search for
     * @return array
     */
    public static function getByTitle(\CurlHandle $ch, string $title): array
    {
        $projects = GitHub::graphQL(
            $ch,
            <<<EOD
            query getByName(\$title: String!) {
                organization(login: "MyOrg") {
                    projectsV2(
                        first: 20
                        orderBy: { field: TITLE, direction: ASC }
                        query: \$title
                    ) {
                        nodes {
                            number
                            id
                            title
                        }
                    }
                }
            }
              
EOD,
            [ "title" => $title ]
        );
        return $projects->data->organization->projectsV2->nodes;
    }


    /**
     * getIdByNumber
     *
     * @param \CurlHandle $ch
     * @param integer $number - the integer identifier of the project
     * @return string - the internal GitHub project ID (e.g. PVT_kwDOBWQiz84AH53W)
     */
    private static function getIdByNumber(\CurlHandle $ch, int $number = 1)
    {
        $project = GitHub::graphQL(
            $ch,
            <<<EOD
            # Exclamation mark since number is required
            query getIdByNumber(\$number: Int!) {
              organization(login: "MyOrg") {
                projectV2(number: \$number) {
                  id
                }
              }
            }
EOD,
            ['number' => $number]
        );
        return $project->data->organization->projectV2->id;
    }
}

Using it

I have not included namespacing or autoloading here. In broad terms, it’s simple to use the Projects class:

$projects = Model\GitHubProjects::getByTitle($ch, 'MyProject');
if (is_array($projects) && !empty($projects)) {
    $project = $projects[0];
    var_dump($project);
}

How-to: Laravel 5.1 tutorial; part 1 – installation

It’s been quite a while since we’ve posted anything about Laravel. We’re strictly hobbyist developers here and in web development it’s almost impossible to keep up with the rate of change unless you’re a full time developer (and even then, it’s not easy). This pace of change of course means trouble not only for small-time developers like us, but also for enterprise users who favour stability over bleeding-edge features.

So the recent announcement is timely, that Laravel 5.1 is the first version to offer long term support (LTS). LTS in this case means two years of bug fixes and three years of security updates (as opposed to six months and one year respectively for other releases). And for us, this means that although our version 4 tutorials quickly became obsolete, our version 5 tutorials should have a chance of remaining relevant for the next three years. So we hope this new series will be useful for you, our readers.

Without further ado, let’s dive in.

Prerequisites

These days there’s a phenomenal number of ways to get up and running with a server – Vagrant, Puppet, Chef, Ansible and so on. For the purposes of this tutorial I’m going to assume the most basic requirements:

  • Apache web server (other web servers will work, but we won’t explicitly deal with them)
  • Shell access to the server (preferably SSH)
  • Root access to install Composer globally (not essential)
  • Git must be installed in your environment.
  • PHP >= 5.5.9
  • OpenSSL PHP Extension (probably compiled in to your PHP installation – check with phpinfo();)
    OpenSSL
  • Mbstring PHP Extension
    MBString
  • Tokenizer PHP Extension
    Tokenizer

Install Composer

Composer is an integral part of Laravel these days. It’s used for managing dependencies – external libraries and the like, used by projects. It is also used to install Laravel. While logged in as root, to make Composer available globally, do:


curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin
ln -s /usr/local/bin/composer.phar /usr/local/bin/composer

The official Composer documentation suggests using mv composer.phar composer, but if you use a symbolic link instead, upgrading Composer is as simple as running curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin again.

Install Laravel

There are different ways of approaching this, but the approach I prefer (for its simplicity) is as follows. To install Laravel in the directory that will house your web project (e.g. if that’s under /var/www), enter:

composer create-project laravel/laravel /var/www/new.website.name

There will be a lot of activity in the console as all Laravel’s various components are installed. The new website directory contains a folder “public” and it’s to this you need to direct your web server. So for example, with Apache, create a new configuration file /etc/apache2/sites-available/new.website.name.conf:

<VirtualHost *:80>
ServerName new.website.name
DocumentRoot "/var/www/new.website.name/public"
<Directory "/var/www/new.website.name/public">
allow from all
Options +Indexes
</Directory>
</VirtualHost>

Again, for Apache, enable the new website (e.g.):

a2ensite new.website.name

If you’re using a control panel (CPanel, Plesk, VirtualMin, etc.) your steps will vary. When you then browse to your new site, you should see something like this:

Laravel 5

Configuration

There’s lots you can configure, but here are some basics.

  • Make sure the storage and the bootstrap/cache directories are writeable by the web server. E.g.:
    chown -R www-data:www-data /var/www/new.website.name/storage
    chown -R www-data:www-data /var/www/new.website.name/bootstrap/cache
    find /var/www/new.website.name/storage -type f -exec chmod ug+rw {} \;
    find /var/www/new.website.name/storage -type d -exec chmod ug+rwx {} \;
    find /var/www/new.website.name/bootstrap/cache -type f -exec chmod ug+rw {} \;
    find /var/www/new.website.name/bootstrap/cache -type d -exec chmod ug+rwx {} \;
  • In config/app.php set your time zone (e.g.):
    'timezone' => 'Europe/London',
  • And locale (e.g.):
    'locale' => 'en_GB',

Pretty straightforward stuff really.

How-to: Laravel 4 tutorial; part 6 – virtualised development environment – Laravel Homestead

[easyreview title=”Complexity rating” icon=”geek” cat1title=”Level of experience required, to follow this how-to.” cat1detail=”We’re pulling together a few sophisticated components here, but keep your eye on the ball and you’ll be okay.” cat1rating=”4″ overall=”false”]

Laravel Tutorials

Introduction

It has been a while since I have had time to work on Laravel development or indeed write a tutorial. And since then, I have decommissioned my main web development server in favour of a Synology NAS. Dummy and I use a third party hosting service for hosting our clients’ web sites and our own. This shared hosting service comes with limitations that make it impossible to install Laravel through conventional means

So instead, I’m setting up a virtual development environment, that will run on the same laptop that I use for code development. Once development is complete, I can upload the whole thing to the shared hosting service. Getting this set up is surprisingly complicated, but once you’ve worked through all these steps, you’ll have a flexible and easy-to-use environment for developing and testing your Laravel websites. This article assumes we’re running Windows.

Components

  • virtualbox_iconVirtualBox enables you to run other operating systems on existing hardware, without wiping anything out. Your computer can run Windows and then through VirtualBox, it can run one or more other systems at the same time. A computer within a computer. Or in this case, a server within a computer. Download VirtualBox here and install it.
  • vagrant_iconVagrant enables the automation of much of the process of creating these “virtual computers” (usually called virtual machines). Download Vagrant here and install it.
  • git_iconGit for Windows. If you’re a developer, chances are you know a bit about Git, so I’ll not go into detail here. Suffice it to say that you’ll need Git for Windows for this project: here.
  • PuTTY_iconPuTTY comes with an SSH key pair generator, which you’ll need if you don’t already have a public/private key pair. Grab the installer here.
  • php_iconPHP for Windows. This is not used for powering your websites, but is used by Composer (next step). I suggest downloading the “VC11 x86 Thread Safe” zip file from here. Extract all files to C:\php. There’s no setup file for this. Rename the file php.ini-development to php.ini and remove the semicolon from the line ;extension=php_openssl.dll. Find a line containing “;extension_dir” and change it to extension_dir = "ext"
  • composer_iconComposer for Windows. Composer is a kind of software component manager for PHP and we use it to install and set up Laravel. Download the Windows installer here and install.

SSH key pair

You’ll need an SSH key pair later in this tutorial. If you don’t already have this, generate as follows:

  1. Start PuTTY Key Generator. (It may be called “PuTTYgen” in your Start Menu.)
  2. I would suggest accepting the defaults of a 2048-bit SSH-2 RSA key pair. Click “Generate” and move your mouse around as directed by the program.
    PuTTY key generation
  3. You can optionally give the key a passphrase. If you leave the passphrase blank, you can ultimately use your key for password-less logins. The drawback is that if your private key ever falls into the wrong hands, an intruder can use the key in the same way. Make your decision, then save the public and private keys. You should always protect your private key. If you left the passphrase blank, treat it like a plain text password. I tend to save my key pairs in a directory .ssh, under my user folder.
  4. Use the “Save private key” button to save your public key (I call it id_rsa).
  5. Don’t use the “Save public key” button – that produces a key that won’t work well in a Linux/Unix environment (which your virtual development box will be). Instead, copy the text from the “Key” box, under where it says “Public key for pasting into OpenSSH authorized_keys file:”. Save this into a new text file. I call my public key file “id_rsa.pub”.

Install the Laravel Installer (sounds clumsy, huh?!)

  1. Load Git Bash.
    Git Bash window
  2. Download the Laravel installer with this command: composer global require "laravel/installer=~1.1". This will take a few minutes, depending on the speed of your connection.
  3. Ideally, you want the Laravel executable in your system path. On Windows 7/8, from Windows/File Explorer, right-click “My Computer”/”This PC”, then click Properties. Click Advanced System Settings. Click the Environment Variables button. Clik Path in the System variables section (lower half of the dialogue) then click Edit. At the very end of the Variable value field, add “;%APPDATA%\Composer\vendor\bin”.
    Set PATH
    Click OK as needed to save changes. Git Bash won’t have access to that new PATH variable until you’ve exited and restarted.

Create Laravel Project

All your Laravel projects will be contained and edited within your Windows file system. I use NetBeans for development and tend to keep my development sites under (e.g.): C:\Users\Geek\Documents\NetBeansProjects\Project World Domination. Create this project as follows:

  1. Fire up Git Bash. This makes sure everything happens in the right place. The remaining commands shown below are from this shell.
  2. Change to the directory above wherever you want the new project to be created.
    cd ~/NetBeansProjects
  3. Install Laravel:
    laravel new "Project World Domination"
    Note: if the directory “Project World Domination” already exists, this command will fail with an obscure error.
  4. That’s it for this stage. Were you expecting something more complicated?

Laravel Homestead

Homestead is a pre-built development environment, consisting of Ubuntu, a web server, PHP, MySQL and a few other bits and bobs. It’s a place to host your Laravel websites while you’re testing them locally. Follow these steps to get it up and running:

  1. From a Git Bash prompt, change to your user folder. Make sure this location has sufficient space for storing virtual machines (800MB+ free).
    cd ~
  2. Make the Homestead Vagrant “box” available to your system.
    vagrant box add laravel/homestead
    This downloads 800MB or so and may take a while.
  3. Clone the Homestead repository into your user folder.
    git clone https://github.com/laravel/homestead.git Homestead
    This should be pretty quick and results in a new Homestead folder containing various scripts and configuration items for the Homestead virtual machine.
  4. Edit the Homestead.yaml file inside the Homestead directory. In the section “authorize”, enter the path to your public SSH key (see above). Similarly, enter the path to your private key in the “keys” section.
  5. Vagrant can easily synchronise files between your PC and the virtual machine. Any changes in one place instantly appear in the other. So you could for example in the “folders” section, map C:\Users\Fred\Code (on your Windows machine) to /home/vagrant/code (on the virtual machine). In my case, I’ve got this:
    folders:
    - map: ~/Documents/NetBeansProjects
    to: /home/vagrant/Projects
  6. We’re going to create a fake domain name for each project. Do something like this in the Homestead.yaml file:
    sites:
    - map: pwd.localdev
    to: /home/vagrant/Projects/Project World Domination/public

    Of course, if you put “http://pwd.localdev” in your browser, it will have no idea where to go. See the next section “Acrylic DNS proxy” for the clever trick that will make this all possible.
  7. To fire up the Homestead virtual environment, issue the command vagrant up from the Homestead directory. This can take a while and may provoke a few security popups.

Here’s the complete Homestead.yaml file:

---
ip: "192.168.10.10"
memory: 2048
cpus: 1

authorize: ~/.ssh/id_rsa.pub

keys:
- ~/.ssh/id_rsa

folders:
- map: ~/Documents/NetBeansProjects
to: /home/vagrant/Projects

sites:
- map: pwd.localdev
to: /home/vagrant/Projects/Project World Domination/public

variables:
- key: APP_ENV
value: local

At this point, you should be able to point your browser to http://127.0.0.1:8000. If you have created a Laravel project as above, and everything has gone well, you’ll see the standard Laravel “you have arrived” message. The Homestead virtual machine runs the Nginx webserver and that webserver will by default give you the first-mentioned web site if you connect by IP address.

Laravel landing page

VirtualBox is configured to forward port 8000 on your computer to port 80 (the normal port for web browsing) on the virtual machine. In most cases, you can connect directly to your virtual machine instead of via port forwarding. You’ll see in the Homestead.yaml file that the virtual machine’s IP address is set to 192.168.10.10. So generally (if there are no firewall rules in the way), you can browse to http://127.0.0.1:8000 or http://192.168.10.10 (the port number 80 is assumed, if omitted). Both should work. Personally I prefer the latter.

Acrylic DNS proxy

Of course we want to be able to host multiple development websites on this virtual machine. To do this, you need to be able to connect to the web server by DNS name (www.geekanddummy.com), not just by IP address. Many tutorials on Homestead suggest editing the native Windows hosts file, but to be honest that can be a bit of a pain. Why? Because you can’t use wildcards. So your hosts file ends up looking something like this:


127.0.0.1 pwd.local
127.0.0.1 some.other.site
127.0.0.1 override.com
127.0.0.1 webapp1.local
127.0.0.1 webapp2.local

(If you’re using 192.168.10.10, just replace 127.0.0.1 in the above example.) So this can go on and on, if you’re developing a load of different sites/apps on the same Vagrant box. Wouldn’t it be nice if you could just put a single line, 127.0.0.1 *.local? This simply doesn’t work in a Windows hosts file.

And this is where the Acrylic DNS proxy server comes in. It has many other great features, but the one I’m particularly interested in is the ability to deal with wildcard entries. All DNS requests go through Acrylic and any it can’t respond to, it sends out to whichever other DNS servers you configure. So it sits transparently between your computer and whatever other DNS servers you normally use.

The Acrylic website has instructions for Windows OSes – you have to configure your network to use Acrylic instead of any other DNS server. Having followed those instructions, we’re now most interested in is the Acrylic hosts file. You should have an entry in your Start menu saying “Edit Acrylic hosts file”. Click that link to open the file.

Into that file, I add a couple of lines (for both scenarios, port forwarding and direct connection, so that both work):

127.0.0.1 *.localdev
192.168.10.10 *.localdev

I prefer using *.localdev, rather than *.local for technical reasons (.local has some peculiarities).

This now means that I can now put in my Homestead.yaml file the following:

sites:
- map: site1.localdev
to: /home/vagrant/Projects/site1/public
- map: site2.localdev
to: /home/vagrant/Projects/site2/public
- map: site3.localdev
to: /home/vagrant/Projects/site3/public
- map: site4.localdev
to: /home/vagrant/Projects/site4/public
- map: site5.localdev
to: /home/vagrant/Projects/site5/public
- map: site6.localdev
to: /home/vagrant/Projects/site6/public
- map: site7.localdev
to: /home/vagrant/Projects/site7/public

and they will all work. No need to add a corresponding hosts file entry for each web site. Just create your Laravel project at each of those directories.

Managing MySQL databases

I would recommend managing your databases by running software on your laptop that communicates with the MySQL server on the virtual machine. Personally I would use MySQL Workbench, but some people find HeidiSQL easier to use. HeidiSQL can manage PostgreSQL and Microsoft SQL databases too. You can connect via a forwarded port. If you wish to connect directly to the virtual machine, you’ll need to reconfigure MySQL in the virtual machine, as follows:

  1. Start the Git Bash prompt
  2. Open a shell on the virtual machine by issuing the command vagrant ssh
  3. Assuming you know how to use vi/vim, type vim /etc/my.cnf. If you’re not familiar with vim, try nano, which displays help (keystrokes) at the bottom of the terminal: nano /etc/my.cnf
  4. Look for the line bind-address = 10.0.2.15 and change it to bind-address = *
  5. Save my.cnf and exit the editor.
  6. Issue the command service mysql restart
  7. You can now connect to MySQL using the VM’s normal MySQL port. Exit the shell with Ctrl-D or exit.

Okay, okay, why go to all this trouble? I just prefer it. So sue me.

Forwarded port Direct to VM
Port: 33060
Host: 127.0.0.1
User name: homestead
Password: secret
Port: 3306
Host: 192.168.10.10
User name: homestead
Password: secret

Managing your environment

Each time you change the Homestead.yaml file, run the command vagrant provision from the Homestead directory, to push the changes through to the virtual machine. And once you’ve finished your development session, run vagrant suspend, to pause the virtual machine. (vagrant up starts it again.) If you want to tear the thing apart and start again, run the command vagrant destroy followed by vagrant up.

How-to: Laravel 4 tutorial; part 4 – database management through migrations

[easyreview title=”Complexity rating” icon=”geek” cat1title=”Level of experience required, to follow this how-to.” cat1detail=”There are some difficult concepts here, but you’ll find this is pretty easy in practice.” cat1rating=”3″ overall=”false”]

Laravel Tutorials

AVZ Database

For almost all my previous web design, I’ve used phpMyAdmin to administer the databases. I speak SQL, so that has never been a big deal. But Laravel comes with some excellent tools for administering your databases more intelligently and (most importantly!) with less effort. Migrations offer version control for your application’s database. For each version change, you create a “migration” which provides details on the changes to make and how to roll back those changes. Once you’ve got the hang of it, I reckon you’ll barely touch phpMyAdmin (or other DB admin tools) again.

Background

If you’ve been following this tutorial series, you may have noticed that I keep referring to a web-scraping application I’m going to develop. Now would be a good time to tell you a bit more about that, so you can understand what I’m aiming to achieve. That said, you can safely skip the next two paragraphs and pick up again at “Configure” if you’re itching to get to the code.

Still with me? Cool. My church uses an off-the-shelf content management system to run its website. It creates an RSS feed for podcasts, but unfortunately that feed doesn’t comply with the exacting requirements of the iTunes podcast catalogue. I thought it would be an interesting exercise to produce a compliant feed, based on data scraped from the web site.

We’re assuming here that I don’t have admin access to the web site and I have no other means of picking up the data. Also, the RSS feed, which contains links to each Sunday’s podcast lacks some other features, like accompanying text or images. So I’m going to parse the pages associated to each podcast one by one, pulling out all the interesting bits. Oh, and to make things really interesting, when you look at the code for the web site’s pages, you’ll see that it’s a whole load of nested tables, which will make the scraping really interesting. 😀

Configure

So I’m creating a web application that will produce a podcast feed. When I created the virtual host for this application (the container for the web site), Virtualmin also created my “ngp” (for NorthGate Podcasts) database. I’m going to create a MySQL user with the same name, with full permission to access the new database. Here’s how I do that from a root SSH login:

echo "GRANT ALL ON ngp.* TO 'npg'@localhost IDENTIFIED BY 'newpassword';" | mysql -p

This prompts me for the MySQL root password, then creates a new MySQL user, “ngp” and gives it all privileges associated to the database in question. Next we need to tell Laravel about these credentials. The important lines in the file app/config/database.php are:

 'mysql',

	'connections' => array(

//...

		'mysql' => array(
			'driver'   => 'mysql',
			'host'     => '127.0.0.1',
			'database' => 'ngp',
			'username' => 'ngp',
			'password' => 'newpassword',
			'charset'  => 'utf8',
			'prefix'   => '',
		),

//...

	),

//...

);

Our application will now be able to access the tables and data we create.

Initialise Migrations

The migration environment (essentially the table that contains information about all the changes to your application’s other tables) must be initialised for this application. We do this using Laravel’s command line interface, Artisan. From an SSH login, in the root directory of your Laravel application (the directory that contains the “artisan” script):

php artisan migrate:install

If all is well, you’ll see the response:

Migration table created successfully.

This creates a new table, migrations, which will be used to track changes to your application’s database schema (i.e. structure), going forwards.

First migration

Sometimes the Laravel terminology trips me up a bit. Even though it may seem there’s nothing really to migrate from yet, it’s technically a migration – a migration from ground zero. Migration in this sense means the steps required to get from the “base state” to the “target state”. So our first migration will take us from the base state of a completely empty database (well empty except for the migrations table) to the target state of containing a new table, nodes.

My web-scraping application will have a single table to start with, called “nodes” [Note: it is significant that we’re using a plural word here; I recommend you follow suit.] This table does not yet exist; we will create it using a migration. To kick this off, use the following Artisan command:

php artisan migrate:make create_nodes_table

Artisan should respond along the following lines:

Created Migration: 2013_07_14_154116_create_nodes_table
Generating optimized class loader
Compiling common classes

This script has created a new file 2013_07_14_154116_create_nodes_table.php. under ./app/database/migrations. If, like me, you’re developing remotely, you’ll need to pull this new file into your development environment. In NetBeans, for example, right-click the migrations folder, click “download” and follow the wizard.

You can deduce from the naming of the file that migrations are effectively time-stamped. This is where the life of your application’s database begins. The new migrations file looks like this:


As you can probably guess, in the "up" function, you enter the code necessary to create the new table (to move "up" a migration) and in the "down" function, you do the reverse (to move "down" or to roll back a migration).

Create first table

Your first migration will probably be to create a table (unless you have already created or imported tables via some other method). Naturally, Laravel has a class for this purpose, the Schema class. Here's how you can use it, in your newly-created migrations php file:

	public function up()
	{
		Schema::create('nodes', function($table) {
				$table->increments('id'); // auto-incrementing primary key
				$table->string('public_url', 255)->nullable(); // VARCHAR(255), can be NULL
				$table->text('blurb')->nullable();             // TEXT
				$table->string('image', 255)->nullable();
				$table->string('speaker', 255)->nullable();
				$table->string('title', 255)->nullable();
				$table->string('mp3', 255)->nullable();
				$table->integer('downloads')->nullable();     // INT
				$table->date('date')->nullable();             //DATE
				$table->integer('length')->nullable();
				$table->timestamps(); // special created_at and updated_at timestamp fields
		});
	}

	/**
	 * Revert the changes to the database.
	 *
	 * @return void
	 */
	public function down()
	{
		Schema::drop('nodes');
	}

To run the migration (i.e. to create the table), do the following at your SSH login:

php artisan migrate

This should elicit a response:

Migrated: 2013_07_14_154116_create_nodes_table

If you're feeling nervous, you may wish to use your DB admin program to check the migration has performed as expected:

ngp nodes db

If you want to roll back the migration, performing the actions in the down() function:

php artisan migrate:rollback

Result:

Rolled back: 2013_07_14_154116_create_nodes_table

Take a look at the Schema class documentation, to see how to use future migrations to add or remove fields, create indexes, etc. Next up: how to use databases in your applications.

AVZ Database image copyright © adesigna, licensed under Creative Commons. Used with permission.

How-to: Laravel 4 tutorial; part 3 – using external libraries

[easyreview title=”Complexity rating” icon=”geek” cat1title=”Level of experience required, to follow this how-to.” cat1detail=”With Composer, installing libraries in Laravel 4 is easy peasy.” cat1rating=”1″ overall=”false”]

Laravel Tutorials

Library

I’m in the process of moving from CodeIgniter to Laravel. I still use CodeIgniter if I need to do something in a hurry. I was very pleased when the Sparks project came on the CodeIgniter scene, offering a relatively easy way to integrate third-party libraries/classes into your project. When I first looked at Laravel, I saw that it offered something similar, in “Bundles”.

Laravel 4 has matured. It is now using Composer for package management. Composer is itself an external library of sorts. It is not framework dependent. You can use Composer virtually anywhere you can use PHP. Which is great, because that means not only can you use Composer to install Laravel, you can use it to pull in other libraries too and track dependencies. With a bit of luck, the third-party library you require has already been made available at Packagist making installation of that library a doddle.

As I mentioned earlier, I’m going to be creating a web-scraping application during this tutorial. We’ve already seen how we can use Composer to make jQuery and Twitter’s Bootstrap available. Let’s now use it to add Goutte, a straightforward web scraping library for PHP. Goutte itself depends on several other libraries. The beauty of Composer is that it will make all those additional libraries available automatically.

Open up an SSH shell connection to your web server and navigate to the laravel directory. Utter the following incantation:

composer require "fabpot/goutte":"*"

Installation will take a while as it hauls in all the various related libraries. But who cares – this is a cinch! Make yourself a coffee or something. I saw the following output:

composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
- Installing guzzle/common (v3.6.0)
Downloading: 100%

- Installing guzzle/stream (v3.6.0)
Downloading: 100%

- Installing guzzle/parser (v3.6.0)
Downloading: 100%

- Installing guzzle/http (v3.6.0)
Downloading: 100%

- Installing fabpot/goutte (dev-master 2f51047)
Cloning 2f5104765152d51b501de452a83153ac0b1492df

Writing lock file
Generating autoload files
Compiling component files
Generating optimized class loader
Compiling common classes

All very impressive and difficult-sounding.

Okay, so that’s great – I’ve got the library here somewhere; how do I load and use it? Loading the class is ridiculously easy. Composer and Laravel make use of PHP’s autoload function. You don’t even have to think about where the files ended up. Just do:

$client = new Goutte\Client();

To put that in context, here’s a new function for our ScrapeController class:

	public function getPages() {
		$client = new Goutte\Client();
		$crawler = $client->request('GET', 'https://pomeroy.me/');
		var_dump($crawler);
	}

If I visit the /scrape/pages URL, I see this:


object(Symfony\Component\DomCrawler\Crawler)#171 (2) { ["uri":protected]=> string(24) "https://pomeroy.me/" ["storage":"SplObjectStorage":private]=> array(1) { ["00000000061dd4ed000000000c2f13de"]=> array(2) { ["obj"]=> object(DOMElement)#173 (0) { } ["inf"]=> NULL } } }

I reckon even Dummy could do this! There are lots more sophisticated things you can do. I keep reading about the “IoC Container” but to be honest I’m finding the official documentation somewhat impenetrable. Once I’ve worked it out, I may post an update. Before that, I’m going to work on the next post in this series – managing databases.

Library image copyright © Janne Moren, licensed under Creative Commons. Used with permission.

How-to: Laravel 4 tutorial; part 2 – orientation

[easyreview title=”Complexity rating” icon=”geek” cat1title=”Level of experience required, to follow this how-to.” cat1detail=”This series really is for web programmers only, though not a great deal of prior experience is required.” cat1rating=”3.5″ overall=”false”]

Laravel Tutorials

Signpost at North Point, Barbados, Feb.1998

I’ve used CodeIgniter for many years, but I have always, I confess, proceeded knowing just enough to get by. So forgive me if my approach seems a little clunky. I have never, for example, used CodeIgniter’s routes. I like my web application files nicely categorised into Model, View, Controller, Library and, if absolutely necessary, Helper. (Google an MVC primer if you’re not familar with these terms. These are concepts that will really aid your web development.)

Controllers

So for now, I want to carry on using Controllers, if that’s okay with you. Controllers are stored under app/controllers. To anyone coming from CodeIgniter, that’s probably going to sound familiar!

As I go through the editions of this tutorial, I will be creating a small application that scrapes data from another website and represents it. More on that anon. Bearing that in mind, here’s a sample controller:

In CodeIgniter, that’s all you would have needed to do, due to automatic routing. In Laravel, you need also to add the following to app/routes.php:

Route::controller('scrape', 'ScrapeController');

To view these pages, you just visit yourdomain/scrape (/index is implied) and yourdomain/scrape/node/x (where x will probably refer to a specific node, possibly by database id).

This all bears explanation; the controllers page in the Laravel documentation does not currently expand on this. The names of the functions in the controller are significant. The first part of the camelCase style name is the HTTP verb that will be used to access the page. This may be an unfamiliar concept, but it’s great once you get used to it.

Most web pages will be accessed by the browser using the HTTP method “GET”. This is just the default. If you’re sending form data (you’ve clicked on a submit button), the chances are we’re dealing with the HTTP method “POST”. This makes it very easy to respond appropriately based on how the URL was reached.

Note: this is scratching the surface of RESTful web development. You may have heard the term bandied about. Wikipedia‘s not a bad place to start if you want to learn more about this.

We’ll reach the getIndex() function if we simply browse to /scrape. Following the age-old convention, “Index” is the default. If we browse to /scrape/node, the getNode() function comes into play. That function is expecting a single parameter, which would be passed along with the URL: /scrape/node/1.

You only reach the pages though through the magic of routing. In the Route::controller('scrape', 'ScrapeController');, we’re telling Laravel that calls to the URL /scrape need to be handed to the ScrapeController class.

Views

Views are pretty straightforward and similar to CodeIgniter. Place them in app/views. Extending the example above, our controller could now look like this:

 $node);
		return View::make('node', $data);
	}

}
?>

The second paramater in View::make is the data (typically a multi-dimensional array) sent to that view. Note that data can also be passed through to a view like this:

	public function getNode($node) {
		return View::make('node', $data)
		    ->with('node' => $node);
	}

And then your view (app/views/node.php) could be like this:

Node

This is node .

Obviously your real views will be more syntactically complete. You can see that the array is flattened one level so that $data('node'); in the controller is accessed a $node in the view.

Models

Models are created under app/models. Unlike CodeIgniter, Laravel comes with its own object relational mapper. In case you’ve not encountered the concept before, an ORM gives you a convenient way of dealing with database tables as objects, rather than merely thinking in terms of SQL queries. CodeIgniter has plenty of ORMs, by the way, it just doesn’t ship with one as standard.

Laravel’s built-in ORM is called “Eloquent”. If you choose to use it (there are others available), when creating a model, you extend the Eloquent class. Eloquent makes some assumptions:

  • Each table contains a primary key called id.
  • Each Eloquent model is named in the singular, while the corresponding table is named in the plural. E.g. table name “nodes”; Eloquent model name “node”.

You can override this behaviour if you like, it just makes things a bit more convenient in many cases.

Example model app/models/node.php:


(You can omit the closing ?> tag.)

Because the Eloquent class already contains a lot of methods, you do not necessarily need to do more than this. In your controllers, you could for example now do this:

$nodes = Node::all();

foreach ($nodes as $node) {
  // Do stuff here
}

This is a whistle-stop tour preparatory to building a real application. Head on over to the official Laravel documentation for much more on all this.

Signposts image copyright © Andrea_44, licensed under Creative Commons. Used with permission.

How-to: Laravel 4 tutorial; part 1 – installation

[easyreview title=”Complexity rating” icon=”geek” cat1title=”Level of experience required, to follow this how-to.” cat1detail=”A good level of familiarity with web hosting will come in handy here, especially if your hosting environment is different from mine. It will also help if you’re comfortable at the command line.” cat1rating=”4″ overall=”false”]

Laravel Tutorials

Introduction

If, like me, you spend much time coding for the web – for pleasure or profit – sooner or later you’re going to find that you benefit from using a development framework. A framework is a collection of scripts that help you create an application much more quickly. Frameworks typically include a lot of the “nuts and bolts” components – scripts that assist with database connections for example, plus components that impose some structure on your programming.

For a long time, my framework of choice was CodeIgniter. CodeIgniter has stagnated of late and concerns have arisen over licensing. Partly as a consequence, many PHP developers like me have searched for an alternative. In the search, I came across a framework that many programmers are turning to: Laravel. My early experiences with Laravel have been extremely positive and I have found many things I prefer about it. In this series of tutorials, I’ll show you how to get up and running with Laravel and begin creating an application. The application will involve some web-scraping, so you may wish to stay tuned for that reason alone.

Before we dive in though, one word of caution: Laravel is a young open source project. Like many such projects, its documentation is less complete than you might wish, particularly when compared to CodeIgniter. In fact CodeIgniter’s great documentation was one of the reasons why I initially chose it as a development framework. Documentation is a core commitment of the Laravel team, but at the time of writing, with the recent release of Laravel 4, I’m finding the documentation is not quite up to scratch. Possibly you’ve found that too, which is why you’ve made it here to this tutorial. In fact one of the worst parts of the documentation at the time of writing is the installation procedure! With that caveat in place, let’s move on – it’s still well worthwhile.

Prerequisites

All my web coding is done within a Linux environment, usually CentOS or Ubuntu Server. For the easiest experience following these tutorials, you may wish to create a similar environment. (I’ve written about that elsewhere.) Alternatively, you should be able to follow the tutorials with some tweaking – but you’re on your own there. At the very least, I recommend you have in place:

  • Apache web server
  • Shell access to the server (preferably SSH)
  • Root access to install Composer globally (not essential)
  • Git must be installed in your environment.

Installing Composer

With the latest release (4) Laravel has taken a leap forward in several areas. One such area is the management of third party libraries and packages. Laravel previously made use of an external project called “Composer“, to install dependent packages. With Laravel 4, you now use Composer to install Laravel itself. To install Composer, from a root login shell, do the following:

cd /usr/local/bin
curl -sS https://getcomposer.org/installer | php
mv composer.phar composer

Provided /usr/local/bin is in your $PATH environment variable, you will now be able to call Composer with “composer [options] command [arguments]“.

Installing Laravel



The beauty of Composer is the simplicity it brings to library/application installation. There is an overwhelming range of tutorials on how to install Laravel with Composer. Please bear in mind that many of these were written while Laravel 4 was in beta or even alpha. Now it has been released, the installation is quite straightforward. Having prepared a new environment for a web site (a virtual host or whatever), navigate to the directory above the default web root directory. Then install using Composer. Eg:

cd /home/geek/domains/test.geekanddummy.com/
composer create-project laravel/laravel

You should see a fair bit of output indicating that Composer is creating a directory “laravel” and pulling in all the dependencies for a basic installation. The laravel directory contains a folder entitled “public“, intended to be your web root. Your easiest way to complete the configuration is to point your web site at that directory. For example, using Virtualmin, you would go to Server Configuration –> Website Options and change “Website documents sub-directory” from “public_html” to “laravel/public”.

Having done that, when I browse to my test web site, I see:

Laravel landing page

Installing other frameworks

Now would be a good time put to put Twitter’s Bootstrap and jQuery in place, if you’re planning to use them. Naturally, we’ll use Composer for this. You might use other frameworks in your web applications – check out Packagist to see if anyone has made a Composer package available.

Composer demands a tutorial all of its own, but I’ll keep it simple here. I’m going to make my new Laravel application depend on the latest compatible branches of Bootstrap and jQuery. This will potentially allow us to upgrade these two frameworks with a simple Composer command at a later date.

In the root of your Laravel application you’ll find the main Composer configuration file, composer.json. You don’t need to get your hands dirty editing the file, just from a shell in that root directory, issue the following commands:

composer require "components/jquery":"*"
composer require "twitter/bootstrap":"*"

This updates the composer.json file to include these dependencies and goes ahead and downloads them. It can take a while – be patient.

You’ll end up with jQuery files under ./components/jquery and Bootstrap files under ./vendor/twitter/bootstrap. These are locations not visible to your web server (the root is at ./public, you’ll recall). This is a particular problem in the case of Bootstrap. For now, here’s a quick-and-dirty way of accessing these files. I’m on the lookout for a more elegant solution, but this will get you up and running rapidly. Navigate to the “public” folder in a login shell and issue the following commands:

mkdir -p assets/css
mkdir assets/img
mkdir assets/js
ln -s ../../../vendor/twitter/bootstrap/img/glyphicons-halflings.png ./assets/img
ln -s ../../../vendor/twitter/bootstrap/docs/assets/css/bootstrap.css ./assets/css
ln -s ../../../vendor/twitter/bootstrap/docs/assets/css/bootstrap-responsive.css ./assets/css
ln -s ../../../components/jquery/jquery.min.js ./assets/js

And so on, for whichever bits you’ll use. This will only work if your web server allows following symbolic links. The .htaccess directive “Options +SymLinksIfOwnerMatch” may help here, but that’s outside the scope of this tutorial.

Configure your development environment

I use NetBeans for development. If you don’t already have a preferred IDE (integrated development environment), I recommend you check it out. Another favourite is Eclipse. You could use an ordinary text editor, but then you’d be missing out on a lot of things that can make your coding more comfortable and efficient.

Having installed Laravel and the other frameworks on my web server, next I use NetBeans to pull the code across to my development environment. In the NetBeans “New Project” wizard, select the option “PHP Application from Remote Server”. In the remote configuration, ensure that you choose as your “upload directory”, the laravel. From there, you’ll want to download the app and public directories.

Conclusion

That’s it for today’s tutorial. Next time, we’ll look at orientating ourself within the framework (“what goes where?”).

From CodeIgniter to Laravel | part 4: managing databases

UPDATE: I have re-written this article for the new Laravel 4. You’ll find the updated article over at Geek & Dummy.

Contents


AVZ DatabaseFor almost all my previous web design, I’ve used phpMyAdmin to administer the databases. I speak SQL, so that has never been a big deal. But Laravel comes with some excellent tools for administering your databases more intelligently and (most importantly!) with less effort. Migrations offer version control for your application’s database. For each version change, you create a “migration” which provides details on the changes to make and how to roll back those changes. Once you’ve got the hang of it, I reckon you’ll barely touch phpMyAdmin again.

Configuration

So let’s assume that I’m creating a new website about ducks. When I created the virtual host, Virtualmin also created my “ducks” database. I’m going to create a MySQL user with the same name, with full permission to access the new database. Here’s how I do that from a root SSH login:

echo "GRANT ALL ON ducks.* TO 'ducks'@localhost IDENTIFIED BY 'newpassword';" | mysql -p
Enter password:[root MySQL password]

This creates a new MySQL user, “ducks” and gives it all privileges associated to the database in question. Next we need to tell Laravel about these credentials. The important lines in the file application/config/database.php are:

<?php
return array(

//...

	'default' => 'mysql',

	'connections' => array(

//...

		'mysql' => array(
			'driver'   => 'mysql',
			'host'     => '127.0.0.1',
			'database' => 'ducks',
			'username' => 'ducks',
			'password' => 'newpassword',
			'charset'  => 'utf8',
			'prefix'   => '',
		),

//...

	),

//...

);

Initialise Migrations

The migration environment must be initialised for this application. We do this using Laravel’s command line interface, Artisan. From an SSH login:

php artisan migrate:install
Migration table created successfully.

This creates a new table, laravel_migrations, which will be used to track changes to your database schema (i.e. structure), going forwards.

My ducks application will have a single table to start with, called “ducks” [Note: it is significant that we’re using a plural word here; I recommend you follow suit]. This table does not yet exist; we will create it using a migration. To kick this off, use the following Artisan command:

php artisan migrate:make create_ducks_table
Great! New migration created!

This will create a new file named something like “2013_04_15_085356_create_ducks_table.php”. If, like me, you’re developing remotely, you’ll need to pull this new file into your development environment. In NetBeans, for example, right-click the migrations folder, click “download” and follow the wizard.

You can deduce from the naming of the file that migrations are effectively time-stamped. This is where the life of your applications database begins. The migrations file will look a bit like this:

<?php

class Create_Ducks_Table {

	/**
	 * Make changes to the database.
	 *
	 * @return void
	 */
	public function up()
	{
		//
	}

	/**
	 * Revert the changes to the database.
	 *
	 * @return void
	 */
	public function down()
	{
		//
	}

}&#91;/php&#93;

As you can probably guess, in the "up" function, you enter the code necessary to create the new table (to move "up" a migration) and in the "down" function, you do the reverse (to move "down" or to roll back a migration).

<h1>Create first table</h1>

Your first migration will probably be to create a table (unless you have already created or imported tables via some other method).  Naturally, Laravel has a class for this purpose, the <a href="http://laravel.com/docs/database/schema" target="_blank">Schema class</a>.  Here's how you can use it, in your newly-created migrations php file:

[php]<?php

class Create_Ducks_Table {

	/**
	 * Make changes to the database.
	 *
	 * @return void
	 */
	public function up()
	{
		Schema::create('ducks', function($table) {
				$table->increments('id');              // auto-incrementing primary key
				$table->string('name', 255);           // varchar field; length 255 characters
				$table->date('birthdate')->nullable(); // can be empty
				$table->boolean('can_fly')->default(TRUE);
				$table->integer('children')->unsigned();
				$table->text('biography');
				$table->timestamps(); // special created_at and updated_at timestamp fields
		});	
	}

	/**
	 * Revert the changes to the database.
	 *
	 * @return void
	 */
	public function down()
	{
		Schema::drop('ducks');
	}

}

To run the migration (i.e. to create the table), do the following at your SSH login:

php artisan migrate
Migrated: application/2013_04_15_085356_create_ducks_table

That creates the table, as described. And if you need to roll back:

php artisan migrate:rollback
Rolled back: application/2013_04_15_085356_create_ducks_table

This removes the table.

By examining the Schema class documentation, you’ll see how you can use future migrations to add or remove fields, create indexes, etc. In my next tutorial, I’ll have a look at using databases in your application.

AVZ Database image copyright © adesigna, licensed under Creative Commons. Used with permission.

From CodeIgniter to Laravel | part 3: installing external libraries

UPDATE: I have re-written this article for the new Laravel 4. You’ll find the updated article over at Geek & Dummy.

Contents


LibraryAs a fan of CodeIgniter, I was very pleased when the Sparks project came on the scene, offering a relatively easy way to integrate third-party libraries/classes into your project. Laravel has a similar and arguably more feature-rich analog in Bundles. With a bit of luck, the third-party library you require has already been converted to a Laravel bundle, making installation a snip.

Let’s say, for example, we’re going to build a web-scraping application. The first two libraries I’d consider adding to the project would be the Requests HTTP library and the PHP Simple HTML DOM Parser.

From an SSH login, at the root of your project, issue the following command:

php artisan bundle:install requests phpsimplehtmldom

You should be greeted with the following results:

Fetching [requests]...done! Bundle installed.
Fetching [phpsimplehtmldom]...done! Bundle installed.

The file application/bundles.php will probably contain code along the following lines:

<?php

/*
 &#91;...various comments...&#93;
*/

return array(

	'docs' => array('handles' => 'docs'),

);

Register the new libraries like this:

return array(

	'docs' => array('handles' => 'docs'),
	'requests' => array('auto' => TRUE),
	'phpsimplehtmldom' => array('auto' => TRUE),

);

And use like this:

		$HDM = IoC::resolve('HtmlDomParser'); // Give us a hook into the library; Requests doesn't need this

		// Request the HTML page
		//$headers = array('Accept' => 'application/html');
		$headers = array();
		//$options = array('auth' => array('user', 'pass'));
		$options = array();
		$request = Requests::get('http://some.domain/some/page', $headers, $options);
		if($request->status_code != 200) {
			// Handle error retrieving page
		}

		$dom = $HDM::str_get_html($request->body);

		// Options
		$options = $dom->find('#somediv option');
		foreach($options as $option) {
			echo $option->value.' | '.$option->innertext."<br />";
		}

There’s a lot more to this IoC thing than meets the eye. To be frank, it’s above my head. I’m also not convinced I fully understand registering bundles. But, like CodeIgniter, learning is a process of immersion in the framework. I’m pretty sure than in a couple of years I’ll laugh at the code above. So all I ask is please be gentle in the comments. 😉

Library image copyright © Janne Moren, licensed under Creative Commons. Used with permission.