DEV Community: Oliver Davies

Experimenting with web components

Oliver Davies — Thu, 29 Feb 2024 00:00:00 +0000

After my Beyond Blocks episode with Mark Conroy, I've spent some time this week experimenting with web components.

The team and I are building a new design system in Fractal and, as Drupal is our main application, we're using Twig as our templating language within Fractal so the changes are easier to port between systems.

Web components are agnostic, so they work within different languages and frameworks.

We also use other technologies, such as Vue.js, and third-party suppliers, so having an agnostic web component would reduce the time and effort needed to implement the design system across different technologies and applications.

If we can make self-contained web components that include their own styling and behaviour, that also improves re-usability and reduces the maintenance overhead as there would be one canonical version for everyone to use - not just a reference implementation everyone would need to recreate.

After this spike, I'm intrigued to see how we could use web components and what potential issues we can solve with them whilst reducing our implementation and maintenance efforts.

Are you interested in web components, too? Listen to the podcast episode with Mark Conroy.

P.S. Do you need immediate access to an expert Drupal Developer? With my Drupal development subscription, make unlimited requests for a fixed monthly price in less time than posting to a job board!

Why I don't branch

Oliver Davies — Wed, 28 Feb 2024 00:00:00 +0000

A few days ago, I asked why people are still using Git Flow in 2024.

I moved to trunk-based development two years ago and haven't looked back.

Why did I do that?

Only having a single branch instead of separate main and develop branches and branches for each feature and fix is much simpler.

I don't get merge conflicts when trying to merge branches together, as everything is on a single branch.

A couple of years ago, I was working on two features for a project. I was demoing them to a client and broke my local environment when switching branches from feature A to feature B.

It was embarrassing, and it took me time to resolve the issues before I could continue working.

Here's the thing

Working mostly on a single branch avoids merge conflicts, saves time, and simplifies my workflow.

No more confusion, merge conflicts or broken demos.

P.S. There's less than a year until Drupal 7's end-of-life date. Plan your upgrade to Drupal 10 now!

Building a design system in a few hours with Symfony

Oliver Davies — Tue, 27 Feb 2024 00:00:00 +0000

I recently spoke with Mark Conroy, Director of Development at Annertech, on the Beyond Blocks podcast. We discussed building something useful in a day and building design systems with web components.

Inspired by that conversation, I spent this afternoon experimenting with web components and seeing how I could use them within a design system we're building, as I think they can solve a particular need we have.

Following that, I thought I'd see how I could build my own design system and decided to do it with Symfony and see what I could achieve within a few hours.

It was a great opportunity to take Symfony 7 for a spin and explore and test some things that Ryan Weaver and I discussed in our episode, such as Symfony UX and Twig components.

Each component is a Twig component with its own PHP class and Twig template, which is rendered when I visit its URL, and I can use the HTML-like <twig:Logo /> syntax to include child components.

You can view the code on GitHub, and it may be something I use and work on in the future.

P.S. There's less than a year until Drupal 7's end-of-life date. Plan your upgrade to Drupal 10 now!

Docker and content creation with Nick Janetakis

Oliver Davies — Mon, 26 Feb 2024 00:00:00 +0000

This week's guest on the Beyond Blocks podcast is Nick Janetakis - a Software Developer, Docker Captain and Teacher who focuses on building and deploying web apps.

I'm a long-time consumer of Nick's content via his blog, YouTube channel and courses, so it was great to discuss Docker, content creation and more with him.

Listen to the episode

P.S. Are you still using Drupal 7 and don’t know what’s involved to upgrade to Drupal 10? Book a Drupal 7 upgrade consultation call or an upgrade roadmap.

Why do people still use Git Flow?

Oliver Davies — Sun, 25 Feb 2024 00:00:00 +0000

The first conference talk I gave was at DrupalCamp London 2014.

The talk was about Git Flow - a popular branching scheme I was using to manage a project, where there are different branches for development and production versions of the software and separate branches for features, releases and hotfixes.

It's been a standard approach as I've worked on different projects and teams, usually with pull or merge requests and code reviews.

But why do people still use it?

I was conducting technical interviews recently and every candidate explained how they used Git Flow or something inspired by it, and GitHub and GitLab have their own simplified versions.

Vincent Driessen wrote the original Git Flow blog post in January 2010, though he updated it in March 2020 to add this note of reflection:

This model was conceived in 2010, now more than 10 years ago, and not very long after Git itself came into being. In those 10 years, git-flow (the branching model laid out in this article) has become hugely popular in many a software team to the point where people have started treating it like a standard of sorts — but unfortunately also as a dogma or panacea.

During those 10 years, Git itself has taken the world by a storm, and the most popular type of software that is being developed with Git is shifting more towards web apps — at least in my filter bubble. Web apps are typically continuously delivered, not rolled back, and you don't have to support multiple versions of the software running in the wild.

This is not the class of software that I had in mind when I wrote the blog post 10 years ago. If your team is doing continuous delivery of software, I would suggest to adopt a much simpler workflow (like GitHub flow) instead of trying to shoehorn git-flow into your team.

If, however, you are building software that is explicitly versioned, or if you need to support multiple versions of your software in the wild, then git-flow may still be as good of a fit to your team as it has been to people in the last 10 years. In that case, please read on.

To conclude, always remember that panaceas don't exist. Consider your own context. Don't be hating. Decide for yourself.

Since adopting trunk-based development and continuous integration and delivery, I've worked faster and avoided merge conflicts, which wasn't the case before, even when I was the only one working on a codebase.

It's a simpler workflow.

I don't need to think about whether this branch is a feature or a hotfix, and I've rarely seen release and hotfix branches used as described in the original blog post.

Here's the thing

Do what works best for you and your team, but don't adopt something because it's the "standard" approach.

P.S. There's less than a year until Drupal 7's end-of-life date. Plan your upgrade to Drupal 10 now!

When should you start writing tests?

Oliver Davies — Sat, 24 Feb 2024 00:00:00 +0000

When you start a new project, when should you start writing tests and doing test-driven development?

Is it before you write any code, or is it something you can start later?

When starting versa, I was only scaffolding the console commands and running some basic commands such as "composer install" and "phpunit".

At that point, there wasn't any business logic to test.

The first versions only supported PHP, so there was no complexity around which language the project used.

There was no logic to determine which language or package manager was used.

Now I've started to add this functionality - such as determining the project type from its composer.json or package.json file - there is logic to test, and I've started to write tests and do test-driven development.

At this phase, I can see the value, which I couldn't when setting up the application to begin with, and different have any logic worth testing.

P.S. Do you need immediate access to an expert Drupal Developer? With my Drupal development subscription, make unlimited requests for a fixed monthly price in less time than posting to a job board!

Slow down to go fast

Oliver Davies — Fri, 23 Feb 2024 00:00:00 +0000

I've recently been improving my typing.

My speed is usually good, but my accuracy is not where I'd like it to be (it's usually around 95%, and I'd like it to be nearer 99%).

It may seem counterintuitive, but I need to slow down to get faster.

But not focusing on the speed and prioritising accuracy, I'll still get faster as I'm not mistyping as many keys.

It's the same when I run.

My first few kilometres are slower as I get into the run, find my pace, focus on breathing, etc.

Here's the thing

The same can also be said for automation and automated testing.

They require some time investment initially but will save time as a project evolves and becomes more complex.

You need to slow down initially to go faster later.

P.S. Do you need immediate access to an expert Drupal Developer? With my Drupal development subscription, make unlimited requests for a fixed monthly price in less time than posting to a job board!

Diffy and visual regression testing

Oliver Davies — Thu, 22 Feb 2024 00:00:00 +0000

I recently recorded an episode of Beyond Blocks with Yuri Gerasymov, who runs Diffy.

He and I discussed visual regression testing, why you'd use it, and some features Diffy offers.

I usually write a combination of browser, kernel and unit tests within an application framework like Drupal and Symfony or behavioural tests with Behat.

These validate that my logic works as expected and that functions return the correct results or pages return the correct response codes and content.

There are types of issues, though, such as breakages within the page layout or structure, which these tests won't discover but can be identified by visual regression tests that compare before and after screenshots.

I added to my website during the recording and can see what value it offers as an additional layer of testing on top of the tests I already write.

P.S. Do you need immediate access to an expert Drupal Developer? With my Drupal development subscription, make unlimited requests for a fixed monthly price in less time than posting to a job board!

Coding defensively and considering the unhappy path

Oliver Davies — Wed, 21 Feb 2024 00:00:00 +0000

Last week, whilst speaking about Sculpin at PHP South West, I showed an example from a client project I'd built with Sculpin.

The project was for a local gym and fitness centre, and I was demonstrating how I'd created the timetable page and kept the data separate from the HTML and Twig markup so the client could easily administer it (they edit the files on GitHub, which triggers a rebuild of the website).

Each class should have a name and start and end times and be on a specified day.

But what if the client didn't include a name or start or end time?

What if they put a number or boolean instead of a string?

What if there are no classes on a particular day?

You don't know how people will use your software, so it's best to be defensive - validate and verify things before rendering them and prevent the page or whole application from breaking if something isn't as you expected or assumed.

We also can't assume the "happy path" will always be correct.

What if there aren't any classes? Do we put an empty message on the timetable or not show that day?

Another scenario

If you were retrieving or posting data to an API endpoint, would you assume it was successful or verify the response code is what you expected?

If you get the data, do you check if it's in the correct format and something you can use?

If not, do you verify other actions in your application haven't run and it's not in an invalid state?

Here's the thing

In PHP, a common approach is to use the assert() function, as we saw in yesterday's email.

Then, write automated tests that don't test just the happy path but also the unhappy paths.

P.S. There's less than a year until Drupal 7's end-of-life date. Plan your upgrade to Drupal 10 now!

Which level is right for you?

Oliver Davies — Tue, 20 Feb 2024 00:00:00 +0000

Today, whilst working on Versa, I was experimenting with different PHPStan levels.

Level 1 is the least strict level, and applies the fewest rules and returns the fewest results.

As you increase the level, the stricter PHPStan is.

Levelling up to 9

Here is the code to get the values of the --extra-args and --working-dir options:

$extraArgs = $input->getOption('extra-args');
$workingDir = $input->getOption('working-dir');

This passed PHPStan level 8, but these are the errors I get when running level 9:

------ -------------------------------------------------------------------------------------------------------
 Line versa
------ -------------------------------------------------------------------------------------------------------
 61 Parameter $extraArgs of static method App\Process\Process::create() expects string|null, mixed given.
 62 Parameter $workingDir of static method App\Process\Process::create() expects string, mixed given.
 72 Parameter $extraArgs of static method App\Process\Process::create() expects string|null, mixed given.
 73 Parameter $workingDir of static method App\Process\Process::create() expects string, mixed given.
 84 Parameter $extraArgs of static method App\Process\Process::create() expects string|null, mixed given.
 85 Parameter $workingDir of static method App\Process\Process::create() expects string, mixed given.
 94 Parameter $extraArgs of static method App\Process\Process::create() expects string|null, mixed given.
 95 Parameter $workingDir of static method App\Process\Process::create() expects string, mixed given.
 104 Parameter $extraArgs of static method App\Process\Process::create() expects string|null, mixed given.
 105 Parameter $workingDir of static method App\Process\Process::create() expects string, mixed given.
 119 Parameter $extraArgs of static method App\Process\Process::create() expects string|null, mixed given.
 120 Parameter $workingDir of static method App\Process\Process::create() expects string, mixed given.
------ -------------------------------------------------------------------------------------------------------

[ERROR] Found 12 errors

The issue is that $input->getOption() from Symfony's InputInterface returns mixed - even though it always returns null or a string.

If I did --working-dir 2, it would return the string "2".

An empty string throws an error, and an empty value (if there are no extra arguments) returns null.

So, I know $workingDir will always be a string and $extraArgs will either a string or null.

Passing level 8

To pass level 8, PHPStan needs to be sure the variables are what I think they are.

Here's the code I can use to get it to pass:

$extraArgs = $input->getOption('extra-args');
$workingDir = $input->getOption('working-dir');
assert(is_string($extraArgs) || is_null($extraArgs));
assert(is_string($workingDir));

By using assert() and throwing an Exception if the condition fails, PHPStan is now happy with the code and my code passes level 9.

Here's the thing

Although the extra code gets PHPStan to pass, it it worth it?

Is this extra code adding value? Does it make the code more readable or is it likely to prevent a bug?

In this case, I know the value will always be the type I expect.

I can work around this using a baseline or annotations for PHPStan to ignore these lines, or is level 8 good enough for this project?

Similar to 100% test coverage, is aiming for the highest PHPStan level an objective to be met, or is enough value being added added by the lower level?

Which level is right for you and this codebase?

P.S. Need help or want another pair of eyes on your code? Book a 1-on-1 consulting call or an online pair programming session with a 100% money-back guarantee.

Introducing Versa - the versatile CLI tool

Oliver Davies — Mon, 19 Feb 2024 00:00:00 +0000

Today, I started to build a new open-source project - Versa, the versatile command-line tool that standardises common commands across projects.

After watching a Twitch streamer building something similar in Rust, I decided to build my take on it and add features I'd need, such as support for local vs Docker-based commands and to run different commands for different projects.

For example, versa run would need to run different commands for Drupal and Sculpin projects, versa test should support different test frameworks for the same language - e.g. PHPUnit, Pest and ParaTest for PHP - and the commands will need to be different in Docker Compose-based projects.

Currently, this logic is within my Build Configs project but can be moved to Versa.

This reduces the complexity within that codebase and means I can open-source it as it's a separate project.

At the moment, I've added PHP as the only supported language but I will add JavaScript/TypeScript support so it supports projects like Fractal.

It's still in the prototype phase and includes some initial commands, but the interesting parts will be making it clever.

Instead of running versa run --type sculpin, I'd like to just do versa run and have it determine the type of project automatically.

versa test should be able to determine the testing framework automatically based on what's in the project's composer.json file instead of having to specify it.

Likewise, for JavaScript, versa install should be able to determine if npm, yarn or pnpm is used.

That'll be where the more complex code will be added and when I start doing test-driven development - maybe with Behat, which is also something I've been thinking about for Build Configs.

Interested? Take a look at the code.

P.S. Are you still using Drupal 7 and don’t know what’s involved to upgrade to Drupal 10? Book a Drupal 7 upgrade consultation call or an upgrade roadmap.

Build something useful in one day with Mark Conroy

Oliver Davies — Sun, 18 Feb 2024 00:00:00 +0000

This week on the Beyond Blocks podcast, I'm joined by Mark Conroy - Director of Development at Annertech to discuss all things front-end development and building something useful in one day.

Listen now

Talking points

Building better websites faster, including Drupal distributions, such as LocalGov.
What Drupal gives you out of the box and using the right tool for the job.
Drupal migrations and migrating Drupal configuration from a spreadsheet.
Saving time and improving efficiency by standardising base builds with Docksal and Composer.
How to build projects, like the Running Plan Generator, in a day and training for 10Ks and marathons.
Prioritising tasks.
Annertech's development workflow and standardisation by developing on remote servers.
Why you may not need preprocessors and complicated front-end build tools, and reducing complexity using vanilla CSS, JavaScript and web components.
Lowering the barrier to entry to contribute to open-source projects.
Building a design system/component library with web components.
The Content Access by Path module that was developed for Essex County Council.

P.S. There's less than a year until Drupal 7's end-of-life date. Plan your upgrade to Drupal 10 now!