Go Monorepo

As a maintainer and contributor to multiple, and often related, git repositories, I often find myself thinking that there must be a simpler way.

Consider, for example, a variety of CakePHP plugins that we develop and maintain at work.  Sure, each one provides a completely separate bit of functionality and has its purpose as a standalone project.  But, at the same time, they all have enough overlap that we use a common cakephp-plugin-template repository to keep things in sync, and also require cakephp-utils plugin from all of them.

It’s only natural to consider other ways of doing things.  Sure, I tried git submodules before, but they don’t quite cut it.  Something is still missing.

Today I came across the Go Monorepo website.  Which makes me wonder even further down this road.  There are also a few other tools and alternatives mentioned in this article.

That’s not something that I’ll jump into right now, but it’s definitely something I’ll consider to try out in the nearest future.

Documenting lists with Swagger

Swagger is a great tool for documenting APIs.  Not only it helps with keeping the documentation complete and up-to-date, but it also provides a handy sandbox for developers to play around with the API directly from the documentation.

We use Swagger a lot at work.  We’ve even pushed the bar slightly, but automatically generating the API documentation on the fly, to match the rest of our Qobrix functionality.  Whenever you change the database schema or the configuration of the fields, the changes are also reflected immediately in the API documentation.  And it works great!

One of the things that we haven’t done though until very recently is the documentation of the list fields.  Swagger provides the enum to document the values that can go into the field, but it’s not very helpful, when the values are not obvious.  Country codes and currency symbols work well, as they are common knowledge.  But if you have something custom, there needs to be a set of labels associated with the set of values.

The other day we decided that something is better than nothing, and added the documentation of the values as part of the field description (the property is described on the same page as enum above).  Here’s the Pull Request with the tiniest of changes.  And here’s how it looks in Swagger:

I admit, it’s not the prettiest of things, but at least the hints for the developers are there.  Also, since the list of labels uses a specific format, it’s quite easy to parse it out of the Swagger JSON automatically and reuse in third-party applications and services (like a website, connected to the system via the API).

While browsing around, I’ve also noticed that Swagger is growing and expanding. There is a new version of the specification – version 3.0, which has also been re-branded as OpenAPI Specification (see OpenAPI Initiative).  Here’s a great blog post that describes the differences between this and the previous versions, and here’s the migration guide for those who need it.

If you are working with PHP, zircote/swagger-php is the way to go.  It already even support the version 3.0.  If you are using the CakePHP framework, alt3/cakephp-swagger is the plugin for you (version 3.0 is not yet supported, but I’m sure it’ll get there soon).

Inflected – a port of ActiveSupport’s inflector to Node.js and the browser

For the last few years I have been heavily involved in building web applications with the CakePHP framework.  Apart from all the usual MVC, ORM, and so on, and so forth, features, I am a big fan of the CakePHP utilities.  And among all of them, my long time favorite is the Inflector class.

The Inflector class makes makes word transformations a breeze – camel-casing, snake-casing, plural, singular, and so on – work like a charm at least for the English language.  It’s also possible to use the same functionality for other languages, but that would require quite a bit of the linguistic expertise.

I’ve got so used to the inflections that I miss them every single time I have to step out of the CakePHP framework.  This doesn’t happen very often for me in the PHP domain, but JavaScript is a totally different story.

The other day I came across the inflected library, which brings most of the CakePHP’s Inflector to JavaScript, via either a Node.JS NPM package, or a simple inclusion of the JavaScript file to the page source and laying off all the hard work on to the browser.

I’m a lot happier with my universe now.

When and where to determine the ID of an entity

It always amazes me when I randomly come across an article or a blog post precisely on the subject that I’m mulling over in my head – all without searching specifically for the solution or even researching the problem domain.  It’s almost like the universe knows what I’m thinking and sends help my way.

When and where to determine the ID of an entity” is an example of exactly that.  Lately, I’ve been working with events in CakePHP a lot.  And for one particular scenario, I was considering the beforeSave() event in the model layer, which would trigger some functionality that modifies data in other models.  So, having a reference of the current ID would be useful for debugging and logging purposes.  But since the current entity hasn’t been saved it, the ID is not there.   And that’s where I started thinking about this whole thing and considering where is the right place to generate the ID.

One thing that kind of bothered me on top of the theoretical discussion, was the practical implementation, especially in different frameworks.  If I remember correctly, the earlier version of CakePHP framwork, used the presence or absense of the ID in the entity to differentiate between insert and update operations.  It might still be true now, but at least there is a way to work around it, as CakePHP now has isNew() method to check if the entity needs to be inserted or updated.

 

ORM: Active Record vs. Data Mapper

Everybody building a web application with a modern framework, is already probably using an ORM (Object-Relational Mapping).  Most frameworks include one out of the box.  But digging deeper into the subject, ORMs do vary from each other, and some cases, very significantly.

Most variations are coming from two main approaches: Active Record and Data Mapper.  I’ve heard the terms for a long time, but today decided to look into the meaning and the actual difference.

The two approaches seem very similar.  The difference is described in a multitude of articles online.  I particularly liked this one.  In essence, Active Record is a better choice for simpler, CRUD-based applications.  Data Mapper, on the other hand, is better for domain-specific applications, as it provides another level of abstraction between the domain objects and the persistence layer.

Most of my work these days is done with CakePHP framework, which I now thought uses the Active Record pattern.  But it turns out that CakePHP ORM so powerful, because it’s more than just one of those:

The CakePHP ORM borrows ideas and concepts from both ActiveRecord and Datamapper patterns. It aims to create a hybrid implementation that combines aspects of both patterns to create a fast, simple to use ORM.

It looks like I need to do some learning and dig deeper into the subject.  Pointers are welcome.