PHP - The Future of Packages

Matthias Noback

Recently I tweeted about phpclasses.org. It was not such a friendly statement:

Why does phpclasses.org still exist? Most of the “packages” contain dangerous, stupid or useless code.

Manuel Lemos, the man behind PHP Classes, made me pull back a bit by pointing out that I was generalizing and that they do what they can to encourage people to do a good job. I recognize their effort. And of course, there is also good code on phpclasses.org.

With this article I’d like to push things a bit further. I want to propose a different role for a community site like PHP Classes. And I also want to outline some steps that Packagist should take to become a better package repository.

PHP Classes

As I already mentioned, I was generalizing a fair bit about PHP Classes. I also had not closely followed any changes made to the platform by its maintainers. So my initial statement was not specific enough, and also not as polite as I usually am. A little explanation from my side would be appropriate.

When I just started as a developer, I regularly visited phpclasses.org to find something suitable for the task at hand. I’m not sure if I ever used something from it in a project. I do know that later in my career I never came back, except when reading the regularly published “Latest Releases from PHPClasses.org” news at phpdeveloper.org. It has been out of sheer curiosity that I skimmed through the new releases and many times I went to the site to inspect the code of the recently released classes.

Almost every week phpclasses.org got a new YAMW - Yet Another MySQL Wrapper. Each of them as bad as the others. But other classes, even the “notable” ones, contained badly designed code. When you ask me: what is the reason for a PHP developer to write classes? I answer: in order to separate responsibilities and hide data. Many principles have been devised to help developers fulfilling these tasks. But in most cases there was no sign of these principles underlying the code on phpclasses.org.

This is why many people have turned their back on phpclasses.org. I was about to do the same. But in response to my tweet some people, including Manuel Lemos, responded that everybody needs a place to learn and try. Yes, of course, when I started working with PHP, I did not apply any of the SOLID principles to my coding, and I’d never heard about clean coding practices. At that point in time I did not dare to share my code with the world. Manuel says that phpclasses.org is the place where even beginners can share their code. That is, I guess, why so much code is procedural code, put inside a class. It also explains why classes often have no identifiable responsibility.

Recently I became interested in phpclasses.org again and I learned a few things:

  • You still need to be registered to take a look at or download the PHP files. This way you can be notified when the owner of a PHP class updates his code.

  • You can have a composer.json file. PHP Classes then registers your package on packagist.org, but under its own vendor namespace, “phpclasses”.

  • You can let PHP Classes create a composer.json file for you. It scans the PHP files and generates a class map for the Composer autoloader.

  • Namespaces are seldomly used.

  • Users don’t need to upload files anymore, they can also point to a Git/SVN/… repository and PHP Classes will then copy each file to their own repository.

Many people who work with Composer and Packagist every day already have a gut feeling that this is wrong. Please note however that the people from PHP Classes are doing their best to encourage these best practices from the “new age of PHP”. You can earn points for using a repository instead of uploading files by hand, or for using namespaces, or for adding a composer.json.

What PHP Classes should be

Using such a system to award points to packages is a great idea already. But I think in order to be a real learning platform for PHP developers, users should not only be encouraged to follow a (the?) standard. It should not even be possible to do anything else. Uploading package files by hand should definitely not be possible at all. It’s good that PHP Classes offers a way to link to a version control repository, but it should not copy all the files to its own repository. It should also force users to provide a composer.json file and make them responsible for defining their package’s dependencies. PHP Classes should not register packages under their own namespace. It should leave that to the users. They should learn how to do such a thing themselves (and it’s very easy).

When all the best practices are somewhat enforced by the platform itself, developers will learn best practices not by struggling with other ways, but by seeing how easy it really is to do the right thing. But there is much more that PHP Classes could do to make it a real learning platform. It should provide code review tools, and it should encourage more experienced users to review code of users who just start.

Also, packages on phpclasses.org should never be pushed to packagist.org. Packagist should be a place for package maintainers who master package management and take responsibility for every aspect of their packages, instead of relying on built-in features of PHP Classes.

Even more specific: it should not be possible at all to reuse code that is published on phpclasses.org. If code has been inspected by PHP Classes community members and has been found suitable for reuse (according to class and package design principles, see below), the owner of the code should manually publish his package on packagist.org.

Packages on packagist.org

My major criticism so far has been focused towards the way PHP Classes currently tries to create a bridge between the world of Composer and Packagist, and the world of people who upload PHP files by hand. But there are some things that have to change with regard to Packagist too. It is time to raise the bar for packages on packagist.org.

I am under the impression that the quality of packages on phpclasses.org is much worse than of packages on packagist.org. This is only a prejudice of course, I can’t know this for sure. packagist.org contains bad packages with bad code too. However, we currently have no structural way to know this beforehand. If you are an unexperienced developer, the only thing you can do to make a judgement about the quality of a package is to take a look at the number of downloads.

To judge a package by the number of downloads is not a good idea, since good packages are often downloaded many times, but there are also a lot of bad packages that have been downloaded very often. Maybe the people who downloaded them came to their senses before its code reached production servers, but still: the statistics say it is very popular.

Besides, the number of downloads is a somewhat fuzzy number. It increases for each install, which includes upgrades to a new version as well as installs done by continuous integration services.

Judging the quality of packages

So we need a better way to make judgements about the quality of packages. We need to be able to look at a package on packagist.org and it should at once give us feedback about its code quality, its documentation, extensibility, ease of use, etc. One step in the right direction would be to automatically let each PHP package be analyzed by Scrutinizer CI. This would already give a great impression of a package’s internal quality.

Another important step we should take is write down the principles of package design. This would allow us to take a package, inspect it, compare its contents to the principles and see if it follows them, or if it violates them in any way.

If there is one thing I learned recently by discussing package design on Twitter, the way package maintainers are used to doing things, is not the way things should ideally be done. Of course nothing is ideal about this world, but there is still a lot to improve when it comes to packages.

Cover of Principles of PHP Package Design

This is why I started to write my second book Principles of PHP Package Design. It contains an elaborate discussion of principles related to package and PHP class design. I think it can be used as part of the effort to make packages better, on packagist.org as well as on phpclasses.org.

I think it is possible to validate part of the package design principles by some kind of static analysis tool. However, some real people are still needed to take a look at each package, try it, and add their judgement to the package’s page on packagist.org. I think the real practical difficulty lies here and I would like to hear from you, if you have any suggestions for this.

Conclusion

I would really like PHP Classes to be a community for beginning PHP developers, who can learn to write code, receive comments and suggestions about the code they wrote, and earn points for following good practices. And I would like Packagist to automatically create and show quality reports and ratings for all its (PHP) packages. It would also be great if packages on Packagist could be judged by real developers.