FreePBX Guide

Welcome to FreePBX Guide, a completely free and open source guide, written for developers working on the FreePBX platform.

Regardless of your previous FreePBX experience, if you’d like to contribute to FreePBX, or build your own FreePBX modules to add additional functionality to the platform, this guide will walk you through everything you need to know to be successful.

Table of Contents

Why This Guide Exists

FreePBX is one of the lagest open source PBX systems in the world, with over 500,000 active users and more than 5,000,000 downloads to date.

With so many users, FreePBX has gained a lot of attention from hobbyists, system administrators, and even large enterprises as it allows the smallest (and largest) of companies to deploy a stable and feature-rich phone system at no cost.

As time has gone on, and the platform has become more and more advanced, developers have had a harder and harder time working on the platform as there are no FreePBX development guides that walk new developers through the basics needed to contribute to the project, as well as build their own FreePBX modules and services.

The purpose of this guide is to teach you:

  • How to contribute code to the FreePBX project successfully.
  • How to build your own FreePBX modules.
  • Which style conventions you should use while writing code.
  • What things you should avoid doing.
  • Useful tips and tricks to make your life easier.

Over time, this guide will continue to be updated to reflect modern FreePBX practices, and will evolve alongside the project to ensure developers have an easy way to get started doing what they do best: hacking code.

Who This Guide is For

FreePBX Guide is written exclusively for developers (computer programmers) wanting to:

  • Contribute code to the FreePBX project.
  • Build their own FreePBX modules and services to extend base FreePBX functionality.

If you’re not a developer, this guide is probably not for you.

Before continuing, you should have a basic understanding of the following technologies:

If you’re not familiar with Asterisk, I’d highly recommend reading the book Asterisk: The Definitive Guide, which is (in my humble opinion) the best book ever written on Asterisk.

Note

Although you don’t need to be an expert at PHP, having a basic understanding of the language will help as you go through the book, since FreePBX is written in PHP and we’ll be discussing code samples as we go along.

Preparing the Environment

Before we get too far into things, I’d like to first walk you through setting up your development environment.

Since we’re going to be hacking FreePBX code, we’re obviously going to need a FreePBX server to do work on as we make our way through this book.

Let’s get to it!

Setting up VirtualBox

Instead of installing FreePBX manually, compiling Asterisk, and all that good stuff, we’re instead going to run the officially supported FreePBX Distro, this way we don’t have to go out of our way to get things setup.

Since we’re going to be running the official FreePBX distro, it also makes sense that we’ll want to install it in a virtual machine–this way we won’t have to install it on an actual computer anywhere, and waste resources.

VirtualBox is the perfect tool for this. It’s free, works on a wide variety of platforms, and is really simple to get setup.

So before we do anything else, download and install VirtualBox.

Now that you’ve got VirtualBox installed, let’s create a new virtual machine! To do this:

  1. Click ‘New’.
  2. Type in a name for your new virtual machine. I usually use something like “FreePBX Beta 2.11.63-3”. This way I know exactly which version of FreePBX I’m running in this virtual machine.
  3. Under the ‘Type’ drop down menu, select ‘Linux’.
  4. Under the ‘Version’ drop down menu, select ‘Other Linux’.
  5. Press ‘Next’.

On this next screen, you can give your virtual machine as much RAM as you want. I’d recommend giving it about 2G of RAM–this way you can boot your FreePBX development machine up and down quickly.

For the rest of this process, just press next and accept the defaults.

You should now how a new virtual machine ready to configure and use!

Preparing the Install

Now before we install FreePBX on our new virtual machine, we need make two small changes to our new virtual machine configuration.

And of course, let’s not forget to download the FreePBX distro! You can download this from the FreePBX distro download page.

First off, open the configuration menu by right clicking the virtual machine you created a moment ago, and click ‘Settings’.

  1. Visit the ‘Storage’ tab on the left, click the CD ROM icon, and on the right side of the screen, click the CD ROM icon again and select ‘Choose a virtual CD/DVD disk file...’ Now navigate to the ISO file you downloaded above, and select it. This is the equivalent of inserting a burned CD ROM into your virtual machine’s CD ROM drive.
  2. Now select the ‘Network’ tab on the left, and in the drop down menu labeled ‘Attached to:’, select ‘Bridged Adapter’. This means that your FreePBX virtual machine will get an IP address on your network, just like your development computer.

Now we’re ready to do the install!

Installing FreePBX

TODO

Future Expectations

TODO

Who Wrote This?

This guide is written by Randall Degges and contributors.

If you’d like to keep up-to-date with changes to this guide, you’re encouraged to:

Reference Stuff