Browse Tag

featured

Setting up Laravel 5 on shared hosting server

UPDATE (7 Jan 2016): Added a final step for pointing domain to subfolder.

UPDATE (4 Apr 2016): I’ve received a number of enquiries with this setup. Please test it on your local environment first. Use homestead to create a domain with the same folder structure. If it’s working on homestead, it’ll most likely work on your shared server.

UPDATE (15 Jun 2016): Added some common problems found from the lovely comments. Scroll to the bottom to see

In this tutorial, I’ll show you some guide to deploy your Laravel 5 application onto a shared hosting server.

By default, the Laravel folder structure assumed that the public folder is within the application itself. This is the high level folder structure:

your_app_name
|--app
|--bootstrap
|--config
|--database
|--public
  |--assets
  |--index.php  <--we need to point here
|--resources
|--storage
|--tests
|--vendor

In an ideal scenario, you can simply point the web domain to the public folder so that the URL loads public\index.php.

However, in a shared hosting server, you are limited to putting your web serving files in a folder probably named public_html or www which is publicly accessible via web domain. You may be tempted to do this (NOT recommended):

shared_hosting_root_NOT_recommended
|--other_folders (not accessible via web domain)
|--public_html
  |--your_app_name
    |--app
    |--bootstrap
    |--config
    |--database
    |--public
      |--assets
      |--index.php  <--we need to point here
    |--resources
    |--storage
    |--tests
    |--vendor

You can then point your web domain to the public folder.

The problem with this is that your application is now publicly accessible and that may expose vulnerability. You cannot be sure if someone somewhere is able to access your config folder and look at all your sensitive information such as database credentials.

Instead, put your application root into a folder outside of public_html, and place only the public folder within public_html.

This is the recommended folder structure:

shared_hosting_root_recommended
|--other_folders (not accessible via web domain)
|--applications  (not accessible via web domain)
  |--your_app_name
    |--app
      |--GoPublic.php <--we'll create this
    |--bootstrap
    |--config
    |--database
    |--public <--copy content to public_html
      |--assets
      |--index.php
    |--resources
    |--storage
    |--tests
    |--vendor
    |--deploy.sh <--we'll create this
|--public_html
  |--your_app_name
    |--assets
    |--index.php <-- we need to point here

In Laravel 4, you can easily tell your application that the public folder is now in another location by simply changing the file bootstrap/path.php. See point 9 of my Laravel 4 tutorial.

However, in Laravel 5, this file no longer exists. I’ll show you how.

1. Create a class to point to new location

Create a new file shared_hosting_root\applications\your_app_root\app\GoPublic.php

<?php namespace App;

class GoPublic extends \Illuminate\Foundation\Application
{
 /**
 * Get the path to the public / web directory.
 *
 * @return string
 */
 public function publicPath()
 {
 return $this->basePath.DIRECTORY_SEPARATOR.'../../public_html/your_app_name';
 }
}

We’re using relative path here so you don’t have to know the absolute path. But it is extremely crucial to follow the same recommended folder structure I’ve mentioned earlier.

Updated:

You may need to run the following command in your root folder to autoload the new class. Otherwise you will get an error saying the class cannot be found.

composer dump-autoload

2. Edit bootstrap\app.php

Now we need to tell our application the location of the new public folder. Open and edit your_app_name\bootstrap\app.php:

<?php

/* -- remove/comment this original code
$app = new Illuminate\Foundation\Application(
 realpath(__DIR__.'/../')
);
-- until here */

/* -- add this new code -- */
$app = new App\GoPublic(
 realpath(__DIR__.'/../')
);

As you can see above, we’re using the new class that we’ve created in step 1.

3. Edit public\index.php

You need to edit these 2 lines.

From line 21:

require __DIR__.'/../bootstrap/autoload.php';

to

require __DIR__.'/../../applications/your_app_name/bootstrap/autoload.php';

And from line 35:

$app = require_once __DIR__.'/../bootstrap/app.php';

to

$app = require_once __DIR__.'/../../applications/your_app_name/bootstrap/app.php';

4. Copy public to public_html

Now, copy the content inside applications\your_app_name\public into public_html\your_app_name.

To simplify the process, I would create a bash file to automatically copy the files to the new location.

Create a new file shared_hosting_root\applications\your_app_name\deploy.sh

#!/bin/bash
echo "Copy public folder to public_html/your_app_name"
rsync -rv ./public/ ../../public_html/your_app_name

Using rsync ensures that if you ever run this deploy.sh several times, only those that are newer will be copied to the new location.

When you’re ready to run it, in the terminal run:

?> cd applications\your_app_name
?> sh deploy.sh

Caution: You have to run deploy.sh within applications\your_app_name, otherwise it will fail.

5. Accessing your app

There are 2 ways of accessing your application from the hosting server. You need to follow either one of the following step depending on your setup.

5a) Using subdomain

The easier way of accessing your application is to set up a subdomain (e.g. your_app_name.example.com) and point it to your application folder (i.e. public_html/your_app_name). This should automagically work without much hassle.

5b) Using primary domain

The other (slightly more complex) way is to point your primary domain (e.g. example.com) to your application folder (i.e. public_html/your_app_name).

By default, the primary domain points to the folder public_html in most of the shared hosting environment.

To do that, you need to create (or edit if it’s already there) a .htaccess file inside the public_html folder.

# Do not change this line. 
RewriteEngine on 

# Change example.com to your domain name
RewriteCond %{HTTP_HOST} ^(www.)?example.com$ 

# Change your_app_name to the subfolder name
RewriteCond %{REQUEST_URI} !^/your_app_name/ 

# Don't change the following two lines. 
RewriteCond %{REQUEST_FILENAME} !-f 
RewriteCond %{REQUEST_FILENAME} !-d 

# Change your_app_name to the subfolder name
# Change example.com to your domain name
RewriteRule ^(.*)$ /your_app_name/$1 
RewriteCond %{HTTP_HOST} ^(www.)?example.com$ 
RewriteRule ^(/)?$ your_app_name/index.php [L]

6. Em…

And that’s it.

I would also recommend using the same folder structure during your development so that you can experience the whole process of deployment before you upload to your hosting server.

Hope this helps!

7. Common Problems

There were a few cases of the following that may cause your Laravel 5 to not work on your live server:

  1. Your PHP version is lower than 5.5.9. Laravel 5 requires PHP 5.5.9 and above.
  2. Your folder structure is different. Make sure your local test environment is exactly the same as your live server. Starting from your server’s root folder.
  3. Re-read the whole tutorial. I find that some of my codes were truncated, so make sure you copy and paste correctly. Try scrolling left and right to see the full code line. Sorry about that.

Laravel migration error Cannot add foreign key contraint

If you’re getting this error message when executing migration on an existing table, you’re probably having the same issue as I was.

[Illuminate\Database\QueryException]
SQLSTATE[HY000]: General error: 1215 Cannot add foreign key constraint (SQL: alter table `pages` add constraint pages_category_id_foreign foreign key (`category_id`) references `categories` (`id`))
[PDOException]                                                          
  SQLSTATE[HY000]: General error: 1215 Cannot add foreign key constraint

The problem is because my ‘categories’ table was created as MyISAM type, which doesn’t support foreign key.

The solution is surprisingly very simple: Convert the table to InnoDB type.

So before I create the new table ‘pages’ which reference to the existing table ‘categories’ with a foreign key, I inserted a line to convert the table to InnoDB type.

We can do that easily with Laravel’s DB::statement.

Like this:

// Default type MyISAM doesn't support foreign key
// Convert table to InnoDB
if (Schema::hasTable('categories')) {
    DB::statement('ALTER TABLE categories ENGINE = InnoDB');
}

if (! Schema::hasTable('pages')) {
    Schema::create('pages', function(Blueprint $table)
    {
        $table->increments('id');
        $table->timestamps();
        $table->string('title', 255);
        ... omitted ...
        $table->integer('category_id')->nullable()->unsigned();
        $table->foreign('category_id')->references('id')->on('categories');
    });
}

I was stuck at this for almost half a day trying to figure out why the migration keeps giving me error (although the tables were created nevertheless).

Hope this helps.

Laravel: order of migrations with foreign keys

Honestly I didn’t know that SQLite is so forgiving until I had to migrate to MySQL in production recently.

Planning the database schema ahead of implementation was a habit, and it didn’t occur to me that the order of migrations with foreign keys was so important. SQLite didn’t produce any error, but when running Laravel migration in MySQL,  it produced an error like this for tables with foreign keys:

[Illuminate\Database\QueryException]
SQLSTATE[HY000]: General error: 1215 Cannot add foreign key constraint (SQL : alter table `profiles` add constraint profiles_company_id_foreign foreign key (`company_id`) references `companies` (`id`))

I was so puzzled because the schema looked correct and it ran without error with SQLite. So it took me awhile to realise that only 2 tables were affected, and coincidentally that 2 tables were the first 2 to be created of all migrations.

The order of the old migrations was like this:

  1. 2014_01_01_00001_create_profiles_table.php
    • Foreign key company_id references to id of table companies
  2. 2014_01_01_00002_create_contacts_table.php
    • Foreign key contacttype_id references to id of table contacttypes
  3. 2014_01_01_00003_create_companies_table.php
  4. 2014_01_01_00004_create_contacttypes_table.php

That first 2 tables referenced to some tables that didn’t exist at the point of migration, that’s why MySQL had an error trying to add a constraint.

I had to change the order of the migrations for that 2 tables to be created without error.

Modified order of migrations:

  1. 2014_01_01_00001_create_companies_table.php
  2. 2014_01_01_00002_create_contacttypes_table.php
  3.  2014_01_01_00003_create_profiles_table.php
    • Foreign key company_id references to id of table companies
  4.  2014_01_01_00004_create_contacts_table.php
    • Foreign key contacttype_id references to id of table contacttypes

Moral of the story: Tables with foreign keys should be created after the tables they reference to have been created.

I hope this will help someone else in the future.

Laravel 4: Using query builder lists for Form::select

Recently I realised I’ve been doing the wrong way to populate the array for Form::select().

In order to get Form::select() to work, the array you parse in must contain key => value. So in the past, I’ve been doing it this way:

$select_array = array();
foreach (Classname::all() as $model) {
    $select_array[$model->id] = $model->name;
}

It does the work, but there’s a built-in function in Laravel that can do this (probably faster, I think) in just 1 line:

$select_array = Classname::lists('name', 'id');

It returns an array that will work with Form::select().

This function is mentioned in the Laravel Documentation to retrieve specific column from a model. But it wasn’t clear that it’s also useful to populate an array for Form::select().

Advanced level

What if the value you want to get is in another class that’s related to this class? Well, we can combine join() with select() and then list().

For example:

$select_array = ModelOne::join('modeltwos', 'modeltwos.id', '=', 'modelones.modeltwo_id')
 ->select('modeltwos.name', 'modelones.id')
 ->lists('name', 'id');

I hope this is useful. Do leave a comment if you have a better way of populating the array for Form::select().

How to override config files of Laravel 4 package

If you want to be able to allow the users who use your package to publish and modify the package’s config files, you’ll need to add these into your Server Provider file, inside function register().

For example, my config files are structured like this:

- vendorname
  - packagename
    - src
      - config
        - image.php
        - config.php
        - menu.php

So within the PackagenameServiceProvider.php file, add these:

public function register()
{
  // other code omitted...

  // Get config loader
  $loader = $this->app['config']->getLoader();

  // Get environment name
  $env = $this->app['config']->getEnvironment();

  // Add package namespace with path set, override package if app config exists in the main app directory
 if (file_exists(app_path() .'/config/packages/vendorname/packagename')) {
 $loader->addNamespace('redminhrportal', app_path() .'/config/packages/vendorname/packagename');
 } else {
 $loader->addNamespace('packagename',__DIR__.'/../../config');
 }

  // Load package override config file
  $menu = $loader->load($env,'menu','packagename');
  $image = $loader->load($env,'image','packagename');
  $config = $loader->load($env,'config','packagename');

  // Override value
  $this->app['config']->set('packagename::menu',$menu);
  $this->app['config']->set('packagename::image',$image);
  $this->app['config']->set('packagename::config',$config);
}

To override the configuration files, users will have to publish the config file with the command below:

php artisan config:publish vendorname/packagename

Laravel: “Allowed memory size exhausted” error during unit tests

I’ve been using in-memory testing for my projects based on Laravel every since I found this great  tutorial: http://net.tutsplus.com/tutorials/php/testing-like-a-boss-in-laravel-models/

It was working very well as my test cases increases, to a point when I’m starting to get this error message:

Fatal error: Allowed memory size of 134217728 bytes exhausted (tried to allocate 16 bytes) in /Applications/AMPPS/www/project/vendor/symfony/console/Sym
fony/Component/Console/Command/Command.php on line 57

I couldn’t find the proper solution, but managed to get it working with a workaround here: http://forums.laravel.io/viewtopic.php?id=11723

We can temporarily increase the memory limit using this function:

// Temporarily increase memory limit to 256MB
ini_set('memory_limit','256M');

In my case, I needed more than 128MB of memory, so I conveniently increased it to 256MB. It depends on your usage and your hardware. Choose accordingly.

Since this is only required during my test (I follow the TDD approach, so testing comes regularly), I had added it in the TestCase class, inside method createApplication().

This is the full code in TestCase.php.

<?php

class TestCase extends Illuminate\Foundation\Testing\TestCase {

public function createApplication()
{
    // Temporarily increase memory limit to 256MB
    ini_set('memory_limit','256M');

    $unitTesting = true;
    $testEnvironment = 'testing';

    return require __DIR__.'/../../bootstrap/start.php';
}    

/**
 * Default preparation for each test
 */
public function setUp()
{
    parent::setUp();
    $this->prepareForTests();
}

/**
 * Migrates the database and set the mailer to 'pretend'.
 * This will cause the tests to run quickly.
 */
private function prepareForTests()
{
    Artisan::call('migrate');
    Mail::pretend(true);
} 

}

Laravel 4: things to note when creating Package

NOTE: This tutorial was written for Laravel version 4.0. I’ve added some notes for version 4.1 but they’re not tested yet. Do let me know if you see any problem.

When I first started using Laravel 4, I had been creating all my models, controllers and views in the root app folder. While things can get too comfortable and convenient here, it may not be a good idea to dump everything at the top. That’s when Package (or Bundle) comes in.

According to Laravel’s documentation:

“Packages are the primary way of adding functionality to Laravel.”

I found 2 great tutorials on creating your own Laravel 4 Package:

  1. http://culttt.com/2013/06/24/creating-a-laravel-4-package/
  2. http://jasonlewis.me/article/laravel-4-develop-packages-using-the-workbench

The following are some of the problems I’ve encountered and it took me quite some time to look for the solutions. Hope this will help someone else too.

1. Define your dependencies

A Package is like a sandbox module where it should contain its own dependencies (or vendors Packages). So you need to add your dependencies to your Package’s composer.json file.

As an example, I needed to include Cartalyst Sentry and Twitter Bootstrap to my Package, this is what I did under “require”:

"require": {
        "php": ">=5.3.0",
        "illuminate/support": "4.0.x",
        "cartalyst/sentry": "2.0.*",
        "twbs/bootstrap": "3.0.*"
},

 NOTE on Sentry:

After writing this blog, I’ve decided to move Sentry out of my package. Firstly, it will be cleaner and allow people using my package to choose their own authentication vendor. Secondly, I was getting so much trouble trying to get it to work properly. So it’s advisable to just put it on the Laravel app root instead.

Remember to run the following command line at your Package’s root folder:

php composer.phar update
php composer.phar dump-autoload

Note: On your first install, run “php composer.phar install”. Although using update will do the same thing too.

For dump-autoload, on the official documentation, they are using artisan instead of composer. I’m still not sure what’s the difference, but both seem to work.

php artisan dump-autoload

2. Extending Controller

When you download the Laravel 4 master, you will get a BaseController.php under the app\controllers folder. It looks something like this:

<?php

class BaseController extends Controller {

    /**
    * Setup the layout used by the controller.
    *
    * @return void
    */
    protected function setupLayout()
    {
        if ( ! is_null($this->layout))
        {
            $this->layout = View::make($this->layout);
        }
    }
}

And then all your custom controllers will extend this BaseController like this:

class CustomController extends BaseController {}

If you copy and paste this BaseController to your Package, it will not work. The Package will try to find “Controller” in your namespace Vendor\Package.

So to make it work, you must first define BaseController under your namespace, and then let Package knows that it needs to find the correct Controller.

In short, use this:

<?php namespace YourVendor\YourPackage;

use \Illuminate\Routing\Controllers\Controller;

class BaseController extends Controller {

     /**
     * Setup the layout used by the controller.
     *
     * @return void
     */
    protected function setupLayout()
    {
        if ( ! is_null($this->layout))
        {
            $this->layout = View::make($this->layout);
        }
    } 
}

Note for Laravel 4.1:

In Laravel 4.1, the Controller path has been moved. See http://laravel.com/docs/upgrade

Use this instead:

<?php namespace YourVendor\YourPackage;

use \Illuminate\Routing\Controller;

class BaseController extends Controller {

     // Your code
}

3. Using Sentry in your Package

Just to be clear, as some readers mistaken “Sentry” as my Package’s name. It’s a third party Package created by Cartalyst: “Sentry is a simple, powerful and easy to use authorisation and authentication package.” I wanted to include this third party Package in my custom Package to add authorisation and authentication capability.

But once Sentry is downloaded and installed to my Package, I still couldn’t get it to recognise the alias “Sentry”. So the following code produces an error:

Sentry::logout();

The FatalErrorException message was:

Class ‘Vendor\Package\Sentry’ not found

That’s right, the Package has mistakenly treated Sentry under my Package’s namespace.

If you remember from Laravel’s basic documentation, while in the app’s root folder, we can define aliases such as “Sentry” in the \app\config\app.php file. But there doesn’t seem to have any way to register that in my Package.

So what I did, as a workaround, is to include the namespace at the top of my file. Like this:

<?php namespace YourVendor\YourPackage;

use Cartalyst\Sentry\Facades\Laravel\Sentry;

class CustomController extends BaseController {
    public function logOut()
    {
        Sentry::logout();
    }
}

Works like charm! But if you know of a shorter and better way, please leave me a message!

Better solution (edited)

Thanks to hardik dangar, there’s actually a shorter way to do this. Simply add a backslash before Sentry so that php doesn’t search Sentry within my namespace.

<?php namespace YourVendor\YourPackage;

class CustomController extends BaseController {
    public function logOut()
    {
        \Sentry::logout();
    }
}

4. Using Illuminate Facades

Just as you thought everything is well and ready to code, you found yourself stuck at this line!

return View::make('vendorpackage::users/view');

And the FatalErrorException message is:

Class ‘Vendor\Package\View’ not found

What the?!

The same goes to Redirect, Input and Validator.

Base on my previous experience with Sentry, I got just the right idea.

Simply add the following to the top of your code:

<?php namespace YourVendor\YourPackage;

use Illuminate\Support\Facades\Validator;
use Illuminate\Support\Facades\Redirect;
use Illuminate\Support\Facades\Input;
use Illuminate\Support\Facades\View;

class CustomController extends BaseController {

Tada!!

Better solution (edited)

Thanks to hardik dangar, there’s actually a shorter way to do this. Simply add a backslash before View so that php doesn’t search View within my namespace.

return \View::make('vendorpackage::users/view');

5. Using Views in your Package

That right, you didn’t see it wrongly. This is how you call your Package’s view.

For example, we want view “users\view”, add your Package’s name to the front like this:

View::make('vendorpackage::users/view');

Then how about using master layout? Same logic, like this:

@extends('vendorpackage::layouts.master')

Where the directory is:

workbench\yourvendor\yourpackage\src\views\layouts\master.blade.php

6. Extending Eloquet in your own model

Laravel documentation taught us this:

class User extends Eloquent {}

This won’t work in a Package. Instead, you should do this:

<?php namespace YourVendor\YourPackage;

use Illuminate\Database\Eloquent\Model;

class User extends Model {}

7. Using Controller in your Package

This used to work:

{{ Form::open(array('action' => 'UserController@postStore')) }}

But to use your Package’s Controller, you need to add your Vendor\Package namespace to the Controller like this:

{{ Form::open(array('action' => 'YourVendor\YourPackage\UserController@postStore')) }}

8. Loading Package Config file

If you want to create a separate database for your package, you can define your database configuration within your package directory:

workspace\vendor\packagename\src\config\database.php

Then add this to the package service provider boot() method:

public function boot()
{
    $this->package('vendor/package');
    include __DIR__."/routes.php";

    // Add my database configurations to the default set of configurations                        
    $this->app['config']['database.connections'] = array_merge(
        $this->app['config']['database.connections']
       ,Config::get('package::database.connections')
    );
}

Source: http://stackoverflow.com/questions/15304722/eloquent-laravel-4-package-database-configuration-format

9. Loading external package within Providers and Aliases

In normal circumstances, when we add a new package to a Laravel installation, we would edit the config/app.php by adding the package namespace within the “Providers” and “Aliases” arrays.

However, when we need to add another external package that is a requirement within our own custom package, we wouldn’t want our users to edit a long lists of Providers and Aliases. Ideally, they should only include our custom package.

I’ve been searching for awhile and finally found a solution from this forum.

Solution:

In this example, we want to add an external package call “Markdown”.

In the file myLaravelProject/workbench/my-vendor/my-package/src/MyVendor/MyPackage/MyPackageServiceProvider,

put this in the boot() method:

$this->app->register('SomeExternalPackage\Markdown\MarkdownServiceProvider');

and this in the register() method:

$this->app->booting(function()
{
    $loader = \Illuminate\Foundation\AliasLoader::getInstance();
    $loader->alias('MyPackage', 'MyVendor\MyPackage\Facades\MyPackage');
    $loader->alias('Markdown', 'SomeExternalPackage\Markdown\Facades\Markdown');
});

10. Override config files of package

If you want to be able to allow the users who use your package to publish and modify the package’s config files, following this tutorial:

How to override config files of Laravel 4 package