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

Zend Framework Blog:
REST Representations for Expressive
Aug 09, 2017 @ 10:12:18

On the Zend Framework blog there's a new post from project lead Matthew Weier O'Phinney covering REST representations in Expressive and the release of two new components to help with their implementation.

We've been working towards our various Apigility on Expressive goals, and have recently published two new components: zend-problem-details and zend-expressive-hal.

These components provide response representations for APIs built with PSR-7 middleware. Specifically, they provide: Problem Details for HTTP APIs (RFC 7807) and Hypertext Application Language (HAL).

These two formats provide both JSON and XML representation options (the latter through a secondary proposal).

The post then goes on to talk about the idea of "representations" and how it relates back to the structure of the data returned and how the user knows what operations they can take on it. He also talks about the differences between normal responses and errors and gives example output helping to illustrate his points. The remainder of the post gets into the details of the two new components, their use and how to implement them in Expressive.

tagged: zendexpressive rest representation data structure response api component tutorial

Link: https://framework.zend.com/blog/2017-08-08-expressive-rest-representations.html

Paul Jones:
Domain Logic and Email Templates
Jul 18, 2017 @ 11:59:50

Paul Jones has a new post on his site sharing some of his thoughts about the placement of domain logic and email templates in an ADR (Action/Domain/Responder) structure. The post is an answer to a recent question he received asking how to organize emails being sent by service classes.

In a way, sending an email as part of a web request/response cycle is like sending two responses: the normal HTTP response, and the email response. With that in mind, it might make sense to think of the HTML + Text email templates as part of a presentation layer. Or, as a combination of infrastructure (the email-sending client) plus presentation (the templates). That would be how to think about the separation of concerns there.

He then provides what he sees as a good directory structure to help keep it all separated out. He also talks about the load sending emails can put on a system, when to move it to workers and how that impacts where the templating of the emails should be done.

tagged: domain logic email template adr actiondomainresponder designpattern structure

Link: http://paul-m-jones.com/archives/6619

SitePoint PHP Blog:
PDS Skeleton by Example: A Standard for File and Folder Structure
May 15, 2017 @ 11:56:29

The SitePoint PHP blog has a tutorial posted by Younes Rafie introducing the php-pds/skelecton package definition and how it can be used to provide some structure and consistency across your package development.

Looking at the Packagist registry, we can see that most packages follow a pattern, with some small changes to fit their needs, while others have a weird folder structure that takes time to get your head around.

This problem has been solved in different ways by different people. Some frameworks have their own recommendations on how to structure your classes and assets, while others have a skeleton that you can use as a starting point. In this article, we’re going to explore the php-pds/skeleton and use it to build a small package as a demonstration.

He then uses a Laravel package example to show the build up of the package structure (based on the pds/skeleton definition). He goes through each portion of the skeleton structure talking about what they should contain:

  • config
  • resources
  • source files
  • tests
  • the "public" directory
  • bin/ folder
  • documentation
  • other files like README and LICENSE documents

He also suggests including a guide to contributing to the package and how to use the "validate" command to be sure this and the other items in the structure are in place.

tagged: pds skeleton package definition structure example tutorial

Link: https://www.sitepoint.com/pds-skeleton-by-example-a-standard-for-file-and-folder-structure/

Fabien Potencier:
Symfony 4: Directory Structure
Apr 11, 2017 @ 11:53:59

Fabien Potencier continues his look at what's coming in the next major release of the Symfony framework (v4) in this new post to his site. In it he talks about changes to the default directory structure that Symfony 4-based applications will use.

Symfony 3 came with a slightly different directory structure than Symfony 2. Symfony 4 will also come with a reworked directory structure. Mostly incremental adjustments to support new features and best practices.

The Symfony 3 directory structure introduced a more standard Unix-like directory structure, with less sub-directories. Symfony 4 keeps going in that direction.

There's six changes he mentions specifically, each with a brief summary of what they'll contain:

  • Tests under tests/
  • Templates under templates/
  • Configuration under etc/
  • Source Code under src/
  • Temporary files under var/
  • Web files under web/

He ends the post with a quick note that, while these will be defaults, all of it is optional and these directories will be created automatically if they don't exist.

tagged: src etc template test structure directory symfony4 var web overview

Link: http://fabien.potencier.org/symfony4-directory-structure.html

Toptal.com:
Maintain Slim PHP MVC Frameworks with a Layered Structure
Apr 07, 2017 @ 11:17:53

The Toptal.com blog has a tutorial posted by Elvira Sheina showing you how to keep a framework project "slim" and manageable in a MVC pattern using a "layered" structure. This structure adds a few extra components to the traditional MVC design to keep functionality cleaner and easier to maintain.

Fat controllers and models: an inevitable problem for most large-scale projects based on MVC frameworks such as Yii and Laravel. The primary thing that fattens controllers and models is the Active Record, a powerful and essential component of such frameworks.

She starts by talking about one of the main issues in MVC applications - "fat" controllers. In this example the controllers contain the bulk of the logic for the application making it difficult to modify and potentially reuse in other places. This is particularly bad when the Active Record pattern is used and the problem of it violating the SRP (Single Responsibility Principle of SOLID development). Instead she promotes the idea of the "layered" design using controllers, a service layer, DTOs, view decorators and a repository layer. She then shows how to implement this kind of structure and tie each of the pieces together with code examples for each piece.

tagged: tutorial mvc framework structure layer dto repository activerecord decorator service

Link: https://www.toptal.com/php/maintain-slim-php-mvc-frameworks-with-a-layered-structure

Esben Petersen:
A modern REST API in Laravel 5 Part 1: Structure
Mar 09, 2017 @ 10:44:56

Esben Petersen has kicked off his series on creating a modern REST framework in Laravel 5 with part one in the series. This first tutorial focuses on the setup of the application using a "folders by component" approach.

Over time when your API grows in size it also grows in complexity. Many moving parts work together in order for it to function. If you do not employ a scaleable structure you will have a hard time maintaining your API. New additions will cause side effects and breakage in other places etc.

It is important to realize in software development no singular structure is the mother of all structures. It is important to build a toolbox of patterns which you can employ given different situations. This article will serve as an opinionated piece on how such a structure could look.

The tutorial covers structure on three different levels (patterns): application flow, project folder structure and resource folder structure. For each level they cover some of the basic concepts involved and share code showing how it could be implemented including controllers, repositories, middleware and fitting it all into a a resource folder structure.

tagged: laravel rest api laravel5 tutorial series part1 structure

Link: http://esbenp.github.io/2016/04/11/modern-rest-api-laravel-part-1/

Nikola Poša:
Testing conventions
Feb 17, 2017 @ 10:31:32

In a new post to his site Nikola Poša has suggested some testing conventions he's worked up over his time in development across projects.

Testing is an essential aspect of development, and test code should be treated the same way with regard to defining and using coding conventions and standards.

This time I would like to share few conventions that I follow when writing unit tests in particular, some of which I adopted only recently.

He breaks it down into three main sections:

  • Structure (file locations and namespacing)
  • Naming (files and testing methods)
  • Arrange-Act-Assert with exceptions and test doubles

Example code is included showing the concepts and implementation of the suggested convention, just to name a few.

tagged: testing convention tutorial structure naming arrange act assert

Link: http://blog.nikolaposa.in.rs/2017/02/13/testing-conventions/

Nikola Poša:
On structuring PHP projects
Jan 17, 2017 @ 10:17:18

Nikola Poša has shared some advice form his own experience on structuring PHP projects and some alternatives to some of the typical structures seen across many packages and applications.

An indispensable part of every programming project is how you structure it, which involves organizing files and sources into directories, naming conventions, and similar. As your application grows, so does the need for structuring it in way that it is easy to manage and maintain.

In most cases, structure of an average PHP-based application is dictated or influenced by the framework that is being used, which is something I'm opposed to. With no intention to be intrusive and without any bias towards specific framework, I'll share with you how I think about organizing my PHP projects.

He starts with a common directory structure seen in a wide range of projects in a framework agnostic way. He mentions the PHP-PDS project that tries to promote this same structure but also provides some alternatives:

  • grouping by archetype
  • grouping by feature
  • splitting out domain and general-purpose code

For each he provides an example of the directory structure and explains the rationale behind it a bit.

tagged: project structure applications grouping archetype feature domain

Link: http://blog.nikolaposa.in.rs/2017/01/16/on-structuring-php-projects/

Stefan Koopmanschap:
Best practices on bundles in Symfony
Dec 29, 2016 @ 10:53:39

Stefan Koopmanschap has a new post to his site sharing some best practices with bundles in Symfony including structure of both the bundle and the application it lives in.

On one of my recent commutes I started listening to the Sound of Symfony podcast. As I had just discovered that one, I decided to listen to their most recent episode, which is on best practices for bundles. I quite disagreed with what was being said in the podcast. I started voicing my disagreement on Twitter but quickly decided that 140 characters is not enough to really explain my disagreement. So here's a blogpost.

He starts by talking about some of the current "best practices" documentation (like this book) and the parts of it he disagrees with. He talks about the use of the AppBundle, the general structure of a Symfony project and the use of bundles to provide better structure to your own code. He covers the placement of you code (your "domain") and the integration of the idea of bounded contexts. He finishes the post with some of his own experience with various frameworks and both good and bad project structures - and how sometimes the default framework structure isn't really what's needed.

tagged: symfony bestpractice bundles structure application opinion soundofsymfony

Link: http://leftontheweb.com/blog/2016/12/29/best-practices-on-bundles-symfony/

Paul Jones:
Package Development Standards: "pds/skeleton" Now Open For Review!
Dec 16, 2016 @ 10:54:14

Paul Jones has a post to his site with a proposal for a standard structure for PHP packages to help provide consistency across the PHP package ecosystem. His proposal - the Package Development Standards initiative - defines the structure of the repository instead of conventions to be used in the package itself (like naming or object structure).

The new pds/skeleton (and the related research) for public review. If you are a package author, you are invited to post your comments and criticisms of the publication as issues on the relevant Github repository.

The pds/skeleton publication describes a set of standard top-level PHP package directories and files. If you are an author of more than three packages on Packagist, chances are you already follow the standard! That’s because PDS initiative researches the PHP package ecosystem to recognize commonly adopted development practices.

He's putting it out there for public review for now until he can get some feedback from the community on the structure and recommendations made. He also recommends going a head and adding "pds/skeleton" to your "require-dev" section to indicate your compliance to the suggestions he's presented.

tagged: package structure repository standard definition opinion composer

Link: http://paul-m-jones.com/archives/6457