Php file structure best practices

When starting out with PHP, it can be daunting figuring out how best to organize a project. If you've ever been confused with where to put your images, external libraries, or keeping your logic separate from your layout, then check out these tips; they'll get you heading in the right direction.

Tutorial Details

• Program: PHP/Projects
• Version: 1
• Difficulty: Easy
• Estimated Completion Time: 20 minutes

Directory Structure

I'd say the number one thing in getting your project up and running quickly is having a solid directory structure you can reuse for multiple projects. If you are using a framework, usually it will provide a structure to use, but in this scenario we're working on a simple site or app.

Breakdown

• You are probably very familiar with the public_html structure. This is the Document Root in which all your public files are accessed (/public_html/page.php is accessed at example.com/page.php).

  • img — All your image files. I decided to split content images from layout images.
  • css — All your css files.
  • js — All your javascript files.

• The resources directory should hold all 3rd party libraries, custom libraries, configs and any other code that acts as a resource in your project.

  • config.php — Main configuration file. Should store site wide settings.
  • library — Central location for all custom and third party libraries.
  • templates — Reusable components that make up your layout.

The Config File

As designers and developers our main goal is to do as little work as possible. One way to reach this goal is with config files. To get a better idea of what the configuration file should have check out this example.

 array(
		"db1" => array(
			"dbname" => "database1",
			"username" => "dbUser",
			"password" => "pa$$",
			"host" => "localhost"
		),
		"db2" => array(
			"dbname" => "database2",
			"username" => "dbUser",
			"password" => "pa$$",
			"host" => "localhost"
		)
	),
	"urls" => array(
		"baseUrl" => "http://example.com"
	),
	"paths" => array(
		"resources" => "/path/to/resources",
		"images" => array(
			"content" => $_SERVER["DOCUMENT_ROOT"] . "/images/content",
			"layout" => $_SERVER["DOCUMENT_ROOT"] . "/images/layout"
		)
	)
);

/*
	I will usually place the following in a bootstrap file or some type of environment
	setup file (code that is run at the start of every page request), but they work 
	just as well in your config file if it's in php (some alternatives to php are xml or ini files).
*/

/*
	Creating constants for heavily used paths makes things a lot easier.
	ex. require_once(LIBRARY_PATH . "Paginator.php")
*/
defined("LIBRARY_PATH")
	or define("LIBRARY_PATH", realpath(dirname(__FILE__) . '/library'));
	
defined("TEMPLATES_PATH")
	or define("TEMPLATES_PATH", realpath(dirname(__FILE__) . '/templates'));

/*
	Error reporting.
*/
ini_set("error_reporting", "true");
error_reporting(E_ALL|E_STRCT);

?>

This is a basic drop-in config file. A multi-dimensional array serves as a flexible structure for accessing various config items such as database credentials.

• db — Store database credentials or other data pertaining to your databases.
• paths — Commonly used paths to various resources for your site.
  • log files
  • upload directories
  • resources
• urls — Storing urls can be really handy when referencing remote resources throughout your site.
• emails — Store debugging or admin emails to use when handling errors or in contact forms.

Using constants for commonly used paths makes include statements (require or include) a breeze, and if the path ever changes you'll only need to update it in one place.

Using Different Config Files For Multiple Environments

By using different config files for multiple environments you can have relevant settings depending on the current environment. Meaning, if you use different database credentials or different paths for each environment, by setting up the respective config files you ensure that your code will work without hassle when updating your live site. This also allows you to have different error reporting settings based on the current environment. Never ever display errors on your live site! Displaying errors on the live site could expose sensitive data to users (such as passwords).

The Layout

Reusable templates are another big time saver. There are some great libraries for templating (such as Smarty), and I always encourage using such a library rather than reinventing the wheel. These libraries offer a lot of functionality (like helper methods for formatting currency and obfuscating email addresses). Since this is a simple site however we don't want to take the time to setup the library and will be using the most basic of basic templates. We achieve this by including common sections or modules in to our site pages; this way if we want to change something in the header, like adding a link to the global navigation, it is propagated throughout the site.

header.php

	
	




	
Simple Site
	

		
Home
		
Articles
		
Portfolio
	

rightPanel.php

	

		
PHP
		
HTML
		
CSS
	
	

		
	

footer.php

	Footer content...

index.php

Let's say that we put all of our layout components (header, footer, rightPanel) in our resources directory under templates.

Taking It Further

While this basic template system gets you off to a great start, you can take it a lot further. For instance, you can create a class or functions that include all the template files and accept a content file as an argument to render within the layout. This way you don't need to keep including the template files in every page of your site, but rather abstract that logic out meaning even less work down the road. I'll show you a quick example.

/resources/library/templateFunctions.php

 0) {
			foreach ($variables as $key => $value) {
				if (strlen($key) > 0) {
					${$key} = $value;
				}
			}
		}
	
		require_once(TEMPLATES_PATH . "/header.php");
	
		echo "
\n"
		   . "\t
\n";
	
		if (file_exists($contentFileFullPath)) {
			require_once($contentFileFullPath);
		} else {
			/*
				If the file isn't found the error can be handled in lots of ways.
				In this case we will just include an error template.
			*/
			require_once(TEMPLATES_PATH . "/error.php");
		}
	
		// close content div
		echo "\t
\n";
	
		require_once(TEMPLATES_PATH . "/rightPanel.php");
	
		// close container div
		echo "
\n";
	
		require_once(TEMPLATES_PATH . "/footer.php");
	}
?>

index.php

This is assuming you have a file called home.php in your templates directory that acts as a content template.

 $setInIndexDotPhp
	);
	
	renderLayoutWithContentFile("home.php", $variables);

?>

home.php

Home Page

Benefits of This Method Include:

• Greater separation of logic and view (php and html). Separating concerns like this makes for cleaner code, and the job of the designer or developer becomes easier as they are mostly working with their respective code.

• Encapsulating the template logic into a function allows you to make changes to how the template renders without updating it on each page of your site.

Symlinks

On Unix based systems (os x, linux) there is a neat little feature called symlinks (Symbolic Links). Symlinks are references to actual directories or files on the filesystem. This is really great for when you have a shared resource, such as a library used between multiple projects. Here are a few concrete things you can do with symlinks:

• Have two versions of your resource directory. When updating your live server you can upload your latest files into an arbitrary directory. Simply point the symlink to this new directory instantly updating your code base. If something goes wrong you can instantly rollback to the previous (working) directory.

• Shared resources are easily managed with symlinks. Say you have a custom library you've been working on, any updates to the library you make in one project will be immediately available in another.

Using Symlinks

Symlinks vs Hardlinks

Symlinks, or softlinks, act as references to full paths on the filesystem. You can use symlinks in multiple locations and the filesystem treats them as if they were the actual file or directory they reference. Hardlinks on the other hand are pointers to a file on the disk (think shortcuts in windows); they take you to the actual location of the file.

There are a few things you should consider when using symlinks. Your server configuration must be set up to follow symlinks. For Apache this is done in the httpd.conf file. Find the Directory block and make sure that Options FollowSymLinks is there. If not add it and then restart Apache.

	Options FollowSymLinks
	AllowOverride None

Creating Symlinks in OS X

There are 2 ways to create symlinks in OS X:

• Via the command line, navigate (cd, change directory) to the directory in which you want the symlink to be created, then use the following command:

  $: ln -s /path/to/actual/dir targetDir

  So if our custom library lives in ~/Sites/libraries/myCustomLibrary we'd cd to where we want to use that library cd ~/Sites/mySite/resources/library and enter:

  $: ln -s ~/Sites/libraries/myCustomLibrary myCustomLibrary

  Note that this method should work in all Unix based operating systems.

• The alternative is through the finder. By holding alt + cmd while clicking and dragging a file, a Symlink (or alias in os x) that points to the file is created.

Creating Symlinks in Windows

To accomplish this in windows you'll need to use the mklink command in the command prompt:

C:\mklink /D C:\libraries\myCustomLibrary C:\Users\derek\Sites\mySite\resources\library\myCustomLibrary

Summary

These tips are meant for beginners or those creating simple sites or applications. Ideally for larger applications or sites, you'll want to consider something more advanced like the MVC architecture and Object Oriented programming. I encourage you to look into these once you've gotten your feet wet and feel that you've outgrown most of the steps above. I decided not to cover source control as it's a pretty large subject on its own, but these tips should help you in organizing your files for easier source control if desired (hint: store stuff like layout images in your resource directory and symlink it into your /public_html/img dir). Definitely look in to using source control, like subversion or git for all of your projects.

Hope you find these tips helpful when starting your next PHP Project. Thanks!

Resources

• Smarty Templating Engine
• Multitier Architecture
• MVC
• Object Oriented Programming
• Subversion For Designers (version control)
• Symlinks
• Hardlinks

• Follow us on Twitter, or subscribe to the NETTUTS RSS Feed for more daily web development tuts and articles.

Did you find this post useful?

Boston based web developer whom primarily lives in PHP, but breaks things in Objective-C from time to time. Loves working with front-end technologies such as HTML, CSS and Javascript. Feel free to follow me on twitter or check out my blog.

What is the best practice PHP?

What is PHP file structure?

Why is PHP so fast?

What are the coding standards in PHP?