Tag: tools

Today I'm sharing a quick-and-dirty script to take an OpenAPI description, spin up a docs server locally, and copy the URL into your clipboard. I also use a bit of glob expansion in my script to find the right folder, because I have a lot of APIs with long and formulaic directory names (TM Forum members know this story). I'm spinning up Scalar here as it's my current favourite just-works local API docs platform.

The more I work on API standards, the more I realise how few teams understand that they can adopt the standards and, without breaking any contract, adapt them to make a strong interface for their own application. One of my favourite examples is to add enums where a standard interface cannot dictate the exact values, but in your own implementation it is very helpful to do so.

API reference documentation changed the way we built integrations, and eventually became part of the driving force for OpenAPI adoption and all the good tooling that flowed from it. As a developer experience specialist, I spend a lot of time thinking about how human users can work with the technical …

I've been using Optic's CLI, an OpenAPI tool that does a bunch of things including diffing OpenAPI descriptions and comparing HTTP traffic with OpenAPI. My use case was an established API that didn't have an OpenAPI file yet - using Optic we could create one as a starting point, and then move to a design-first workflow to make the changes that I was there to help with. For this blog post, I've used the example of https://api.joind.in as an excellent representation of an API still in use, but without an OpenAPI file and not built with code that a code generator would recognise.

For teams that generate OpenAPI from their codebase, there's a tough choice between maintaining rich and extensive content such as Markdown descriptions and examples in codebase annotations, or in making those changes to the generated file - and then losing them when the code changes and the file is regenerated. The new OpenAPI Overlay Specification defines a format for storing updates to an OpenAPI document, and there's a new generation of tools to make it easy to do, so let's take a look.

I come across a lot of "greedy" GitHub Actions, where automation is running across a whole project instead of only on the parts that are relevant. Examples might be code linters that report problems with documentation folders, or the inverse of that. It's especially problematic in monorepos where we probably want to use the same tool when we're doing the same task for different subfolders, but that tool might not make sense to run everywhere.

Wrangling some document conversion the other day, I ended up in a situation where I had the JSON I needed, but in a completely unreadable format. Luckily, this problem is very easily fixable .... when you know how. So today's post is a quick recap on how I did that using jq, a very handy command-line tool for working with JSON. For the impatient, here's the command:

Working on API tools, I get to see inside lots of different organisations' API projects and processes. Every scenario is different, but a common theme is that many companies use a more complicated API description workflow than you see in conference slide decks! This article shares my typical workflow, steps and chosen tools that might show up in an API description pipeline.

Reviewdog is a tool to use with GitHub actions for applying review tools in your CI. I use it with Vale, and it's really good. One thing that has tripped me up multiple times is that by default, it only applies the checks to the changes in the pull request, not to the whole project. So when you add something like Vale, which is a prose linter, it only checks ... the workflow file you just added! I always forget that it works this way, and how to change it, so I'm pasting some examples for future reference.

Vale is an open source CLI tool for linting prose (if you're not linting prose yet, why not? I never want to go back). I typically use it for everything, locally and in CI, and it's especially valuable now I'm working for a company that uses US English. You'd think that most of the challenges would be caused by the majority of non-native English language contributors? Nope, most of the chaos comes from the token Brit :)

I ran into one challenge though where I didn't want to enable Vale for everything: a large internal documentation repo. This is the catch-all of things we should share with one another and like most internal company documentation sites, there is a lot going on. I assembled a very minimal set of Vale rules and still the first pass netted me over 10k errors. Luckily, Vale has a --glob option, but it took me a while to find how to exclude multiple files and directories using it, so here's the example for future-me, and anyone else who needs to see it!

As a Developer Advocate for an API company, I spend a lot of time talking about APIs and webhooks and HTTP in general. Recently I've been focussing on HTTP tools, but I really wanted a very simple example API that I could use that would return JSON but really let me focus on the tools, not the API. So I created a "Planets and Webhooks" API with a couple of GET endpoints to return JSON data, and another endpoint to receive and log incoming webhook data.

I've been building apps with queues lately and mostly using beanstalkd as my queue because it is very simple, very fast and on my platform it is [apt install beanstalkd] -easy to install. I have also been using a handy web interface for beanstalkd which I like so much that I felt I ought to share! It's beanstalk-console, which is a PHP-based web interface to one (or many) beanstalkd servers.

I've been a long-time fan of RequestBin, but it's no longer active since it suffered so much bad traffic. It's never been too difficult to set up locally and when I tried to do that last week, I realised it has got even easier because it now has a docker-compose configuration.

At a conference a few days ago, I put up a slide with a few of my favourite tools on it. I got some brilliant additional recommendations in return from twitter so I thought I'd collect them all in one place in case anyone is interested - all these tools are excellent for anyone working APIs (so that's everyone!). First, my original slide:

I'm a fan of Jenkins as a build server, and on one particular project we've also started using New Relic (I haven't figured out how to blog fun things about New Relic without sharing graphs of client applications which doesn't seem like a cool thing to do). New Relic has a feature where you can notify it when you do a deployment, and it shows on the graphs a line marking when that happened, which is super useful for correlating performance changes with code changes.

I find myself needing to take a PDF, output it at a specific size, and have the result offset to the top right hand side of the screen. To achieve it, I needed a few new switches to my good friend PDFJam, so I thought I'd share my command!

pdfjam …

While I worked on this, we were using the wiki feature in GitLab ... which pretty much hit the nail on the head. Further investigation showed that the wiki feature in GitLab (and indeed in GitHub) is a ruby gem called Gollum.

It took me far too long to get my first hubot working; when I finally sat down to get it going the process was much easier than I expected! So here's a little guide in the hope that this helps you get started too.

I'm enjoying using hubot to integrate services very easily and both give updates and respond to commands in chat. One of my hubots chats to us in slack rather than in IRC, and there are a couple of gotchas that I wish I'd known about before I started!

• Hubot will …

There are lots of reasons why you might like to compile your own PHP extensions. For me those reasons are usually:

• The extension isn't available on pecl (e.g. uprofiler)

• The extension is on pecl, but you need the newest version or a branch with a particular feature or fix in it, perhaps for testing

• You are fixing an extension yourself (yay, we need more people like you!)

Related: If you followed my previous post on compiling PHP, be aware that in the ``php/bin/`` folder there is a pecl binary that will install extensions correctly for whichever version of PHP it belongs to, so you may not need to read the rest of this post. However if you do, the paths follow on from the examples in that post.

I haven't seen a really approachable guide anywhere, we tend to speak of extensions in hushed tones, and actually it isn't particularly tricky so here is my quick how-to guide.

When I advise people about upgrading their PHP version, I say things like "just run your test suite with the new version" "just grab the new version and try your site with the built-in webserver". A couple of people recently have asked for more detail on how to actually achieve these things so here's a quick primer on getting new PHP without touching anything to do with your existing PHP installation.

The joind.in projects are set up so that the build process runs on pull requests when they are opened, which is great! It means that contributors don't have to wait for one of the maintainers to look at it, only to reject the contribution on something that could be picked up automatically. I've had a few questions about the setup so I thought I'd share how it works.

I'm introducing lint checking on one of my projects, because it didn't have a build process yet and I love this as a great place to start. Oh, and because we managed to commit broken syntax! So I set up a php lint job (I will share my travis config in another post) and tried to work out doing the same thing for JavaScript.

There's been some cool things happening in the PHP world over the last few years, but with the least helpful names ever ... yes, those PSR-somethings which all do totally different things (apart from two of them which are the same). They're actually all superb things, and done for a good reason, so I thought I'd try to translate them into normal speak.

Short answer: everything! However we need some good directory structures and source control configuration to make that a really practical answer, so this article is a quick outline of my usual advice for a good source control structure for a standard web project. The examples are for a PHP project but I'm sure you could apply this to your own language of choice, also.

While working on a book ("PHP Web Services" from O'Reilly, not out yet but soon!) recently, I was looking for some place I could make HTTP requests to, to show off how to make different kinds of requests with different tools. On my own machine, I have a couple of scripts that chatter back giving debug information about the requests that were made, but I wanted to get the tools examples going without any additional dependencies at all. I hadn't used anything like these tools before, but I found quite a few alternatives, so I thought I'd share what I came up with.

Last week I wrote an email to a client who hasn't yet implemented source control, but who is thinking about it. It turned into rather a long email as I attempted to convey WAY too much information in one long email. After some twitter banter, I repackaged my thoughts into a whitepaper on Source Control entitled You're not using source control? Read This! (PDF, no registration needed).

The document goes on to talk about the available tools (git, Hg, SVN) and give a sales pitch for _why_ source control has benefits for an organisation. There are also some action points to follow to implement source control if you haven't already taken the leap, which I hope will help anyone looking to take that step - it's kind of awkward in this day and age to admit that your organisation doesn't have source control, but however this situation arose, hopefully this document wraps up my thoughts on how to find a good way out!

This post is mostly about a tutorial I will be delivering at PHPNW on October 5th in Manchester, UK, and why I think a tutorial that contains no PHP belongs at a PHP conference

In October, I'll be delivering a tutorial at the mighty PHPNW Conference which contains very little PHP. Why? Because I think, as developers, it's our other professional skills that suffer. As a consultant, I work with lots of different teams, and it is very rare for code to be the problem (and the one time it was, it wasn't the only problem!).

In web development, our biggest challenges are not writing code, we can do that. But getting the code safely from one place to another, with many people's work preserved, having our platform(s) correctly configured and understanding how to use them, making use of the tools in the ecosystem which will help us improve the quality of our code; these are the big challenges we face, and that's why I proposed this workshop and why I think all these topics are important.

I've been hearing great things about puppet, chef, vagrant, and friends for a while now, but since I work on my own I tend to either develop straight onto my ubuntu machine or grab an appropriate existing VM and use that. So I read about this brave new world of virtualisation but (as with most tools) they can be hard to introduce on your own, and I didn't.

Then I went to WhiskyWeb, which had a hackathon. I'm unclear on exactly what happened because my attention was elsewhere but it seems like @JayTaph showed off puppet and vagrant to @deizel*, who immediately built a vagrant setup for joind.in, which is an open source project that I'm currently leading. With the shiny new technology all packaged for me, I decided it was time to take a look!

I wrote recently about deployment and I got some followup questions about managing database changes when you've got multiple versions of code hanging around.

There are two things you need to come to terms with:

• There is no silver bullet

• Rigid process is required

Since becoming freelance 18 months ago, I've taught a number of courses at my excellent local tech training centre, NTI Leeds. Over the next few months we're running some one-day PHP courses (see my course dates page for more detail and the dates, all these are in Leeds although I'd like to run them elsewhere too), targeted at a particular area or set of skills. These are areas that I find myself delivering consultancy or training on frequently, or things I teach when I go places and realise these gaps exist in their knowledge. Does this match your experiences of "things I wish PHP developers knew - including me"?