PHP – The Future of Packages

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.

bookpage-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.

Posted in Book, PHP | Tagged , , , | 11 Comments


11 Responses to PHP – The Future of Packages

  • # January 18, 2014 at 20:09

    some thoughts:

    I think the judging part will come from several fronts. From companies upholding their own ecosystem for packages with their personal seal. The community mechanism for this is based on know-how. We know who is who if we have been hanging out for long within the community. I know I will not use some bundles, yet if they improve and I notice I will give them a chance. Also that can change. We shouldn’t ban some packages forever because they evolve so constant review must be made. Experience shared. I believe the recommendation button in the now disappearing KnpBundles.com was a powerful feature yet set aside or minimized sometimes. I don’t think we can do much about PHP Classes, I know Lemos is a nice developer and he has been a long time in this. However, PHPClasses I don’t know I just never like the looks of the site, the UIX seems to be a website from the php5.2 era even though if we can do marvelous things with it. Maybe is because there is not a team behind it. I can change my opinion if like you see some more positive points. I still think your harsh opinion on PHPClasses does not lack motifs or justification. But looking back he did write a nice plugin to push composer beyond. So I say the ecosystem just convulses every now and then and it is good.
    Lemos has so much experience and history all my respects to him.

    When bad code exists good code will exist too and our task is to model by example. I say we should focus more on the quality of packagist or encourage higher quality repository guilds while yet being kind to others. We cannot expect everyone to know what we know.

    I also want to say this is the reason why I started to work on #Gush https://github.com/cordoval/gush#gush is that I want to lower and encourage good flows and practices for package design and maintenance. If people grow as good maintainers they will write good packages and there is no other way to write good packages than using a good flow for package design. Which turns me into a request, can I write a chapter on your book about this? :D

    cordoval

    Reply

    • # January 21, 2014 at 10:51

      Cordoval, you are right about PHPClasses UX issues. That is a matter that has been in the development queue to be addressed until it gets its turn. Coincidentally its turn is now. It was planned to be done next. So there is a Design Thinking process going on already. Right now I am doing interviews with people that have used the site. It would be useful if you could participate, as you seem to know what are the UX issues. Therefore, if you are available for a short interview via Skype (less than 30 minutes), please mail me at info at phpclasses.org telling what days and times you would be able to do it.

      Manuel Lemos

      Reply

  • # January 19, 2014 at 20:20

    Thanks Luis for your elaborate reply. By the way, I was trying not to be harsh here. This article is meant as a positive way to look at things which I judged harshly in the not so distant past.

    As for the new Gush tool, it seems to be pretty good and I hereby invite you to write something about it for the appendix of the book. I will ask others to do the same if they want (like Liip).

    Matthias Noback

    Reply

  • # January 21, 2014 at 10:45

    Matthias thank you for your analysis. This is helpful to me to understand how PHPClasses is perceived.

    There are a few misunderstandings, so it is my responsibility to do whatever is needed to avoid that those misunderstandings keep happening. Let me clarify.

    - Notable classes are just classes that do something unusual, not necessarily with high quality code, or even innovative.

    - PHPClasses has no relation with Packagist. PHPClasses and JSClasses have their own Composer repositories. Packages from PHPClasses are downloaded from PHPClasses directly, not from Packagist.

    - Packages can be added to PHPClasses/JSClasses repositories even if they do not have a composer.json file. That is because most metadata that authors provide in composer.json files, is already provided to the sites by other means, like version numbers, dependencies, which are the class files (for classmaps), etc.. If a composer.json file is provided, definitions are merged, including dependencies on external packages.

    - PHPClasses prefixes packages’ base names with phpclasses, to avoid collisions with package names from other repositories, when you you have projects with packages from multiple repositories.

    - Not all packages in PHPClasses are part of PHPClasses Composer repository automatically. At least one user has to request that a package be available from the Composer repository. This way PHPClasses Composer repository is lean, because only packages that Composer users care are there. This avoids the typical long download time overhead that you have to put up with when you request packages from Packagist.

    - Classmaps are only generated if the package does not have its own composer.json file stating to use some other autoloader rules like PSR-0. If the package uses PSR-0, namespaces are applied by composer.

    - Authors do not earn reputation points just for adding a composer.json file. They earn points if their package is made available conscientiously in the PHPClasses Composer repository.

    Other than that, I my opionion, if you start making too much demands on the requirements of a package to be published in a repository, authors give up. That seems somewhat what happened to PEAR.

    Many authors do not upload package files individually because that is a pain. If packages are in public repositories, it is much faster to do it all at once importing from a VCS.

    For the others, the site already tried to educate them regarding the advantages of using a VCS. Still many authors were not yet convinced of doing. That is why PHPClasses rewards those that use them with reputation points.

    http://www.phpclasses.org/blog/post/205-Top-Version-Control-Systems-used-by-PHP-Developers.html

    PHPClasses should never rely on Packagist, nothing against it but if for some reason that site goes down, PHPClasses site users should not get stuck.

    The site already provides means for users to rate the packages they try. That is used in top rated listings to show packages sorted according to they are valued by others.

    Still it is hard to motivate users to rate the packages they try. Most users feel they do not have too. Still PHPClasses gives reviewer reputation points to uses that rate other people stuff.

    Anyway, PHPClasses uses complex anti-spam algorithms to avoid that authors overrate their own packages creating fake accounts.

    For sites that do not even require the users to be logged, like for instance Packagist, taking anonymous rating votes is asking to be spammed by authors that want to get promoted without deserving.

    I like your idea of using tools like scrutinizer to evaluate the code quality. Doing that will be possible in the future in PHPClasses. Still tools like that say nothing about the utility of a package, or even if the examples and documentation are useful enough. That is evaluated by users of PHPClasses when they rate packages.

    PHPClasses never was a place just for beginners. If you evaluate what for instance packages for the innovation award do, you clearly see that great part of the nominated authors are very advanced.

    I understand that some developers that do not know PHPClasses site well still see it as a site for inferior developers. It is their mistake but it is also the image that those developers get from the site. That is why I am focused on eliminating the circumstances that make them get the wrong image.

    Manuel Lemos

    Reply

  • # January 22, 2014 at 15:54

    Thanks, great article, articulates many of the thoughts I’ve had about phpclasses.org. Glad to see a dialog started between you and Manuel.

    BTW, the link to Scrutinizer is broken, it should be https://scrutinizer-ci.com/

    Tac

    Reply

  • Pingback: Matthias Noback: PHP - The Future of Packages | htaccess

  • Pingback: Matthias Noback: PHP - The Future of Packages | facebooklikes

  • Pingback: PHPDeveloper.org: Matthias Noback: PHP - The Future of Packages

  • # January 22, 2014 at 19:31

    Nice article Matthias. I think it’s good to look at the larger gatherings of PHP developers like PHPClasses and ask the community leaders to gently point in the “right” direction. Not to say: “go there!”, but to allow developers to at least know about current best practices.

    That being said, I think the average code quality comparison between PHPClasses and Packagist is impossible. I remember when Google came out as the default search engine in Netscape – and we all went “wow.. look at it.. it’s so shiny and glorious!”. Because there where zero dead links and no spam. Compared to the other search engines the qualityof the results was just incredible.
    But that new car smell didn’t last very long, we all know what it smells like now…

    The point is: Age matters. I think in time there will be unmaintained packages and old crappy code (by tomorrow’s standards, mind you, not today’s) in Packagist. Just like WordPress plugins, Joomla components and Drupal & Magento modules. Agent Smith said it best: “It’s inevitable”. But following your advice, we might postpone the inevitable just long enough ;-)

    Ramon de la Fuente

    Reply

  • # January 25, 2014 at 03:07

    I posted on the mailing list years ago about how poor phpclasses.org was. The design was remnant of 90′s era “I just learned HTML”, the packages were poor quality, and Manuel answered every single mailing list post with “there are packages available at phpclasses.org/something”

    The *idea* behind it was nice, but the execution was poor, and it helped proliferate bad code throughout the ecosystem.

    php classes IS garbage

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

* *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>