Merge branch 'gh-pages' of github.com:codeguy/php-the-right-way into gh-pages

Conflicts:
	_posts/01-04-01-Mac-Setup.md

CONTRIBUTING.md

@@ -51,8 +51,8 @@ included in the project:
 2. If you cloned a while ago, get the latest changes from upstream:
 
    ```bash
-   git checkout master
-   git pull upstream master
+   git checkout gh-pages
+   git pull upstream gh-pages
    ```
 
 3. Create a new topic branch (off the main project development branch) to
@@ -73,7 +73,7 @@ included in the project:
 6. Locally merge (or rebase) the upstream development branch into your topic branch:
 
    ```bash
-   git pull [--rebase] upstream master
+   git pull [--rebase] upstream gh-pages
    ```
 
 7. Push your topic branch up to your fork:

_layouts/default.html

@@ -35,8 +35,8 @@
                 <li><a href="/#site-header">Welcome</a>
                     <ul>
                         <li><a href="/#translations">Translations</a></li>
-                        <li><a href="/#how_to_contribute">How to Contribute</a></li>
-                        <li><a href="/#spread_the_word">Spread the Word!</a></li>
+                        <li><a href="/#how-to-contribute">How to Contribute</a></li>
+                        <li><a href="/#spread-the-word">Spread the Word!</a></li>
                     </ul>
                 </li>
                 {% assign lastIsChild = false %}

_posts/01-02-01-Use-the-Current-Stable-Version.md

@@ -1,12 +1,12 @@
 ---
-title: Use the Current Stable Version (5.5)
+title: Use the Current Stable Version (5.6)
 isChild: true
 anchor: use_the_current_stable_version
 ---
 
-## Use the Current Stable Version (5.5) {#use_the_current_stable_version_title}
+## Use the Current Stable Version (5.6) {#use_the_current_stable_version_title}
 
-If you are just getting started with PHP make sure to start with the current stable release of [PHP 5.5][php-release]. PHP has made great strides adding powerful [new features](#language_highlights) over the last few years. Don't let the minor version number difference between 5.2 and 5.5 fool you, it represents _major_ improvements. If you are looking for a function or its usage, the documentation on the [php.net][php-docs] website will have the answer.
+If you are getting started with PHP, start with the current stable release of [PHP 5.6][php-release]. PHP has added powerful [new features](#language_highlights) over the last few years. Though the incremental version number difference between 5.2 and 5.6 is small, it represents _major_ improvements. If you are looking for a function or its usage, the documentation on the [php.net][php-docs] website will have the answer.
 
 [php-release]: http://www.php.net/downloads.php
 [php-docs]: http://www.php.net/manual/en/

_posts/01-03-01-Built-in-Web-Server.md

@@ -6,7 +6,7 @@ anchor: builtin_web_server
 
 ## Built-in web server {#builtin_web_server_title}
 
-You can start learning PHP without the hassle of installing and configuring a full-fledged web server (PHP 5.4+ required). To start the server, run the following from your terminal in your project's web root:
+With PHP 5.4 or newer, you can start learning PHP without installing and configuring a full-fledged web server. To start the server, run the following command from your terminal in your project's web root:
 
     > php -S localhost:8000
 

_posts/01-04-01-Mac-Setup.md

@@ -37,7 +37,8 @@ The solutions listed above mainly handle PHP itself, and do not supply things li
 [Homebrew PHP]: https://github.com/Homebrew/homebrew-php#installation
 [mac-compile]: http://www.php.net/manual/en/install.macosx.compile.php
 [xcode-gcc-substitution]: https://github.com/kennethreitz/osx-gcc-installer
+
 ["Command Line Tools for XCode"]: https://developer.apple.com/downloads
-[mamp-downloads]: http://www.mamp.info/en/downloads/index.html
+[mamp-downloads]: http://www.mamp.info/en/downloads/
 [phpbrew]: https://github.com/phpbrew/phpbrew
 [xampp]: http://www.apachefriends.org/en/xampp.html

_posts/01-05-01-Windows-Setup.md

@@ -24,5 +24,5 @@ PHP.
 [zsce]: http://www.zend.com/en/products/server-ce/
 [xampp]: http://www.apachefriends.org/en/xampp.html
 [easyphp]: http://www.easyphp.org/
-[wamp]: http://www.wampserver.com/
+[wamp]: http://www.wampserver.com/en/
 [php-iis]: http://php.iis.net/

_posts/01-06-01-Vagrant.md

@@ -29,6 +29,7 @@ If you need a little help to start using Vagrant there are three services that m
 - [Puphpet][puphpet]: simple GUI to set up virtual machines for PHP development. **Heavily focused in PHP**. Besides
   local VMs, can be used to deploy to cloud services as well. The provisioning is made with Puppet.
 - [Protobox][protobox]: is a layer on top of vagrant and a web GUI to setup virtual machines for web development. A single YAML document controls everything that is installed on the virtual machine.
+- [Phansible][phansible]: provides an easy to use interface that helps you generate Ansible Playbooks for PHP based projects.
 
 [vagrant]: http://vagrantup.com/
 [puppet]: http://www.puppetlabs.com/
@@ -36,3 +37,4 @@ If you need a little help to start using Vagrant there are three services that m
 [rove]: http://rove.io/
 [puphpet]: https://puphpet.com/
 [protobox]: http://getprotobox.com/
+[phansible]: http://phansible.com/

_posts/03-05-01-Command-Line-Interface.md

@@ -5,7 +5,7 @@ anchor: command_line_interface
 
 ## Command Line Interface {#command_line_interface_title}
 
-PHP was created primarily to write web applications, but it's also useful for scripting command line interface (CLI) programs. Command line PHP programs can help you automate common tasks like testing, deployment, and application administrivia.
+PHP was created to write web applications, but is also useful for scripting command line interface (CLI) programs. Command line PHP programs can help automate common tasks like testing, deployment, and application administrivia.
 
 CLI PHP programs are powerful because you can use your app's code directly without having to create and secure a web GUI for it. Just be sure not to put your CLI PHP scripts in your public web root!
 

_posts/05-05-01-PHP-and-UTF8.md

@@ -1,12 +1,13 @@
 ---
+title: Working with UTF-8
 isChild: true
 anchor: php_and_utf8
 ---
 
-## PHP and UTF-8 {#php_and_utf8_title}
+## Working with UTF-8 {#php_and_utf8_title}
 
 _This section was originally written by [Alex Cabal](https://alexcabal.com/) over at 
-[PHP Best Practices](https://phpbestpractices.org/#utf-8) and has now been shared here_.
+[PHP Best Practices](https://phpbestpractices.org/#utf-8) and has been used as the basis for our own UTF-8 advice_.
 
 ### There's no one-liner. Be careful, detailed, and consistent.
 
@@ -18,9 +19,8 @@ for a brief, practical summary.
 
 The basic string operations, like concatenating two strings and assigning strings to variables, don't need anything 
 special for UTF-8. However most string functions, like `strpos()` and `strlen()`, do need special consideration. These 
-functions often have an `mb_*` counterpart: for example, `mb_strpos()` and `mb_strlen()`. Together, these counterpart 
-functions are called the Multibyte String Functions. The multibyte string functions are specifically designed to 
-operate on Unicode strings.
+functions often have an `mb_*` counterpart: for example, `mb_strpos()` and `mb_strlen()`. These `mb_*` strings are made 
+available to you via the [Multibyte String Extension], and are specifically designed to operate on Unicode strings.
 
 You must use the `mb_*` functions whenever you operate on a Unicode string. For example, if you use `substr()` on a 
 UTF-8 string, there's a good chance the result will include some garbled half-characters. The correct function to use 
@@ -32,17 +32,21 @@ string has a chance of being garbled during further processing.
 Not all string functions have an `mb_*` counterpart. If there isn't one for what you want to do, then you might be out 
 of luck.
 
-Additionally, you should use the `mb_internal_encoding()` function at the top of every PHP script you write (or at the 
+You should use the `mb_internal_encoding()` function at the top of every PHP script you write (or at the 
 top of your global include script), and the `mb_http_output()` function right after it if your script is outputting to 
 a browser. Explicitly defining the encoding of your strings in every script will save you a lot of headaches down the 
 road.
 
-Finally, many PHP functions that operate on strings have an optional parameter letting you specify the character 
+Additionally, many PHP functions that operate on strings have an optional parameter letting you specify the character 
 encoding. You should always explicitly indicate UTF-8 when given the option. For example, `htmlentities()` has an 
-option for character encoding, and you should always specify UTF-8 if dealing with such strings.
+option for character encoding, and you should always specify UTF-8 if dealing with such strings. Note that as of PHP 5.4.0, UTF-8 is the default encoding for `htmlentities()` and `htmlspecialchars()`.
 
-Note that as of PHP 5.4.0, UTF-8 is the default encoding for `htmlentities()` and `htmlspecialchars()`.
+Finally, If you are building an distributed application and cannot be certain that the `mbstring` extension will be
+enabled, then consider using the [patchwork/utf8] Composer package. This
+will use `mbstring` if it is available, and fall back to non UTF-8 functions if not.
 
+[Multibyte String Extension]: http://php.net/manual/en/book.mbstring.php
+[patchwork/utf8]: https://packagist.org/packages/patchwork/utf8
 
 ### UTF-8 at the Database level
 
@@ -58,8 +62,9 @@ Further Reading for why.
 
 ### UTF-8 at the browser level
 
-Use the `mb_http_output()` function to ensure that your PHP script outputs UTF-8 strings to your browser. In your HTML, 
-include the [charset `<meta>` tag](http://htmlpurifier.org/docs/enduser-utf8.html) in your page's `<head>` tag. 
+Use the `mb_http_output()` function to ensure that your PHP script outputs UTF-8 strings to your browser. 
+
+The browser will then need to be told by the HTTP response that this page should be considered as UTF-8. The historic approach to doing that was to include the [charset `<meta>` tag](http://htmlpurifier.org/docs/enduser-utf8.html) in your page's `<head>` tag. This approach is perfectly valid, but setting the charset in the `Content-Type` header is actually [much faster](https://developers.google.com/speed/docs/best-practices/rendering#SpecifyCharsetEarly).
 
 {% highlight php %}
 <?php
@@ -103,10 +108,11 @@ $handle->execute();
  
 // Store the result into an object that we'll output later in our HTML
 $result = $handle->fetchAll(\PDO::FETCH_OBJ);
+
+header('Content-Type: text/html; charset=utf-8');
 ?><!doctype html>
 <html>
     <head>
-        <meta charset="UTF-8" />
         <title>UTF-8 test page</title>
     </head>
     <body>

_posts/07-01-01-Databases.md

@@ -61,7 +61,7 @@ $pdo->query("SELECT name FROM users WHERE id = " . $_GET['id']); // <-- NO!
 {% endhighlight %}
 
 This is terrible code. You are inserting a raw query parameter into a SQL query. This will get you hacked in a
-heartbeat, using a practice called [SQL Injecton]. Just imagine if a hacker passes in an inventive `id` parameter by calling a URL like
+heartbeat, using a practice called [SQL Injection](http://wiki.hashphp.org/Validation). Just imagine if a hacker passes in an inventive `id` parameter by calling a URL like
 `http://domain.com/?id=1%3BDELETE+FROM+users`.  This will set the `$_GET['id']` variable to `1;DELETE FROM users`
 which will delete all of your users! Instead, you should sanitize the ID input using PDO bound parameters.
 

_posts/07-02-01-Interacting-via-Code.md

@@ -4,7 +4,7 @@ title: Interacting with Databases
 anchor: databases_interacting
 ---
 
-## Interacting with Databases
+## Interacting with Databases {#databases_interacting_title}
 
 When developers first start to learn PHP, they often end up mixing their database interaction up with their 
 presentation logic, using code that might look like this:
@@ -20,14 +20,14 @@ foreach ($db->query('SELECT * FROM table') as $row) {
 
 This is bad practice for all sorts of reasons, mainly that its hard to debug, hard to test, hard to read and it is going to output a lot of fields if you don't put a limit on there.
 
-While there are many other solutions to doing this - depending on if you prefer [OOP](/#object-oriented-programming) or [functional programming](/#functional-programming) - there must be some element of seperation. 
+While there are many other solutions to doing this - depending on if you prefer [OOP](/#object-oriented-programming) or [functional programming](/#functional-programming) - there must be some element of separation. 
 
 Consider the most basic step:
 
 {% highlight php %}
 <?php
-functon getAllSomethings($db) {
-	return $db->query('SELECT * FROM table');
+function getAllSomethings($db) {
+    return $db->query('SELECT * FROM table');
 }
 
 foreach (getAllFoos() as $row) {
@@ -35,7 +35,7 @@ foreach (getAllFoos() as $row) {
 }
 {% endhighlight %}
 
-That is a good start. Put those two items in two different files and you've got some clean seperation.
+That is a good start. Put those two items in two different files and you've got some clean separation.
 
 Create a class to place that method in and you have a "Model". Create a simple `.php` file to put the presentation logic in and you have a "View", which is very nearly [MVC] - a common OOP architecture for most [frameworks](/#frameworks_title).
 
@@ -63,16 +63,16 @@ include 'views/foo-list.php';
 <?php
 class Foo()
 {
-	protected $db;
+    protected $db;
 
-	public function __construct(PDO $db)
-	{
-		$this->db = $db;
-	}
+    public function __construct(PDO $db)
+    {
+        $this->db = $db;
+    }
 
-	public functon getAllFoos() {
-		return $this->db->query('SELECT * FROM table');
-	}
+    public function getAllFoos() {
+        return $this->db->query('SELECT * FROM table');
+    }
 }
 {% endhighlight %}
 

_posts/07-03-01-Abstraction-Layers.md

@@ -4,7 +4,7 @@ title: Abstraction Layers
 anchor: databases_abstraction_layers
 ---
 
-## Abstraction Layers
+## Abstraction Layers {#databases_abstraction_layers_title}
 
 Many frameworks provide their own abstraction layer which may or may not sit on top of PDO.  These will often emulate features for
 one database system that is missing from another by wrapping your queries in PHP methods, giving you actual database abstraction instead of just the connection abstraction that PDO provides.
@@ -22,7 +22,7 @@ Some abstraction layers have been built using the [PSR-0][psr0] or [PSR-4][psr4]
 [2]: http://www.doctrine-project.org/projects/dbal.html
 [4]: http://packages.zendframework.com/docs/latest/manual/en/index.html#zend-db
 [6]: https://github.com/auraphp/Aura.Sql
-[7]: http://propelorm.org/Propel/
+[7]: http://propelorm.org/
 
 [psr0]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md
 [psr4]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md

_posts/08-01-01-Templating.md

@@ -0,0 +1,12 @@
+---
+title: Templating
+anchor: templating
+---
+
+# Templating {#templating_title}
+
+Templates provide a convenient way of separating your controller and domain logic from your presentation logic.
+Templates typically contain the HTML of your application, but may also be used for other formats, such as XML.
+Templates are often referred to as "views", which make up **part of** the second component of the
+[model–view–controller](http://www.phptherightway.com/pages/Design-Patterns.html#model-view-controller) (MVC)
+software architecture pattern.

_posts/08-02-01-Benefits.md

@@ -0,0 +1,21 @@
+---
+isChild: true
+anchor: templating_benefits
+---
+
+## Benefits {#templating_benefits_title}
+
+The main benefit to using templates is the clear separation they create between the presentation logic and the rest of
+your application. Templates have the sole responsibility of displaying formatted content. They are not responsible for
+data lookup, persistence or other more complex tasks. This leads to cleaner, more readable code which is especially
+helpful in a team environment where developers work on the server-side code (controllers, models) and designers work on
+the client-side code (markup).
+
+Templates also improve the organization of presentation code. Templates are typically placed in a "views" folder, each
+defined within a single file. This approach encourages code reuse where larger blocks of code are broken into smaller,
+reusable pieces, often called partials. For example, your site header and footer can each be defined as templates,
+which are then included before and after each page template.
+
+Finally, depending on the library you use, templates can offer more security by automatically escaping user-generated
+content. Some libraries even offer sand-boxing, where template designers are only given access to white-listed
+variables and functions.

_posts/08-03-01-Plain-PHP-Templates.md

@@ -0,0 +1,62 @@
+---
+isChild: true
+anchor: plain_php_templates
+---
+
+## Plain PHP Templates {#plain_php_templates_title}
+
+Plain PHP templates are simply templates that use native PHP code. They are a natural choice since PHP is actually a
+template language itself. That simply means that you can combine PHP code within other code, like HTML. This is
+beneficial to PHP developers as there is no new syntax to learn, they know the functions available to them, and their
+code editors already have PHP syntax highlighting and auto-completion built-in. Further, plain PHP templates tend to be
+very fast as no compiling stage is required.
+
+Every modern PHP framework employs some kind of template system, most of which use plain PHP by default. Outside of
+frameworks, libraries like [Plates](http://platesphp.com/) or [Aura.View](https://github.com/auraphp/Aura.View) make
+working with plain PHP templates easier by offering modern template functionality such as inheritance, layouts and
+extensions.
+
+### Simple example of a plain PHP template
+
+Using the [Plates](http://platesphp.com/) library.
+
+{% highlight php %}
+<?php // user_profile.php ?>
+
+<?php $this->insert('header', ['title' => 'User Profile']) ?>
+
+<h1>User Profile</h1>
+<p>Hello, <?=$this->escape($name)?></p>
+
+<?php $this->insert('footer') ?>
+{% endhighlight %}
+
+### Example of plain PHP templates using inheritance
+
+Using the [Plates](http://platesphp.com/) library.
+
+{% highlight php %}
+<?php // template.php ?>
+
+<html>
+<head>
+    <title><?=$title?></title>
+</head>
+<body>
+
+<main>
+    <?=$this->section('content')?>
+</main>
+
+</body>
+</html>
+{% endhighlight %}
+
+{% highlight php %}
+<?php // user_profile.php ?>
+
+<?php $this->layout('template', ['title' => 'User Profile']) ?>
+
+<h1>User Profile</h1>
+<p>Hello, <?=$this->escape($name)?></p>
+{% endhighlight %}

_posts/08-04-01-Compiled-Templates.md

@@ -0,0 +1,69 @@
+---
+isChild: true
+anchor: compiled_templates
+---
+
+## Compiled Templates {#compiled_templates}
+
+While PHP has evolved into a mature, object oriented language, it
+[hasn't improved much](http://fabien.potencier.org/article/34/templating-engines-in-php) as a templating language.
+Compiled templates, like [Twig](http://twig.sensiolabs.org/) or [Smarty](http://www.smarty.net/)*, fill this void by
+offering a new syntax that has been geared specifically to templating. From automatic escaping, to inheritance and
+simplified control structures, compiled templates are designed to be easier to write, cleaner to read and safer to use.
+Compiled templates can even be shared across different languages, [Mustache](http://mustache.github.io/) being a good
+example of this. Since these templates must be compiled there is a slight performance hit, however this is very minimal
+when proper caching is used.
+
+**While Smarty offers automatic escaping, this feature is NOT enabled by default.*
+
+### Simple example of a compiled template
+
+Using the [Twig](http://twig.sensiolabs.org/) library.
+
+{% highlight text %}
+{% raw %}
+{% include 'header.html' with {'title': 'User Profile'} %}
+
+<h1>User Profile</h1>
+<p>Hello, {{ name }}</p>
+
+{% include 'footer.html' %}
+{% endraw %}
+{% endhighlight %}
+
+### Example of compiled templates using inheritance
+
+Using the [Twig](http://twig.sensiolabs.org/) library.
+
+{% highlight text %}
+{% raw %}
+// template.php
+
+<html>
+<head>
+    <title>{% block title %}{% endblock %}</title>
+</head>
+<body>
+
+<main>
+    {% block content %}{% endblock %}
+</main>
+
+</body>
+</html>
+{% endraw %}
+{% endhighlight %}
+
+{% highlight text %}
+{% raw %}
+// user_profile.php
+
+{% extends "template.html" %}
+
+{% block title %}User Profile{% endblock %}
+{% block content %}
+    <h1>User Profile</h1>
+    <p>Hello, {{ name }}</p>
+{% endblock %}
+{% endraw %}
+{% endhighlight %}

_posts/08-05-01-Further-Reading.md

@@ -0,0 +1,28 @@
+---
+isChild: true
+anchor: templating_further_reading
+---
+
+## Further Reading {#templating_further_reading_title}
+
+### Articles & Tutorials
+
+- [Templating Engines in PHP](http://fabien.potencier.org/article/34/templating-engines-in-php)
+- [An Introduction to Views & Templating in CodeIgniter](http://code.tutsplus.com/tutorials/an-introduction-to-views-templating-in-codeigniter--net-25648)
+- [Getting Started With PHP Templating](http://www.smashingmagazine.com/2011/10/17/getting-started-with-php-templating/)
+- [Roll Your Own Templating System in PHP](http://code.tutsplus.com/tutorials/roll-your-own-templating-system-in-php--net-16596)
+- [Master Pages](https://laracasts.com/series/laravel-from-scratch/episodes/7)
+- [Working With Templates in Symfony 2](http://code.tutsplus.com/tutorials/working-with-templates-in-symfony-2--cms-21172)
+
+### Libraries
+
+- [Aura.View](https://github.com/auraphp/Aura.View) *(native)*
+- [Blade](http://laravel.com/docs/templates) *(compiled, framework specific)*
+- [Dwoo](http://dwoo.org/) *(compiled)*
+- [Latte](https://github.com/nette/latte) *(compiled)*
+- [Mustache](https://github.com/bobthecow/mustache.php) *(compiled)*
+- [PHPTAL](http://phptal.org/) *(compiled)*
+- [Plates](http://platesphp.com/) *(native)*
+- [Smarty](http://www.smarty.net/) *(compiled)*
+- [Twig](http://twig.sensiolabs.org/) *(compiled)*
+- [Zend\View](http://framework.zend.com/manual/2.3/en/modules/zend.view.quick-start.html) *(native, framework specific)*

_posts/12-05-01-Building-your-Application.md

@@ -49,7 +49,7 @@ Chef resources for PHP developers:
 
 * [Three part blog series about deploying a LAMP application with Chef, Vagrant, and EC2](http://www.jasongrimes.org/2012/06/managing-lamp-environments-with-chef-vagrant-and-ec2-1-of-3/)
 * [Chef Cookbook which installs and configures PHP 5.3 and the PEAR package management system](https://github.com/opscode-cookbooks/php)
-
+* [Chef video tutorial series by Opscode, the makers of chef](https://www.youtube.com/playlist?list=PLrmstJpucjzWKt1eWLv88ZFY4R1jW8amR)
 Further reading:
 
 * [Automate your project with Apache Ant](http://net.tutsplus.com/tutorials/other/automate-your-projects-with-apache-ant/)

_posts/14-01-01-Resources.md

@@ -29,8 +29,7 @@ anchor: resources
 
 * [PagodaBox](https://pagodabox.com/)
 * [AppFog](https://appfog.com/)
-* [Heroku](https://heroku.com)
-  (PHP support is undocumented but based on stable Facebook partnership [link](http://net.tutsplus.com/tutorials/php/quick-tip-deploy-php-to-heroku-in-seconds/))
+* [Heroku](https://devcenter.heroku.com/categories/php)
 * [fortrabbit](http://fortrabbit.com/)
 * [Engine Yard Cloud](https://www.engineyard.com/products/cloud)
 * [Red Hat OpenShift Platform](http://openshift.com)

_posts/14-04-01-Books.md

@@ -7,7 +7,8 @@ anchor: books
 
 There are a lot of books around for PHP but some are sadly now quite old and no
 longer contain accurate information. There are even books published for "PHP 6"
-which does not exist, and might not now ever exist because of those books. 
+which does not exist, and will not now ever exist. The next major version of PHP
+will be named "PHP 7" because of those books.
 
 This section aims to be a living document for recommended books on PHP
 development in general. If you would like your book to be added, send a PR and

_posts/16-01-01-PHPDoc.md

@@ -0,0 +1,63 @@
+---
+anchor: phpdoc
+---
+
+# PHPDoc {#phpdoc}
+
+PHPDoc is an informal standard for commenting PHP code. There are a *lot* of different [tags](http://www.phpdoc.org/docs/latest/references/phpdoc/tags/index.html) available. The full list of tags and examples can be found at the [PHPDoc manual](http://www.phpdoc.org/docs/latest/index.html).
+
+Below is an example of how you might document a class with a few methods;
+
+{% highlight php %}
+<?php
+/**
+ * @author A Name <a.name@example.com>
+ * @link http://www.phpdoc.org/docs/latest/index.html
+ * @package helper
+ */
+class DateTimeHelper
+{
+    /**
+     * @param mixed $anything Anything that we can convert to a \DateTime object
+     *
+     * @return \DateTime
+     * @throws \InvalidArgumentException
+     */
+    public function dateTimeFromAnything($anything)
+    {
+        $type = gettype($anything);
+
+        switch ($type) {
+            // Some code that tries to return a \DateTime object
+        }
+
+        throw new \InvalidArgumentException(
+            "Failed Converting param of type '{$type}' to DateTime object"
+        );
+    }
+
+    /**
+     * @param mixed $date Anything that we can convert to a \DateTime object
+     *
+     * @return void
+     */
+    public function printISO8601Date($date)
+    {
+        echo $this->dateTimeFromAnything($date)->format('c');
+    }
+
+    /**
+     * @param mixed $date Anything that we can convert to a \DateTime object
+     */
+    public function printRFC2822Date($date)
+    {
+        echo $this->dateTimeFromAnything($date)->format('r');
+    }
+}
+{% endhighlight %}
+
+The documentation for the class as a whole firstly has the [@author](http://www.phpdoc.org/docs/latest/references/phpdoc/tags/author.html) tag, this tag is used to document the author of the code and can be repeated for documenting several authors. Secondly is the [@link](http://www.phpdoc.org/docs/latest/references/phpdoc/tags/link.html) tag, used to link to a website indicating a relationship between the website and the code. Thirdly it has the [@package](http://www.phpdoc.org/docs/latest/references/phpdoc/tags/package.html) tag, used to categorize the code.
+
+Inside the class, the first method has an [@param](http://www.phpdoc.org/docs/latest/references/phpdoc/tags/param.html) tag documenting the type, name and description of the parameter being passed to the method. Additionally it has the [@return](http://www.phpdoc.org/docs/latest/references/phpdoc/tags/return.html) and [@throws](http://www.phpdoc.org/docs/latest/references/phpdoc/tags/throws.html) tags for documenting the return type, and any exceptions that could be throw respectively.
+
+The second and third methods are very similar and have a single [@param](http://www.phpdoc.org/docs/latest/references/phpdoc/tags/param.html) tag as did the first method. The import difference between the second and third method is doc block is the inclusion/exclusion of the [@return](http://www.phpdoc.org/docs/latest/references/phpdoc/tags/return.html) tag. `@return void` explicitly informs us that there is no return, historically omitting the `@return void` statement also results in the same (no return) action.

scripts/setup.js

@@ -10,7 +10,7 @@
             dataType: 'jsonp',
             timeout: 3000,
             type: 'GET',
-            url: 'https://api.github.com/repos/codeguy/php-the-right-way/contributors'
+            url: 'https://api.github.com/repos/codeguy/php-the-right-way/contributors?per_page=100'
         }).done(function (data) {
             if ( data.data && data.data.length ) {
                 var $ul = $('<ul></ul>'), dataLength = data.data.length;