Skip to main content

Quality Assurance on PHP projects - PHPDocumentor feedback

First of all, thank you all for the enormous feedback I got on my latest article on documentation of code. I got a lot of comments on the usage of PHPDocumentor for the following reasons:
  • the project seems to be no longer maintained
  • it's not ready for php 5.3
  • it uses too much resources when using it on big projects
I have to agree that these reasons are valid enough to step away from PHPDocumentor as a tool for documentation purposes and look for a better alternative. So I've investigated one tool most people have commented on or tweet-ed/facebook-ed/g+-ed on: DocBlox.

Before I start a flamewar, I'm all for investigating more tools as time permits me, but these are my first impressions on the tool that had the most buzz in my personal social zone. If your tool of preference is not listed here, write an article on it and put the link here in the comments (or ping back to this article in your own post).

DocBlox seems to be the youngest project of all the various projects suggested to me, but gets a lot of support from major players in the field of PHP and is supported by my favorite build tool Phing (a tool I'll describe in detail in another article).

Installation
You can simply use PEAR to install DocBlox.

user@server $: pear channel-discover pear.docblox-project.org
user@server $: pear channel-discover pear.michelf.com

Select a package you need, in this case docblox/DocBlox-0.12.1 as the project is still in beta (when writing this article) and version DocBlox-0.12.2 has some issues

user@server $: pear install -a docblox/DocBlox-0.12.1

Usage
DocBlox is pretty simple in it's usage and works indeed better than PHPDocumentor, although I had to contact the project lead Mike van Riel (@mvriel) regarding a dependency error on Zend Framework, but it should be fixed now or any time soon.

My dear friend Matthew Weier O'Phinney (@weierophinney) had taken up my challenge to write an article about the usage of DocBlox and I have to say, it's a very good introduction that allowed me to use it immediately.

As a result, I was able to test-run both PHPDocumentor and DocBlox using Phing resulting in a small win for DocBlox. I haven't made a true benchmark test including memory consumption, cpu usage but I think that someone with more sysadmin background knowledge can easily set it up to give a more in-depth detail on which tool performs the best.



Comments

  1. Has anyone had this working with Mac OSX Lion? I've installed it as per the instructions above (except with 0.13.0 rather than 0.12.1) and get the following error:
    PHP Warning: require_once(markdown.php): failed to open stream: No such file or directory in /usr/lib/php/DocBlox/src/DocBlox/Core/Application.php on line 35

    Any help would be massively appreciated.

    ReplyDelete
  2. @Gavin, if you're using the PHP version bundled with OS X, you may need to add PEAR's directory to your include path in /etc/php.ini. This is what mine looks like - I was having a similar error just trying to get phing to work.

    include_path = ".:/usr/lib/php:/usr/local/share/pear/PEAR";

    ReplyDelete
  3. I have spoken to Gavin via Twitter; problem was indeed a missing include path.

    ReplyDelete
  4. The dependency was fixed in version 0.13.0

    See: http://www.docblox-project.org/2011/08/release-of-v0-13-0/

    Nice work, though.

    ReplyDelete

Post a Comment

Popular posts from this blog

PHP 7 and Apache on macOS Sierra

I posted several talks about compiling PHP from source, but everyone was trying to convince me that a package manager like Homebrew was a more convenient way to install. The purpose of Homebrew is simple: a package manager for macOS that will allow you to set up and install common packages easily and allows you to update frequently using simple commands. I used a clean installation of macOS Sierra to ensure all steps could be recorded and tested. In most cases you already have done work on your Mac, so chances are you can skip a few steps in this tutorial. APACHE AND PHP WITH HOMEBREW I’ve made this according to the installation instructions given on GetGrav. The installation procedures These installation procedures will set up your macOS Sierra with PHP 7.1 and Apache 2.4. Install Xcode command line tools (if not done yet)xcode-select --install Install Homebrew/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" Set up for in…

Sessions in PHP 7.1 and Redis

In case you have missed it, PHP 7.1.0 has been released recently. Now you can’t wait to upgrade your servers to the latest and greatest PHP version ever. But hold that thought a second… With PHP 7 lots of things have changed underneath the hood. But these changed features can also put unexpected challenges on your path. Our challenge One of these challenges that we faced was getting PHP 7.1 to play nice storing sessions in our Redis storage. In order to store sessions in Redis, we needed to install the Redis PHP extension that not only provides PHP functions for Redis, but also installs the PHP session handler for Redis. Because we upgraded our servers to PHP 7.1, we were looking to use the latest provided version for this Redis extension: redis-3.1.0. Once installed, we bumped against a nasty problem. Warning: session_start(): Failed to read session data: redis (path: tcp://127.0.0.1:6379) Searching the internet for this error, we didn’t got many hits that could point us into a dire…

Speeding up database calls with PDO and iterators

When you review lots of code, you often wonder why things were written the way they were. Especially when making expensive calls to a database, I still see things that could and should be improved.
No framework development When working with a framework, mostly these database calls are optimized for the developer and abstract the complex logic to improve and optimize the retrieval and usage of data. But then developers need to build something without a framework and end up using the basics of PHP in a sub-optimal way.

$pdo = new \PDO( $config['db']['dsn'], $config['db']['username'], $config['db']['password'] ); $sql = 'SELECT * FROM `gen_contact` ORDER BY `contact_modified` DESC'; $stmt = $pdo->prepare($sql); $stmt->execute(); $data = $stmt->fetchAll(\PDO::FETCH_OBJ); echo 'Getting the contacts that changed the last 3 months' . PHP_EOL; foreach ($data as $row) { $dt = new \DateTime('2015-04-…