“The Illustrated TLS Connection” is an interactive guide to the TLS connection, explaining every byte with code, comments, annotations, and more. If you ever wanted to know the details of how this works, I can’t think of a better resource to direct you to. And if you find any issues or can suggest a better explanation, there’s a GitHub repository for you to contribute.
Any web developer knows how to apply CSS rules to style web page elements. Including links. Including hover effects (on mouse over). But I think most have never went far enough to explore the limits of this styling. “Having fun with link hover effects” goes exactly there, with some really cool techniques that tend to leave people with “why didn’t I think of that” thought hovering over their head.
“The Land Where PHP Uses eval()” is an interesting post powered by the study of 2,000 Open Source PHP projects. It details a number of scenarios where developers have used the eval() function and suggests the better ways for most of these. Despite of how dangerous and inefficient the eval() is in PHP, there are still good reasons to use it in some cases. Read the full post to see which are those.
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).
Liam Hammett (check many of his other excellent posts) has a nice explanation of the bitmask constant arguments in PHP. These are fairly common and most PHP developers have seen them. However, it’s been a few occasions where I discovered that especially newer developers don’t understand how this works.
Bitmask arguments and operations were used extensively in programming by the older generations, especially where CPU and memory were critical. But with hardware getting so much cheaper over the last few decades, nobody really cares about an extra few memory bytes and CPU cycles.
Regardless of the memory and CPU though, bitmask arguments are still quite handy and using them can significantly simplify the code.