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

Paul Jones:
Semantic Versioning and Public Interfaces
Jun 03, 2015 @ 09:16:33

Paul Jones has an interesting post to his site that makes the link between software versioning and public interfaces your code provides. He points out that, despite semantic versioning helping to define how to version your code, there's still some ambiguity about it and backwards compatibility.

Adherence to Semantic Versioning is just The Right Thing To Do, but it turns out you have to be extra-careful when modifying public interfaces to maintain backwards compatibility. This is obvious on reflection, but I never thought about it beforehand. Thanks to Hari KT for pointing it out. Why do you have to be extra-careful with interfaces and SemVer? [...] If we remove a public method, that’s clearly a BC break. If we add a non-optional parameter to an existing public method, that’s also clearly a BC break. [...] However, if we add a new public method to the concrete class, that is not a BC break. Likewise, changing the signature of an existing method to add an optional parameter is not a BC break either. [...] But what happens with an interface?

He suggests that changing current functionality (such as adding a non-optional parameter) is a backwards compatibility break but in an interface so is adding a new method. By adding a method you "break" the implementation someone already has, causing plenty of trouble for the users. He wonders about the right approach for making these updates, if it's creating a new interface or just extending the current one and having users migrate. He also includes a few update notes about abstract classes and how Symfony handles BC breaks too.

tagged: versioning public interface backwardscompatibility break bc abstract symfony

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

Phil Sturgeon:
The Importance of Serializing API Output
Jun 01, 2015 @ 09:50:16

Phil Sturgeon as a new post to his site today talking about the importance of serialized API output and why it's important to think about what to share and how they're shared.

One section that seems to get a lot of feedback and questions is when I talk about serialization, which I refer to as “adding a presentation layer to your data”. [...] To PHP developers, they often consider serialization to be using the serialize() function. Yes, this is one form of serialization, but it’s not the only one. Another common serialization approach is of course to use the json_encode() function. [...] Excuse the drastically simplified chunk of code here, but the point is we’re taking a model (probably using an ORM) and returning the result directly. This seems fairly innocent, but leads to a range of problems.

He suggests that, when thinking about the data coming out of your API, you have to assume that every possible value could be shared if models are output directly. He gives the example of user passwords which, obviously, don't need to be shared at all. He includes an example of formatting the output with the Fractal library and why using something like that is important. He covers some of the topics to think about including attribute data types, renaming fields to make them more clear, the ability to pull from multiple data stores and the ability to version serializers. He ends the post with links to a few different serialization formats and some solutions (not just PHP ones) that can be used for the sort of handling he recommends.

tagged: serialize api output json fractal datatype json tutorial versioning

Link: https://philsturgeon.uk/api/2015/05/30/serializing-api-output/

Qandidate.com Blog:
Using the Accept Header to version your API
Oct 20, 2014 @ 12:56:46

On the Qandidate.com blog today there's a new tutorial talking about the use of the Accept header in REST HTTP requests and, more specifically, working with it in a Symfony-based application.

I investigated different ways to version a REST API. Most of the sources I found, pretty much all said the same thing. To version any resource on the internet, you should not change the URL. The web isn't versioned, and changing the URL would tell a client there is more than 1 resource. [...] Another thing, and probably even more important, you should always try to make sure your changes are backwards compatible. That would mean there is a lot of thinking involved before the actual API is built, but it can also save you from a big, very big headache. [...] Of course there are always occasions where BC breaks are essential in order to move forward. In this case versioning becomes important. The method that I found, which appears to be the most logical, is by requesting a specific API version using the Accept header.

He shows how to create a "match request" method in his custom Router that makes use of the AcceptHeader handling to grab the header data and parse it down into the type and API version requested. He also includes an example of doing something similar in the Symfony configuration file but hard-coding the condition for the API version by endpoint.

tagged: accept header rest api versioning symfony tutorial

Link: http://labs.qandidate.com/blog/2014/10/16/using-the-accept-header-to-version-your-api/

Mathias Noback:
Semantic versioning for bundles
Sep 30, 2014 @ 11:26:40

In a recent post to his site Mathias Noback looks at the use of semantic versioning, introducing some of its basic concepts and how it can relate to the work done in Symfony bundles.

Semantic versioning is an agreement between the user of a package and its maintainer. The maintainer should be able to fix bugs, add new features or completely change the API of the software they provide. At the same time, the user of the package should not be forced to make changes to their own project whenever a package maintainer decides to release a new version.

He breaks down what the version numbering represents (major, minor and patch versions) and how they work with Symfony's "semver" to handle issues that come with backwards compatibility concerns. He then looks at a few things to consider when versioning your bundles and how it relates to the underlying libraries it might use:

  • Bundles expose an API themselves
  • The API of a bundle leads a life on its own
  • A library may contain bugs that are totally unrelated to the bundle
  • A library may contain features that are not implemented by the bundle

Ultimately, he suggests that bundle versioning should have nothing to do with the underlying libraries/packages. It's his opinion that they should only be reversioned when there is a change in the actual bundle.

tagged: semantic versioning symfony bundle package library opinion

Link: http://php-and-symfony.matthiasnoback.nl/2014/09/semantic-versioning-for-bundles/

SitePoint PHP Blog:
Database Versioning with Ladder Migrations
Apr 22, 2014 @ 10:48:41

The SitePoint PHP blog has posted another tutorial looking at database versioning (see this postfocusing on Ladder migrations. Ladder is a simple PHP-based way to write migrations with rollbacks in a clear, easy to read format.

Version control systems are invaluable for tracking changes in your code, particularly when you’re working in a team. However, most applications don’t consist solely of application code. Managing changes to the database has always been a little more challenging, particularly when you’re adding new features which require changes to the schema. [...] One solution is to move responsibility for creating and modifying the database schema into code, using migrations. That way, changes can be managed along with the rest of your application, and features we take for granted in version control – such as being able to compare versions and keep an audit trail – can be used for database changes.

He introduces the Ladder tool briefly, shows how to get it installed/configured and gets into writing a first simple migration. It creates a "users" table with two columns and comes with both "up" and "down" methods to make rollbacks easier. Ladder also provides functionality for database seeding, pre-populating the database tables with sample data either from hard-coded values or from a CVS file.

tagged: database migration ladder versioning tutorial project

Link: http://www.sitepoint.com/database-versioning-ladder-migrations

DZone.com:
PHP objects in MongoDB with Doctrine
Mar 21, 2012 @ 10:03:59

On DZone.com today Giorgio Sironi has a new post showing how you can use Doctrine with MongoDB to work with Document objects from the database.

In the PHP world, probably the Doctrine ODM for MongoDB is the most successful. This followes to the opularity of Mongo, which is a transitional product between SQL and NoSQL, still based on some relational concepts like queries. [...] The case for an ODM over a plain Mongo connection object is easy to make: you will still be able to use objects with proper encapsulation (like private fields and associations) and behavior (many methods) instead of extracting just a JSON package from your database.

He briefly mentions that the PECL extension for Mongo needs to be installed prior to trying out any of the examples. His first example shows how to create a DocumentManager (similar to the normal EntityManager for those familiar with Doctrine). He also shows an integration with the ORM and shares some of the findings he's made when it comes to versioning the resources (hint: annotations are your friend).

tagged: mongodb doctrine object orm tutorial versioning

Link:

Tilllate Blog:
Caching of Dynamic Data Sets
Dec 05, 2007 @ 10:29:00

On the Tilllate Blog, there's a new post discussing the use of caching in applications, specifically for dynamic data.

Consider you have a set of data that is changing dynamically for each page request and you need to cache that data the fastest way possible. You can’t cache dynamic and unpredictable data as a whole, can you? Hence, we would put each data entry into cache separately to be able to fetch it separately and dynamically. But this means bombing your cache infrastructure with with requests.

They break it up into a few different topics - caching text elements on the page, two-tiered caching (grouping cached items), incremental caching and cache versioning. They don't share an example of their code unfortunately, but they do mention something about a possible contribution to the Zend_Cache component of the Zend Framework.

tagged: caching dynamic data text element incremental versioning cache caching dynamic data text element incremental versioning cache

Link:

Tilllate Blog:
Caching of Dynamic Data Sets
Dec 05, 2007 @ 10:29:00

On the Tilllate Blog, there's a new post discussing the use of caching in applications, specifically for dynamic data.

Consider you have a set of data that is changing dynamically for each page request and you need to cache that data the fastest way possible. You can’t cache dynamic and unpredictable data as a whole, can you? Hence, we would put each data entry into cache separately to be able to fetch it separately and dynamically. But this means bombing your cache infrastructure with with requests.

They break it up into a few different topics - caching text elements on the page, two-tiered caching (grouping cached items), incremental caching and cache versioning. They don't share an example of their code unfortunately, but they do mention something about a possible contribution to the Zend_Cache component of the Zend Framework.

tagged: caching dynamic data text element incremental versioning cache caching dynamic data text element incremental versioning cache

Link: