Contributing to Open Source – Updating Phalconphp.com

A while back, I wrote a tutorial about installing Phalcon on Windows Azure. However, Phalconphp.com's home page still doesn't mention Azure as a supported environment in the "Phalcon can be installed on" section:

In this tutorial, we'll clone the Phalconphp.com website to our local PuPHPet VM, update it to include new information about a supported environment, and submit a pull request to the project owners. This post is a spiritual successor to my Dillinger.io Pull Request Tutorial, so be sure to check it out before moving along, as this tutorial will focus more on the PuPHPet workflow than the actual pull request workflow.

Note that while I will be using PuPHPet to prepare an environment in which to launch the website, you're by no means bound by this restriction – if you'd prefer to just clone it to your already set up local environment, please feel free to do so, though I personally believe the PuPHPet way is faster if you just do what I did.

Initial configuration

If you aren't familiar with PuPHPet yet, please see Matthew Setter's tutorial. Let's visit PuPHPet and set up our virtual machine. One thing we need to keep in mind to make things easier for us, is where the Phalcon website's document root is, so we can bind that in our VM. If we check their Github, we can see they use the standard public folder in the main "website" repo, and that's what we'll do too.

I've chosen the following options, so feel free to follow in my footsteps or download my final version here (anything I don't mention was left on the default value):

Environment: Local

Server: Apache

OS: Ubuntu Precise 12.04 x64 – Virtualbox 4.3

Name: upgrading-phalconphp

Installed packages: vim

Timezone: Europe/Zagreb (leave on your own if you want)

Install XDebug: yes

MySQL options: db1, user1, pass1

Under Apache Virtual Host, I put the values as follows:

Create and download the archive, place it in your vagrant boxes location and unzip it.

Next, let's add the Phalcon provision script from this article to the shell subfolder, and add the following line under all the provision blocks in the Vagrantfile:

config.vm.provision :shell, :path => "shell/install_phalcon.sh"

This will make sure Phalcon is installed on VM boot.

Next, we need to make sure the website is ready to run when the VM boots. We first need to fork the website repository. Go to https://github.com/phalcon/website and fork it.

Clone your fork into the box's folder root:

git clone http://github.com/YOUR_USERNAME/website

After cloning, my folder structure looked like this:

If you used the PuPHPet procedure above, run vagrant up and wait for the VM boot to finish. If you picked Apache as the server like I did, after the VM boot, you might have to disable the default vhost. You can do this by SSHing to the box with vagrant ssh and executing:

sudo a2dissite 15-default.conf
sudo service apache2 reload

This removes the default configuration, leaving alive only the one we set up in PuPHPet under "Virtual Host". Since the Phalcon website doesn't use a database (most of the material is static), we can immediately run it locally, without the need for any further modifications:

There might be some warnings about PHP not being able to write to the cache directory in the source code folder, but we won't be dealing with that right now as it's not that important for this particular quick fix.

Connect your repo to the original upstream, then make a new branch called adding-azure and switch to it, by executing:

Theoretically, we could have added the default vhost disable commands and the git procedure to a final provision shell file. I'll leave that up to you for experimentation.

Updating the website

Finally, we can start working.

The relevant files will be:

app/views/index/index.volt

app/views/pages/hosting.volt

We will also need a new image file as the logo for Windows Azure. I've made one you can download:

Add this image to public/images/hosting. Seeing as all the hosting provider images in that folder have their color counterpart, even if the color version is never used, let's respect this tradition and add our own as well.

Next, we need to edit the home page to include the image into the image-set link. Open index.volt and add it to the end of the hosting images, like so:

Notice how we used some translation placeholders like hosting_azure_1. This is because Phalcon uses language files as a multi-language site, and the actual text of the content presented on the website is defined elsewhere.

These language files are in app/var/languages. They are simple key=>value arrays defined in PHP files, and easily editable.

Open the en.php file for English, and find the part where the hosting descriptions are (should be line 198). At the bottom of that section, add our own:

If you're feeling extra generous, add some other translations to the other language files – I'm sure the Phalcon team would appreciate it.

Sending a pull request

Once we add everything to Git with git add and commit with a decent message like "Added Azure to hosting providers, both on home page and the hosting page. Linked to article describing the procedure.", we can push the repo online.

Once pushed, we submit the Pull Request.

Conclusion

All that's left to do now is wait and see if the devs will accept it. Regardless of whether or not the PR pulls through, this article has taught you how simple it actually is to contribute to an open source project.

If you want your contributions count to go up or just need to gain some experience slowly but surely, look around for some projects that need help and assist. Start small, like we did in this article – by making changes to HTML and text, then slowly move on to proper functionality as you see some missing.

If you have your own contribution story you'd like to share, a specific request, or just general feedback regarding this article, please don't hesitate to leave it in the comments below!

Bruno is a coder from Croatia with Master’s Degrees in Computer Science and English Language and Literature. He’s the editor of SitePoint’s PHP channel and a developer evangelist for Diffbot.com. He avoids legacy code like the plague and when picking projects makes sure they’re as cutting edge as possible. He’s a treadmill desk enthusiast and active (board)gamer who sometimes blogs.

Free Guide:

7 Habits of Successful CTOs

"What makes a great CTO?" Engineering skills? Business savvy? An innate tendency to channel a mythical creature (ahem, unicorn)? All of the above? Discover the top traits of the most successful CTOs in this free guide.