PHP Library Best Practices?

Question

I'm working on a project that I'd eventually like to package as a reusable PHP library. Can anyone suggest some best practices for doing so? Directory structure? File naming conventions? Anything else I might not be thinking of? Or should I just put everything in an appropriately named .php file or two and call it good? Thanks.

Answer 1

Zend, PEAR and ez all have their coding standards.

• PEAR Coding Standard
• Zend Coding Standard
• ez Components Coding Standard

I'd favour PEAR, but the others are not too bad either. Bottom line, use one of them - don't reinvent the wheel.

What I do is this:

//PEAR CS:
class Whatever_Whenver {}
//library/Whatever/Whenever.php

class Whatever_Whenever_Exception {}
//library/Whatever/Whenever/Exception.php

On top of the obvious structural naming convetions, there is a tool called phpcs (PHP_CodeSniffer) to check on idents, tabs vs. spaces, naming conventions, documentation and all that.

Now on many projects we don't stop just there and use what is called continuous integration which involves an automatic test environment to keep track of coding style, unit tests (PHPUnit, xdebug etc. for coverage, etc.) and all that.

For more info on CI you can check out phpUnderControl and xinc.

Answer 2

Hi Brian,

I was looking here today for a similar thing and found this question and answer thread very useful.

There's a good discussion on that thread of not only folder structure, but also coding standards. If you're going to let others hack on your code then using commonly accepted standards is definitely required.

And, to stress the point raised elsewhere, use existing libraries where you can -- make sure you spend the bulk of your coding time on the stuff that makes your project unique.

CakePHP is definitely worth a look if you want to offload that heavy lifting and get something working fast. If you've used MVC stuff before, this will be... cake.

Good luck!

Answer 3

You may seriously want to consider reading the last chapter (and probably all of) Kent Beck's new book Implementation Patterns. The chapter specifically deals with patterns and pitfalls in developing frameworks. Your library, if reusable by others, is essentially a framework. That opens you to a whole host of maintenance issues that you would not have if you were only developing the code for yourself.

The chapter primarily deals with the implementation patterns (go figure) that you need to consider while designing your framework in the first place, but also talks about the issues you face over the long term. Consider versions and backward compatibility; extensibility and flexibility; accepting patches and bug-fixes from third parties. All of these are aspects to making a library publicly available for reuse.

That, and the rest of book is pretty darned awesome to anyone who loves to write software.