Looking for more information on how to do PHP the right way? Check out PHP: The Right Way

CloudWays Blog:
Generate Documentations For PHP Projects Through Sami
Jul 06, 2017 @ 13:47:46

On the CloudWays blog there's a new tutorial posted showing you how to create project documentation with Sami, a tool that takes the DocBlock information already in your code and makes it into something more human-readable.

Developers regularly create large blocks of code that form parts of API’s and other mid to large level projects. While there is a (more or less) agreed upon convention for code writing, every developer has a personal comment and documentation writing standards. Some add small cryptic notes while others attach full-length Google Docs that document the method or class in painful details. This problem becomes very severe when the number of end users increases and there is a need for proper documentation of the project.

[...] DocBlocks are important because they are used by a well known Symfony document generator package called Sami. Very popular in PHP community, Sami also provides the ability to create custom twig templates and work with versioned documentation on GitHub. In this article, I will use Sami and a GitHub project Sync Mysql data with Elasticsearch to automatically generate documentation.

The tutorial then helps you get the Sami package installed via Composer and how to execute it to ensure it's working as expected. Next it points you to a project to clone to help with the MySQL-to-Elasticsearch interface. It then helps with the creation of a configuration file, the results of a build and some additional tips for customizing the configuration for your environment.

tagged: tutorial documentation generation sami docblock install configure theme

Link: https://www.cloudways.com/blog/generate-documentations-for-php-projects-through-sami/

Matthieu Napoli:
Approaching coding style rationally
Nov 13, 2015 @ 11:51:07

In a post to his site Matthieu Napoli shares some of his thoughts about "code style rationality" including code formatting in general and some suggestions on one of the harder things in development - naming things.

Habits are sometimes making us blind. We think X looks prettier than Y but that’s just the habit speaking. In this article I’ll try to take a rational approach at coding style. That means leaving the “it looks ugly/better” at the door.

If at any point you feel like something “just doesn’t look good”, breath in, breath out, and try it! Nothing beats hands-on experience, not even some random article on the internet.

He looks at a few subjects specifically (there's way too many to cover them all in detail):

  • the use of trailing commas
  • alignment of values in docblock comments
  • keeping docblock comments minimal
  • using the "Interface" suffix
  • using the "Exception" suffix

He ends the post by reminding readers that the point is to think about code style logically and that no rules are written in stone.

tagged: code style formatting rational approach opinion comma docblock interface exception

Link: http://mnapoli.fr/approaching-coding-style-rationally/

Acquia Blog:
Quick Tips for Writing Object Oriented Code in PHP
Jul 13, 2015 @ 10:58:14

On the Acquia blog Adam Weingarten has shared some tips for writing good (and modern) object-oriented code in PHP:

Recently I began working on a D8 module, but this isn't a story about a D8 module. The work I did provided me an opportunity to get back to my pre-Drupal object oriented (OO) roots. Writing OO code in PHP presented some curve balls I wasn’t prepared for. Here are some of the issues I encountered:

His tips touch on things like:

  • Using a code structure that can be autoloaded via PSR-4
  • Namespacing your classes
  • Working with types and type hinting
  • Using docblock comments for autocomplete in IDEs

There's also a few other quick topics he finishes the post out with: the lack of enums in PHP, working with associative arrays, no functional overloading and assigning responsibility to classes.

tagged: oop tips objectoriented code modern psr4 namespace typing docblock missing

Link: https://www.acquia.com/blog/quick-tips-for-writing-object-oriented-code-in-php/09/07/2015/3285651

SitePoint PHP Blog:
Getting Started with Symfony2 Route Annotations
Nov 06, 2014 @ 09:27:25

On the SitePoint PHP blog today there's a new tutorial posted that gets into the details on one of the powerful (and most used) components of the Symfony framework, the Router, and how to interact with it via annotations. Symfony's route annotations allow you to define functionality at the controller level or via a YAML configuration file.

When you download the Standard Symfony 2 Distribution, it includes an interesting bundle named SensioFrameworkExtraBundle which implements a lot of great stuff, especially the opportunity to use annotations directly within your controllers. The idea behind this article is not to convice developers to embrace this way of doing, but to point the finger at an alternative method to easily configure controllers. Keep in mind that there is no magic recipe, it depends on what you need in each specific scenario. Symfony 2 implements a strong built-in component to manage all the routes of an application: the Routing Component. Basically, a route maps a URL to a controller action.

His example sets up a simple blog and compares the two ways of configuring the routing: one side putting it all in the YAML configuration and the other in the controller docblocks (annotations) themselves. He adds a base page for showing the listing of posts and a single article route, complete with slugs. He also shows how to add in some additional configuration handling to do things like set default values, making things required and enforcing the HTTP method on the request (GET, POST, PUT, etc)

tagged: route annotations introduction docblock tutorial yaml configuration settings

Link: http://www.sitepoint.com/getting-started-symfony2-route-annotations/

Explore Aspect Oriented Programming with CodeIgniter, Part 3
Aug 24, 2012 @ 11:56:29

PHPMaster.com is back with the third part of their series looking at Aspect Oriented Programming with the CodeIgniter framework. (Part 1, Part 2)

In the previous parts of the series we learned about AOP concepts and the need for using AOP in large scale projects and I introduced CodeIgniter’s hooks as a convenient mechanism for creating AOP functionality from scratch. In this part I’ll show you how to use both XML and comment-based techniques to create custom AOP functionality when a dedicated AOP framework is not available.

They start with the XML configuration that defines a few aspects and pointcuts for the application. This is then read in via the "applyBeforeAspects" and the aspects that should be executed first are extracted, loaded and run. Following this, they take the other approach - based on docblock comments - and pull in the comments (the @before and @after tags) and load/execute the aspects that way instead.

tagged: aop aspectoriented programming tutorial xml docblock configuration


Antonin Januska:
How To Write Code Comments Well
Aug 20, 2012 @ 10:17:42

In this new post Antonin Januska shares some reminders about what good code comments should look like - what needs to go in and what needs to stay out (you comment all your code, right?)

Code organization is a huge thing, especially for developers (because they deal with code), and often times it’s a philosophical debate as to how code should be documented, if spaces should be used instead of tabs, what kind of documentation should be used and so on. Yet, what no one brings up is the dire issue of COMMENTING. We can all agree that comments are essential (and sometimes used to build half-ass documentation on big systems) but what no one really mentions is the fact that people are crappy commenters.

There's two topics he touches on that (surprisingly) it's easy for developers to forget when writing their code - "be informative" and "use consistent formatting". A lot of the issues could be helped if developers made more use of DocBlock formatting which many IDEs already have support for.

tagged: code comments opinion docblock formatting informative


Generate Documentation with ApiGen
Aug 02, 2012 @ 09:44:43

On PHPMaster.com today there's a new tutorial showing you how to generate API documentation with the help of the ApiGen documentation tool and some commenting in your code.

If you’re writing undocumented code, you should stop this very moment. I’m serious. Drop everything, save and quit, and focus on improving this essential part of your workflow. [...] ApiGen is a docblock parser like PhpDocumentor. PhpDocumentor has been around for much longer than ApiGen, but unfortunately its development is somewhat stunted and it lacks in terms of modern documentation and examples.

He shares an example class, fully commented to show off the right way to handle the DocBlocks and goes through each of the "@" types and explains what they're for. Also included are the instructions for getting ApiGen installed (via the PEAR installer) and a sample command to generate the docs from the source. You can find out more about ApiGen and some of its other options on it's main site.

tagged: api documentation tutorial apigen docblock parse tool


Andrew Eddie's Blog:
Making the most out of Code Assist in Eclipse/PDT and Zend Studio for PHP
Dec 01, 2011 @ 12:55:32

Andrew Eddie has posted a helpful tutorial for Eclipse users out there showing how to get the most our of code assist in Eclipse PDT/Zend Studio.

One of the powerful features of an IDE like Eclipse is the ability for it to "read" your code and give you some assistance about your API as you type. This could include things like class property or methods names, constants, functions, argument lists, and so on. Eclipse/PDT and ZendStudio do this by parsing a PHP class directly, but they also look at your docblocks and some other special comments where the raw PHP is not enough. This article is a bag of tricks that help you get the most out of code assistance using Eclipse/PDT or Zend Studio in those awkward corners of your code that you might have through previously inaccessible.

Among his tips are things like adding "@var" declarations to help with code completion, type hinting on methods/functions, using the "@property" annotation and using a "this" trick to override what class the IDE sees as the local object. ,/p>

tagged: eclipse zendstudio ide hint trick docblock annotation codeassist


Tales of a Coder:
DocBlox - Pain Free Documentation
Dec 01, 2011 @ 09:56:27

On the Tales of a Coder blog there's a recent post about DocBlox, an alternative to the usual phpDocumentor for generating automatic documentation, and how it made it "pain free" for her current project.

Want to generate documentation for your PHP project, but keep putting it off? Can't be bothered wading thigh deep in documentation, screaming WHY WON'T IT WORK as you try to set it up? Look no further. DocBlox is pain free and you'll be up and running, literally in a few minutes.

She includes a guide to getting the latest DocBlox installed and configured to work with your project. The configuration is a straight-forward XML file, so changing the settings to match your needs is easy (more on the config here). Once this is configured, building your documentation is one command away. For more details on DocBlox, check out the project's website.

tagged: docblox phpdocumentor painfree documentation docblock tutorial


Karsten Deubert's Blog:
Zend_MVC, Controller Plugins and Annotations
Nov 28, 2011 @ 12:02:50

Karsten Deubert has a recent post to his blog looking at annotations in Zend Framework applications to enhance functionality already in the framework.

Recently I had the idea to influence Controller Actions with annotations but discarded it with thoughts like "In PHP I will have to use reflection and some black magic to get this working which will have insane performance hits for my applications"... until I set everything up to see that it costs just 1-2ms in average per request without any form of caching.

He includes a few bits of code to show a simple annotation example (setting a layout) and the controller plugin that performs the translation. In his case, it's hard-coded to look for the "@layout" annotation in the docblock comment, but it'd be relatively trivial to extend it to a more full-featured version.

tagged: zendframework mvc controller annotations docblock comment plugin