Configure PHP and Laravel Framework

PHP, Laravel and Composer

In this guide we configure PHP and Laravel Framework to build web applications and REST APIs. As a result, you can prepare the environment to start the development process in a Laravel Project.

After this process, you will get installed the following components:

  • PHP (PHP 7 or newer)
  • MySQL/MariaDB server engine and client
  • PEAR (PHP repository of common reusable components)
  • Composer (PHP package and dependency manager)
  • XDebug (PHP debugger used by unit tests tools like PHPUnit)
  • Laravel command line tools (laravel and php artisan)

Install PHP, Database and required components

PHP and the Laravel Framework need some basic components prior to run a Laravel application. The following steps will help you complete all the Laravel software and component requirements.

Install or update php

If you don’t have a PHP 7.1 or newer installation, see the article Installation of PHP in Windows, MacOS and Linux  to review the installation steps of PHP for your specific OS.

Initialize a php.ini 

The file php.ini is the PHP configuration file. The best way to retrieve the current php.ini location is executing the command php -i

php -i | grep php.ini

This command will return some configuration information:

Configuration File (php.ini) Path => /usr/local/etc/php/7.1
Loaded Configuration File => /usr/local/etc/php/7.1/php.ini

If you installed PHP in MacOS as recommended, using HomeBrew, your php.ini file will be located in /usr/local/etc/php/7.1/php.ini(depending on the PHP version installed, 7.1 in the example).

Otherwise, in MacOs, or when you install PHP for the first time, there is no default php.ini file installed. If php.ini is not present, you need to create one, copying from the php.ini.default file (generally, php.ini file is located in /etc/php.ini):

sudo cp /etc/php.ini.default /etc/php.ini

Install a Database engine (MySQL/MariaDB)

Typically, you can configure a database engine to work with a backend application. Typical options could be MySQL, or MariaDB (a MySQL compatible and open-source database). Also, you can choose SQLite or PostgreSQL , both supported by Laravel .

Installing MySQL

  • MacOS: Using  Homebrew,
    • brew install mysql
  • Debian/Ubuntusudo apt-get install mysql-server
  • Windows: Use the MySQL installer package

Installing MariaDB

  • MacOS: Using  Homebrew,
    • brew install mariadb
    • brew services start mariadb
  • Debian/Ubuntusudo apt-get install mariadb-server
  • Windows: Use the MariaDB installation guide.

The initial installation of MySQL/MariaDB server includes the mysql client. You can access your database console using the user root and a blank password:

mysql -u root

Install PEAR

PEAR is a PHP toolset with a variety of repositories that extends the functionalities of PHP with additional packages. The common installation steps are the following:

Download

curl -O http://pear.php.net/go-pear.phar
sudo php -d detect_unicode=0 go-pear.phar
rm go-pear.phar

  • Use option [1] to change path to [/usr/local/pear]
  • Use option [4] to change path to [/usr/local/bin]
  • Press Enter to start installation
  • Use the default php.ini location when prompted (leave empty and press Enter)

Check your PEAR installation using:

pear version

Install composer

Composer is a package manager used in PHP to manage dependencies and autoload components. Laravel uses Composer to install the project dependencies, including Laravel components.

MacOS

curl -o /tmp/composer https://getcomposer.org/installer
php /tmp/composer
mv ~/composer.phar /usr/local/bin/composer

Linux (Debian/Ubuntu)

sudo apt-get install composer

Windows

Use the Composer installation guide.

Install PHP dependencies

Laravel requires some php extensions to work properly. The base PHP installation comes with the majority of the dependencies needed. However, some distributions need additional php packages to install.

Linux (Debian)

sudo apt-get install php-zip
sudo apt-get install php-mbstring

Install Xdebug for PHP

Xdebug is a powerful debugging framework for PHP. Laravel PHPUnit test use XDebug to get additional information about the classes, variables and the routing of the PHP application steps. The most common installation process is using PECL (a tool installed by PEAR). Before thet, you need to install PHP development tools to compile the package.

MacOS

brew install autoconf
sudo pecl install xdebug

After that, you will receive a final message like this:

Build process completed successfully
Installing '/usr/lib/php/extensions/no-debug-non-zts-20160303/xdebug.so'

Then, you need to update the /etc/php.ini file to use the Xdebug extension, including the location of the xdebug.so file created in a new line like:

zend_extension="/usr/lib/php/extensions/no-debug-non-zts-20160303/xdebug.so"

Finally, you can check if your php installation has XDebug properly installed:

php -i | grep xdebug

If the output of this command is not showing any content, theck the final step about php.ini. Check if the php.ini you edited is the right one using the command:

php -i | grep "Loaded Configuration File"

This will output the current php.ini file used.

Install Laravel

Now you can install Laravel using composer, installing as a global package (not only for the current project). It allows to save space in your project, since there is a common location for the framework files, avoiding duplicated files in each Laravel project.

composer global require "laravel/installer"
PATH=$PATH:$HOME/.composer/vendor/bin

Make sure you have this code in your ~/.bash_profile startup script

# Get the aliases and functions
if [ -f ~/.bashrc ]; then
. ~/.bashrc
fi

And to add the PATH variable to the ~/.bashrc file

PATH=$PATH:$HOME/.composer/vendor/bin
export PATH

Create a new Laravel project

The Laravel command is to perform Laravel actions in a project. The first command is “new” (laravel new) . This command will create a whole Laravel project structure in a new folder using thelaravel-app-name, subfolders and files needed to start a new project.  After creation, you can switch inside the project to perform additional actions.

laravel new laravel-app-name
cd laravel-app-name

First-time Configuration

The first time you create a new Laravel app, you need to make some initial configurations.

  • If there is no .env file, create one using the template file .env.example
    cp .env.example .env
  • If you just created the .env file, you need to create a security key for the application
    php artisan key:generate
  • Test your initial Laravel application using the artisan serve command
    php artisan serve

Connecting a Database

In the .env file you can setup a database to work with your project. You need to set the database connection parameters. In a new Mysql/MariaDb installation, you can use this parameters:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=myapp
DB_USERNAME=root
DB_PASSWORD=

DB_DATABASE will be the name of you database associated with the application. If you have not created a database with this name, you can create it using the mysql console:

mysql -u root -p -e "CREATE DATABASE myapp"

When you run this command, it will ask you for a password. After that, you database will be created. If you have an initial installation of MySQL/MariaDB, the password is empty.

Setup a database password

If you want to secure your database, you may set a password for the root account. It will ask you for the current password (the first time it’s empty):

mysqladmin -u root -p password "myrootpassword"

If you changed the root password, remember to update the .env file with the new password in the DB_PASSWORD field.

Update dependencies

When you create a new Laravel app with laravel new, or when you get the source of a Laravel application for the first time, you will note that the dependencies are not packed in the source. The folder ./vendor contains all the composer components and dependencies of the project, but normally, this folder is empty or non existent in the first time. When you run the command:

composer install

With this command, composer will retrieve all the component dependencies of the project and they will be stored in a folder named vendor.

At this point you are ready to use your application for development.

Using PHP artisan commands

In Laravel, Artisan is the main tool to manage your project for different tasks. This is a PHP command line application that runs inside your project folder.

php artisan action [parameters]

When you run the command php artisan, you will get a list of all the available artisan actions available. For example:

  • migrate Run the database migrations (creation of tables, and initial data)
  • serve Serve the application on the local PHP development HTTP server
  • tinker Interact with your application using a command line
  • cache:clear Flush the application cache
  • key:generate Set the application key
  • make:command Create a new Artisan custom command
  • make:controller Create a new controller class
  • make:migration Create a new migration file
  • make:model Create a new Eloquent model class
  • make:test Create a new test class

You can get help about the parameters and use of each action running the command php artisan help action. For example:

php artisan help make:migration

Common development tasks with php artisan

These are the  most commands you run every time you work with a Laravel project during development:

php artisan make:migration migration_name

  • To create a new migration file (Creation of database tables, fields, indexes)
  • File created in./database/migrations/yyyy-mm-dd_hhmmss_migration_name.php
  • yyyy-mm-ddis the current date (Ex: 2018-10-23)
  • hhmmss is the current time (Example: 093500)

php artisan migrate

  • Execute migrations not executed yet.
  • The migrations are executed using alphabetical order (ordered by date/time) of the migration files.
  • Using the parameter –step, you can control to apply migrations one by one.

php artisan make:model Models\ModelName

  • To create a new Model class
  • The double backslashes (\) will be converted to a single one.
  • File created in  ./app/Models/ModelName.php
  • Models (App/Models) is the default namespace for models. You can use a different namespace if you want.

php artisan make:controller TestController -m Models\ModelName

  • To create a controller named TestController (by convention, every controller has the suffix Controller)
  • File created in ./app/Http/Controllers/TestController.php
  • The parameter -m helps to configure the controller as a resource controller for AppModelsModelName 

php artisan make:test ReservationTest --unit

  • To create a test case file for a Controller or any functionality
  • File created in ./tests/Unit/ReservationTest.php
  • Without the --unit parameter, it will be created in ./tests/Feature/ReservationTest.php

 

Example Project

You can find an example Laravel project based on this guide in https://github.com/fraigo/laravel-app

Also, there is a Laravel Install script to automate the steps of this guide in https://github.com/fraigo/laravel-install-script (for Debian/Ubuntu based systems)

 

 

 

 

Leave a Reply