codeguy / php-the-right-way

An easy-to-read, quick reference for PHP best practices, accepted coding standards, and links to authoritative tutorials around the Web

PHP: The Right Way

Overview

This is the GitHub Pages repository for the PHP: The Right Way project.

• This website is a Jekyll project.
• Each section and sub-section are a Markdown file in _posts/.
• Sub-sections have isChild: true in their front matter.
• The navigation and page structure are automatically generated.

Spread the Word!

PHP: The Right Way has web banner images you can use on your website. Show your support, and let new PHP developers know where to find good information!

See Banner Images

How to Contribute

You should read the CONTRIBUTING.md file for precise instructions and tips. But, if you prefer a TL;DR:

1. Fork and edit
2. Optionally install Ruby with Jekyll gem to preview locally
3. Submit pull request for consideration

Contributor Style Guide

1. Use American English spelling (primary English repo only).
2. Use four (4) spaces to indent text; do not use tabs.
3. Wrap all text to 120 characters.
4. Code samples should adhere to PSR-1 or higher.

Where

https://www.phptherightway.com

• English
• Español
• Français
• Indonesia
• Italiano
• Polski
• Português do Brasil
• Română
• Slovenščina
• Srpski
• Türkçe
• български
• Русский язык
• Українська
• العربية
• فارسى
• ภาษาไทย
• 한국어판
• 日本語
• 简体中文
• 繁體中文

Translations

If you are interested in translating PHP: The Right Way, fork this repo on GitHub and publish your localized fork to your own GitHub Pages account. We'll link to your translation from the primary document.

To avoid fragmentation and reader confusion, please choose one of these options:

1. We link to your GitHub Pages fork with [username].github.io/php-the-right-way
2. We link to your GitHub Pages fork with a subdomain (e.g. "ru.phptherightway.com")

If you use a subdomain, enter the subdomain into the CNAME file, and ask us to setup DNS for you. If you do not use a subdomain, remove the CNAME file entirely else your fork will not build when pushed.

Add information about your translation in the wiki page.

When your translation is ready, open an issue on the Issue Tracker to let us know.

Why

There's been a lot of discussion lately about how the PHP community lacks sufficient, credible information for programmers new to PHP. This repository aims to solve this problem.

Who

My name is Josh Lockhart. I'm the author of the Slim Framework, and I work for New Media Campaigns.

Collaborators

• Kris Jordan
• Phil Sturgeon

License

Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License

php-the-right-way's Issues

Polish translation

Hi,

Polish translation is ready. It is available at http://pl.phptherightway.com. Please link it to the main document.

Bartosz

Chinese translation

Hi, I have translated this site at http://wulijun.github.com/php-the-right-way, could you please add a link at the primary docment?

Errors vs Exceptions

Something that comes up in all of the bash PHP sites is : "PHP errors and PHP exceptions are completely different beasts. They don’t seem to interact at all."

A somewhat growing standard practice is to have an error handler that creates and throws an ErrorException so that all errors and exceptions can be globally handled in the exception handler. The messaging is that they are different "beasts" but can easily interact and roll up to one location.

Firstly, do you think this is necessary?

If so, I am not sure where in the document this should go. I see the section on "Coding Practices->Exceptions" and "Security->Error Reporting" and not sure if it fits with either. I guess more so with the first exceptions section but maybe in "Coding Practices->Handling Errors and Exceptions" ?!?

PHP Fog is closing soon

Platform as a Service (PaaS) section

phpfog will be replaced by appfog, which support multiple languages

Where to store diagrams, screenshots or other images?

I am writing a content page on Debugging and profiling PHP code. When I complete the content page I will create a summary for the main page.

In the content page I would like to add a kcachegrind viewer screenshot showing flat profile and a call graph. It is not about the program itself, but for better describing how call graph looks like.

Where should I store these images?

Polish translation

Hello,

I started making a polish translation of the document. You can add a "coming soon" statement. I wish to make it available within couple of days.

Low-contrast text is harder to read

Your site is full of good advice that is made harder to read because the prose in written in grey colour on a light background. Some may think this looks nice but in fact when you have long paragraphs of text to read, readability should matter more than visual design fashion. Please change the main prose into a black typeface.

For some inspiration, you may look at this site: http://contrastrebellion.com/

Unfortunately I have no time to make the change myself, but I hope you will take this as an opportunity to make your site even better and more accessible.

filter_input should not be nessesary for PDO

As per PDO documentation it should not be nessesary to use filter_input to protect applications against SQL injection attacks when using prepared statements. It should be safe to use PDO only.

For mysql_query (or whatever it is called for other databases) it still needs to be called on input parameters.

Spanish translation now available

I've forked and translated the website into Spanish. It took me a few days but now you can find it at

http://ederweber.github.com/php-the-right-way/

I've taken care of changing all the links that point to the PHP documentation and making sure they point to the Spanish translation. The extra pages on Functional Programming and Design Patterns have not been translated but I'll get to those soon. Also, I'll try to find an alternative to all the external resources that are only available in English, although I may just have to translate them myself with the authors' permission and put them in a external resources folder or the wiki.

Any and all suggestions and constructive criticism are welcome, thanks!

[Localize] Russian

@butteff Thanks for volunteering to localize into Russian. For localizations, we will link to your fork running on GitHub Pages. To avoid fragmentation and user confusion, I want to either 1) link to [username].github.com/php-the-right-way, or 2) point [language].phptherightway.com to your fork on GitHub Pages.

Feel free to fork and make edits as necessary. You'll want to make sure you continue to pull in and translate changes on a regular basis. Right now, we're iterating quickly.

Section about IDEs ?

As far as I agree that there's no right way to use an IDE, I think that question about "the best (free) IDE" is asked far too often.
What about a section with free (or best) IDEs simply compared? Would you like me to write a section about this ?

Links to Bulgarian translation and DNS record

I made a pull request 4 days ago, but I guess I had to make an issue.

No longer seeing nav highlighting

What happened to the navigation highlighting that occurred while scrolling?

I've tried it in several browsers and it seems to be missing. I don't see any javascript errors.

Addition to the 'People to Follow' list

I think that at least two quite important voices in the PHP world are missing from that list.

• Pádraic Brady, Twitter: @padraicb
• Anthony Ferrara, Twitter: ‏@ircmaxell

Both have very insightful blogs going and are submitting important RFCs to PHP.

mysql_* removed in PHP 5.5.0?

I'm just wondering if there's any source for the mysql_* extension being removed in PHP 5.5.0? With docs on choosing a MySQL API stating 'Long term deprecation announced' is the next major version really going to remove this extension? If it is a source should be provided. If it isn't I believe the wording on why not to use mysql_* should be changed to reflect real reasons to use a better API instead of something that may or may not happen.

The exact wording I am referring to can be found at https://github.com/codeguy/php-the-right-way/blob/gh-pages/_posts/06-01-01-Databases.md and is the last paragraph in the introduction on Databases.

Otherwise I like where you're going with the site and hope that it can lead new/existing PHP developers to the right reference materials and information.

Functional programming deserves a better example

See here for in-line comment: 384345f#commitcomment-1560821

Proper setup of a MySQL connection using PDO

Considering the fact that there are still many people using MyQL as database engine wouldn't it be worth mentioning the correct way of setting up a PDO connection using MySQL as engine?

I.e.: setting of encoding, disabling of emulated prepared statements...?

Common pitfalls/User tips - Yay or Nay

With the aim being to instill best practices, I think it would be beneficial to include a common pitfalls or user tips section. However, I would like to gauge others opinions first.

I'm sure everyone will have their own opinions, but I've included a few examples of common issues that I've found in beginners/novice code.

Examples:

Comparison operators:

One common pitfall of beginners is not fully understanding comparison operators, which can lead to misfortune when using strict comparison functions (there are warnings in the docs, but it's often overlooked).

<?php
$a = 5;   // 5 as an integer

var_dump($a == 5);    // returns true
var_dump($a == '5');  // ignores type and returns true
var_dump($a === 5);   // compares type/value (integer vs integer) and returns true
var_dump($a === '5'); // compares type/value (integer vs string) and returns false

/**
 * Strict comparisons
 */
$str = strpos('testing', 'test');
var_dump($str); // returns (int) 0

if ($str) // $str (0) is interpreted as false

if ($str !== false) // true, as strict comparison was made

String types:

I propose informing users to the benefits of each and when they should be used... I won't go in depth, but here's a short overview:

• Single quotes aren't parsed (quicker)
• Double quotes can host escaped characters and can evaluate variables
• Heredoc vs Nowdoc (same as single vs double)

<?php
'How are you today?';  // simple string, no need to parse
"I'm $mood today";     // using double quotes avoided escaping and concatenating

Lines should be concatenated when exceeding the soft line limit (80/120 characters):

<?php
'Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.';

'Lorem ipsum dolor sit amet, consectetur adipisicing elit,'
    . ' sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.';

Unneeded "else":

I often see "else" included in every conditional argument, however in a lot of cases "else" is unneeded:

<?php
function test($a)
{
    if ($a) {
        return true;
    } else {
        return false;
    }
}

function test($a)
{
    if ($a) {
        return true;
    }
    return false;
}

Ternary operators:

I'm a huge fan of ternary operators, but I've come across a few users who've used them in excess causing code to become harder to read.

<?php
// okay
$a = 5;
echo ($a == 5) ? 'yay' : 'nay';

// excessive
$b = 10;
echo ($a) ? ($a == 5) ? 'yay' : 'nay' : ($b == 10) ? 'excessive' : ':(';

Not viewable on mobile

Currently the new menu overlaps the content when viewing on an iPhone. The viewport should be taken into consideration or optionally hidden.

Remove frameworks, replace with component libraries

@philsturgeon Thoughts? I've been second-guessing frameworks since I added them. I think they're tangential at best. Re-usable component libraries (Symfony Components, Packagist packages, etc.) would better serve our audience without the polarizing and popularity-contest side-effects.

Interest in PaaS Deployment Articles?

I'm curious if anyone would be interested in me creating a section on deploying PHP to Windows Azure via Windows and Mac/Linux.

Would that be of value to anyone?

Brazilian portuguese translation

I have altered the CNAME to br.phptherightway.com. Here's the repository:

https://github.com/klaussilveira/php-the-right-way

Include link to pt-br translation

The translation into pt-br (Brazilian Portuguese) is almost finished, it has been headed by @klaussilveira

Anyway, in my opinion it is already ready to be listed here in official repo, what do you think?

Remove frameworks that do not do PHP the right way

This may be controversial. But if think a framework should not be on the list eg if it does not use name spaces.

translation of the document

we are translating all the content in Italian.

Do you prefer
_includes\translations\section.md
or
_\includes\section.it_IT.md

[Idea] Encourage website promotion

Hi,

The website is a great step to improve PHP code out there.
Reminds me of http://promotejs.com/ as a movement to help removing bad information.
What about doing something similar, having a nice banner and an embed code, so people may link to the website in their blogs and websites, helping the promotion and google indexing.
Maybe a "Promote" topic in the introduction?

xdebug

Using xdebug is the right way for php? Couldn't find a single word about this in the article.

Point people to User Groups

I think its useful to mention in the resources area or maybe a shot community paragraph, that these and more best practices are usually showcased in the various UG meetings and conferences around the world.

We do not yet have a central repository for that, but we can always point them to the few key resources.

Do you guys think this fits into the website?

Site forces www.

www is old school stuff: http://no-www.org/verify.php?u=phptherightway.com&retest=1

Menu links are broken on banners.html

Simple mistake, somebody fix it. The links need to start with /# to bring the user back to the main page's appropriate anchor.

I am having no luck forking this project on Github - every one of them is giving me read-only access, contrary to what the page says. Am I missing something, by chance?

Adding a Component Library section

Re-usable component libraries (Symfony Components, Packagist packages, etc.) would better serve our audience without the polarizing and popularity-contest side-effects.

Design proposal for topic pages

As for Issue #67 and others to follow there is a need for having more content on a specific topic, published as bonus pages. Some layout adjustments are required for those inner pages. For one, I would like to make it easy to recognize that it is a inner page, and also to make it easy to go back to the main page.

This is a quick mockup done in Web Inspector.

I was thinking about adding breadcrumbs, but some pages may be linked from different sections breaking the breadcrumbs flow.

Unicode and Multibyte String Functions

What can you say about Unicode and multibyte string functions?
I suppose it is an important part of core php skills.

started to work on romanian translation

just so you know! :)

[suggestion] Add SolarPHP to framework list

pmjones (author of PHP fig-standards and all-round PHP whizz) has written a very done-the-right-way framework called SolarPHP ( http://solarphp.com/ ) which I think deserves a link.

Convert to Jekyll

Jekyll is a ruby static site manager. You might have noticed how a bunch of "programmer" snobs have the same layout, and thats because they use Octopress and don't know any css/html.

In any case, Jekyll allows you to organize content as markdown, then allows you to build the pages based on some generic layout. The engine is ruby, but that doesn't really matter much - there are other static site generators in PHP, but a language is a language.

To convert, we would need to extract your page's layout into a standalone layout which can include Liquid formatting (liquid is like twig). Then we convert your content into markdown and we are done.

The benefit here is that most people know markdown, and it's much easier to write markdown in the github editor than it is html, allowing quick edits/forks by others interested in contributing.

In any case, I have been working on my own jekyll distribution, which would allow us to just extract your theme, css, and text into the sum of their parts, and then my distro has helper functions to build the page etc. We can use it if you'd like, or just roll your own.

Thoughts?

Include Exceptions as a topic?

Maybe worth considering, Exceptions are a very worthwhile but misunderstood and underused part of PHP. Many beginners and some lagging old-timers don't know about them, I've even had question the question "but it throws an exception, how could I work with it after it shuts down my app?!" (not understanding they can be caught).

CLI example must used non-zero exit code

If something fails on the CLI, it must use an non-zero exit code. Just calling die() is no valid option. The following example:

if($argc != 2) {
    die("Usage: php hello.php [name].\n");
}

Should there become something like:

if($argc != 2) {
    echo "Usage: php hello.php [name].\n";
    exit(64);
}

One might want to re-use common exit codes: http://www.gsp.com/cgi-bin/man.cgi?section=3&topic=sysexits

Broken link Windows setup

The link "download the binaries" is an anchor and it should be an external link.

File to fix : php-the-right-way / _posts / 01-05-01-Windows-Setup.md

Original markup :
download the binaries
Parenthesis are making anchor at compilation.

Should be :
[download the binaries][php-downloads]
With square brackets.

Sorry but I cannot fork this project twice and I am currently working on the french translation.

Migrate Laravel to full-stack list

Based on user feedback.

Using regional domains in reference

While reading(and translating) the manual, I meet a lot of links to regional resources, which may complicate the understanding of reference. My opinion, that we should use only international subdomain if it exists, for best understanding of reference and for facilate translation to other languages.
An example : mysql: http://uk.php.net/mysql
Here : https://github.com/codeguy/php-the-right-way/blob/gh-pages/_posts/06-01-01-Databases.md
In my opinion, that should be, like:

That different, will give a chance php.net redirect everyone who reads reference to his regional domain with translation, if it exists.

PT-BR translation

Hello,
I've seen somewhere in the repository that the portuguese translation is coming soon.
Is it the one from Portugal or from Brazil? If it's not the brazilian one, I want to translate it.

Thanks in advance, and sorry for my english.

Japanese translation

I started Japanese translation at https://github.com/m-takagi/php-the-right-way
and set CNAME to ja.phptherightway.com

Could you please setup DNS ?

Short tags and ternary

As a beginner I have no idea if I can, cannot, should or should not use short tags. What about few words on this topic as it's always enabled since 5.4 ?
The same problem is with ternary operator, beginners very often write code like:

if ($user->isValidated()){ return 'ok'; }else{ return 'wrong'; }
instead of
return $user->isValidated() ? 'ok' : 'wrong';

*Maybe we could create a section like "Common eginner mistakes" ?

Set default branch to gh-pages

We should move the default branch to gh-pages so that contributing to this repo is easier from a non-github user's perspective. Could also move all the files in master branch to the gh-pages branch as appropriate.

Fix Packagist link

Missing link in paragraph body.

Add a note about using opcode cache like APC

Definitely needs some attention.
Easy to install/setup and greatly increase application speed, yet not many people use it even today..

Link to PSR-0

When you write about namespaces and Composer, please link to the PSR-0 standard for namespaces. That's the standard, that is supported by Composer autoloader.

Link: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md

Unused links (namespaces and overloading) in programming paradigms

In meta programming chapter (
https://raw.github.com/codeguy/php-the-right-way/gh-pages/_posts/03-02-01-Programming-Paradigms.md), two links are unused :

• namespaces : http://php.net/manual/en/language.namespaces.php
• overloading : http://php.net/manual/en/language.oop5.overloading.php

But namspaces link is used in the next section (ie : Namespaces https://github.com/codeguy/php-the-right-way/blob/gh-pages/_posts/03-03-01-Namespaces.md).

Date and Time small bug

[datetime]: http://www.php.net/manual/language.exceptions.php should be http://www.php.net/manual/class.datetime.php