DEV Community: Lynn Romich

E2E Testing an App with Clerk Authentication in Cypress

Lynn Romich — Thu, 21 Apr 2022 00:39:25 +0000

Background: Clerk is a hosted authentication and user management product.

I recently started writing E2E tests in Cypress for an app that uses Clerk for authentication, and there wasn’t anything out there to guide me, so here’s what I ended up with after fiddling with it for a bit.

(Note: In my case, this is a Next.js app using Clerk’s Next.js SDK, but my understanding is that this code will work everywhere, because their client SDKs all ultimately use ClerkJS under the hood.)

I wrote a custom Cypress command that waits for Clerk to load, signs the user out if they aren’t signed out already, and then signs in with test credentials (see here for how you can set these so that they’re accessible via Cypress.env()).

Cypress.Commands.add(`initializeAuth`, () => {
  cy.log(`Initializing auth state.`)

  cy.visit(`/`)

  cy.window()
    .should(window => {
      expect(window).to.not.have.property(`Clerk`, undefined)
      expect(window.Clerk.isReady()).to.eq(true)
    })
    .then(async window => {
      await window.Clerk.signOut()
      await window.Clerk.client.signIn.create({
        identifier: Cypress.env(`TEST_USER_IDENTIFIER`),
        password: Cypress.env(`TEST_USER_PASSWORD`),
      })
    })
})

If you’re using TypeScript to write your tests (which I recommend!), you’ll also want to add this command to your custom command types.

declare global {
  namespace Cypress {
    interface Chainable {
      /**
       * Initialize auth to a state where you're logged in as the test user.
       * @example cy.initializeAuth()
       */
      initializeAuth(): Chainable<void>
    }
  }
}

Ultimately, you’ll probably want to use this command in a before or beforeEach hook to reset the auth state before every test, like so:

describe(`Test Page`, () => {
  beforeEach(() => {
    cy.resetDatabase() // another custom command
    cy.initializeAuth()
  })

  // ... tests go here
})

Happy testing! Please let me know if you run into problems with this approach.

Yes, PHP is Worth Learning/Using in $CURRENT_YEAR

Lynn Romich — Wed, 17 Nov 2021 23:25:40 +0000

Welcome, dear reader! If you're reading this, you're probably one of the many people who find themselves wondering how much of what they've heard about PHP (a lot of which isn't super positive, I'm sure) is still relevant today. Is PHP a dying language? Should you learn PHP in $CURRENT_YEAR, and/or use it to build your next app? Hopefully, by the end of this post, you'll have the answers to these questions and more.

Rather than yet another generic overview of the language or a point-by-point refutation of the things people say is wrong with it, what I want this post to be more than anything else is kind of a comprehensive list of ✨good things about PHP✨ (or, well, at least things that I think are good).

How We Got Here

If you have any preconceptions about PHP at all, they're probably largely shaped by what the discourse around it was during the PHP 4 and PHP 5 days. This was an era where PHP was increasingly seen as a "legacy" platform in contrast to cool new projects like Ruby on Rails and Node.js, and conventional wisdom was that PHP was simply a "bad" language, or at least a language a lot of people were writing bad code in.

You might also have heard that PHP 7 was a big step forward for PHP, though, and this is true. While the story of how PHP got to where it is today is largely one of many incremental improvements, a lot of people would probably agree that the release of PHP 7 in 2015 was the start of the "modern" PHP era. PHP 7 included, among other things:

dramatic performance improvements
a significantly expanded type system (scalar types and return types)
anonymous classes
the null coalescing operator (??)
the spaceship operator (<=>)
unicode codepoint escape syntax (echo "\u{2764}"; → ❤️)
a built-in CSPRNG API

What PHP Code Looks Like Today

Over the last several years, PHP has become a significantly more ergonomic language, as examples like this post illustrate very well. Let's do a rundown of some of the most significant features PHP has gained over the years, some of which you may or may not recognize from other languages (and some you might even wish your favorite language had!).

The null coalescing operator

// equivalent to:
// $username = isset($_GET['user']) ? $_GET['user'] : 'anonymous';

$username = $_GET['user'] ?? 'anonymous';

The nullsafe operator

// equivalent to:
// $dateTime = $event->getDateTime();
// $timestamp = $dateTime ? $dateTime->getTimestamp() : null;

$timestamp = $event->getDateTime()?->getTimestamp();

Constructor property promotion

class WidgetManager
{
    public function __construct(
        public LoggerInterface $logger
    ) {}
}

This code is equivalent to:

class WidgetManager
{
    public LoggerInterface $logger;

    public function __construct(
        LoggerInterface $logger
    ) {
        $this->logger = $logger;
    }
}

The `match` expression

$error = match ($code) {
    0 = null,
    1 => new SomeError(),
    2, 3, 4 => new OtherError(),
    default => new UnknownError(),
}

Named arguments

function testFunction(
    string $first,
    string $second,
    ?string $third = null,
    ?string $fourth = null
) { /* … */ }

testFunction(
    second: 'second value',
    first: 'first value',
    fourth: 'fourth value',
);

Arrow functions

$collection = new ArrayCollection([1, 2, 3]);
$incremented = $collection->map(fn (int $i) => $i + 1);
// $incremented is [2, 3, 4]

Attributes

#[Route('/greetings')]
class GreetingController
{
    #[Route('/hello')]
    public function hello(): string
    {
        return 'hello';
    }
}

The spaceship operator

The spaceship operator is a little esoteric (and possibly a little controversial, depending on how confident you are that people reading your code will know what it does without looking it up), but the one thing it's very useful for is writing clear and succinct comparison/sorting functions.

echo 1 <=> 1; // 0
echo 1 <=> 2; // -1
echo 2 <=> 1; // 1

echo "a" <=> "a"; // 0
echo "a" <=> "b"; // -1
echo "b" <=> "a"; // 1

The spread operator

$first = ['a' => 1, 'b' => 2];
$second = ['c' => 3, 'd' => 4];

$merged = [...$first, ...$second];

// $merged is ['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4]

The numeric literal separator

$withoutSeparators = 1000000000;
$withSeparators = 1_000_000_000;

echo $withoutSeparators === $withSeparators; // true

Array destructuring

$list = [1, 2]
[$first, $second] = $list

// $first is 1, $second is 2

$array = [
    'a' => 1,
    'b' => 2
];

['a' => $a, 'b' => $b] = $array;

// $a is 1, $b is 2

PHP's Type System

While it's by no means the strictest type system out there (not to mention entirely optional, much like TypeScript), modern PHP has a robust type system that includes features like interfaces, scalar and object types, nullable types, union and intersection types, and more.

Code speaks louder than words, so here's an example of what code that takes full advantage of the type system in PHP 8.1 can look like:

<?php

declare(strict_types=1);

class MyClass
{
    public \DateTimeInterface $dateTime = new \DateTime();

    public function __construct(
        public readonly LoggerInterface $logger
    ) {}

    public function useUnionTypes(int|string $input): void
    {
        // $input is guaranteed to be either an int or a string
    }

    public function useIntersectionTypes(Traversable&Countable $input): void
    {
        // $input is guaranteed to satisfy the constraints
        // of both `Traversable` AND `Countable`
    }
}

Package Management

Composer is the de facto standard package manager for modern-day PHP, and has been for about a decade now. It's strongly inspired by other popular package managers, such as npm for JavaScript, so if you've used a modern package manager in any other language, chances are you'll feel right at home with Composer.

Packagist is the main public package repository for Composer. Like npm, you can also use Packagist to host your private packages for a reasonable monthly fee.

What I'd consider the main difference between Composer and npm is actually one of culture, rather than a technical difference — the PHP community doesn't generally have the preference for micropackages that the JavaScript community does, so for better or worse, the average PHP project is more likely to have dozens of larger dependencies than hundreds of smaller ones.

Frameworks

The current PHP landscape is dominated by two web application frameworks: Laravel and Symfony. While a detailed breakdown of the differences and similarities between these is out of scope for this post, suffice to say that they're both modern, expressive frameworks that aim to make it easier to write robust, fast, and maintainable web applications while reducing the need to write boilerplate code as much as possible.

If you're concerned about frameworks perhaps being "overkill" for what you want to do with PHP, you'll be happy to hear that Symfony is a microframework out of the box (all components outside of the core framework are 100% optional), and Laravel also has a microframework variant called Lumen.

To help you get a bit of a feel for these, here's what some typical modern PHP code written with one of these frameworks might look like:

<?php

namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class ExampleController
{
    // the RandomNumberGenerator is automatically
    // injected by a service container

    public function __construct(
        private RandomNumberGenerator $randomNumberGenerator
    ) {}

    #[Route('/number')]
    public function number(): Response
    {
        $number = $this->randomNumberGenerator->generate(min: 1, max: 100)

        return new Response(
            "<html><body>Your lucky number is: $number</body></html>"
        );
    }
}

The Open-Source Ecosystem

PHP has an incredibly robust open-source ecosystem that I honestly think even a lot of more "respectable" languages can envy.

There are high-quality, well-maintained open-source libraries available for pretty much everything the average PHP application is likely to need, and many of the most popular packages in the ecosystem are maintained by established vendors or projects rather than individual maintainers, though of course there's plenty of those, too.

Anyhow, the following is a very surface-level overview of some of the most significant packages in the PHP ecosystem:

symfony/* - the Symfony Components, a set of incredibly popular PHP packages and the foundation for the Symfony framework
- symfony/cache - a production-ready caching library with support for many different backing stores
- symfony/console - a CLI library used by many notable PHP projects
- symfony/dependency-injection - a PSR-11-compatible service container
- symfony/dotenv - a .env file parser
- symfony/event-dispatcher - an event dispatcher
- symfony/form - a library for creating and processing forms (HTML or otherwise)
- symfony/http-client - an HTTP client library
- symfony/mailer - a multi-transport library for creating and sending emails
- symfony/messenger - a message bus with support for sync and async message processing
- symfony/notifier - a tool for sending notifications with first-party support for email, SMS, Slack, Discord, Telegram, push notifications, and more
- symfony/routing - the router used by the Symfony framework
- symfony/security - utilities for authentication, authorization, CSRF protection, and other common security needs
- symfony/serializer - a serialization/deserialization library with support for JSON, XML, YAML, CSV, and more
- symfony/validator - a data validation library
league/* - The League of Extraordinary Packages, a set of modern, standards-compliant PHP packages developed with the explicit mission of improving the PHP ecosystem
- league/commonmark - a CommonMark-compliant Markdown parser
- league/csv - read and write CSV documents
- league/flysystem - a filesystem abstraction with support for local filesystems, object storage, FTP, and more
- league/oauth2-server - an OAuth 2.0 authorization server implementation
- league/oauth2-client - an OAuth 2.0 client library with built-in and community support for many common OAuth 2.0 providers, as well as custom providers
- league/omnipay - a multi-gateway payment processing library
doctrine/* - packages from the Doctrine Project, largely but not exclusively related to working with databases
- doctrine/collections - utilities for working with arrays of data
- doctrine/dbal - a data*base **abstraction **l*ayer with support for MySQL, Oracle, Microsoft SQL Server, PostgreSQL, and SQLite databases
- doctrine/orm - the Doctrine ORM, a popular PHP ORM based on the Data Mapper pattern
- doctrine/migrations - utilities for database schema versioning (i.e. database migrations)
phpoffice/* - packages from the PHPOffice project, a set of libraries for working with file formats produced by Microsoft Office and other office suites
- phpoffice/phppresentation - read and write presentation file formats (e.g. .pptx)
- phpoffice/phpspreadsheet - read and write spreadsheet file formats (e.g. .xlsx, .csv)
- phpoffice/phpword - read and write document file formats (e.g. .docx)
guzzlehttp/guzzle - an HTTP client library based on PSR-7
monolog/monolog - a very widely-used logging library based on PSR-3
phpunit/phpunit - the de facto standard PHP testing framework, based on the xUnit architecture
pestphp/pest - a modern testing framework built on top of PHPUnit
nesbot/carbon - an extension of the PHP DateTime API
phpstan/phpstan - a static analysis tool, the most popular of several active projects
twig/twig - a modern template engine, inspired by Python's Jinja template engine

PHP-FIG

PHP-FIG — short for "PHP Framework Interop Group" — is a group of influential projects in the PHP community working to push PHP forward by standardizing a bunch of things every project was doing in its own, ever-so-slightly incompatible way.

Unfortunately, while pretty much all of the most influential projects in the PHP ecosystem were once members of PHP-FIG, many have since left over concerns that the project was headed in the direction of building a "framework-by-committee" rather than working on relatively simple standards everyone could actually implement. Some things never change, I guess.

That being said, PHP-FIG still very much deserves a place in this post, both because it's frankly a pretty unique project I don't think I've seen attempted anywhere else, and also because it's still produced a number of incredibly useful PSRs (PHP Standard Recommendations) over the years. These include:

an autoloading standard (PSR-4)
interfaces for common app/framework components (PSR-3, PSR-6, PSR-11, PSR-14, PSR-16)
standards for HTTP request/response objects and code that handles them (PSR-7, PSR-18)
style guides (PSR-1, PSR-12)

No Compiling/Transpiling

One thing you'll probably find refreshing about PHP compared to many comparable languages is that it doesn't require a build step (at least, not one that you have to think about). In fact, due to PHP's typical execution model (more on that later), not only is there no build step, but you don't even have to restart your web server when you change your code — hit save, send the request again and the response you get will be from the code you just saved.

One major benefit of this (to me, anyway) is that when you install a package through Composer, you're simply downloading the source code of the package, not compiled artifacts or code mangled by some build tool before publishing. What this means for you is that any time you click into, say, a function that comes from a third-party package, you're going to be looking at the actual source code — formatting, comments and all.

PHP is Fast

While it's hard to make apples-to-apples performance comparisons between programming languages, and you probably shouldn't be worrying about language runtime performance that much anyway (your code is almost always going to be I/O-bound, after all), it's worth pointing out that modern PHP is very fast, handily beating "slow" languages like Ruby in synthetic benchmarks.

More than anything else, this is thanks to lots of hard work put into improving performance by the PHP team over the years, up to and including adding entirely new features, such as the JIT compiler introduced in PHP 8.

The Ups and Downs of PHP's Unique Execution Model

You might have heard people say that PHP was "doing serverless before serverless was a thing", and this is kind of true.

The way people used to write PHP was they'd have a bunch of PHP files where each file corresponded to a page or route (e.g. index.php for a homepage, item.php for another page, and so on) and output some HTML. Then they'd upload this code to their server — often a shared hosting provider where all a developer had to do was FTP the files up to the server, and it'd just work. The web server would handle all the parts external to your code, like starting up a PHP process for the request and giving it the right script based on the path.

There's a lot of sites on the internet that still work this way, and while PHP has since evolved past some parts of this approach, you can probably see how it resembles some patterns that have become popular in recent years, like filesystem-based routing and serverless functions.

The part of this that's most relevant today is the idea that your app gets initialized and torn down for every request. Any variables you set, anything you do to the objects in your app, everything gets wiped out at the end of the request — there's no way to persist data between requests without relying on some sort of external resource, like a database.

There are naturally some drawbacks to this setup, not the least of which being that it means that putting some data in memory to keep it around for a while is less trivial in PHP than it is in something like Node.js. On the other hand, this setup makes whole classes of bugs impossible at the application level (like meaningful memory leaks), and perhaps more importantly, it means you don't have to worry about writing async code nearly as much as other languages, because you're only ever going to be handling one request per process anyway.

For instance, making an HTTP request is as simple as writing a blocking call to an HTTP client:

use Symfony\Component\HttpClient\HttpClient;

$client = HttpClient::create();
$response = $client->request('GET', 'https://example.com');

$statusCode = $response->getStatusCode();
$content = $response->getContent();

In most other languages, code like this would be a huge no-no because you'd be blocking the runtime from handling any other requests while you wait for that call to HttpClient::request() to finish. In PHP, though, because the assumption that you have the process "to yourself" is built into the language, you can write blocking code like this safely, while avoiding the mental overhead that async code can sometimes involve.

I should probably cap this section off by mentioning that there has been a push in recent years to make asynchronous code viable in PHP, and frameworks like Amp have made significant progress in this area. That being said, the vast majority of PHP code is still synchronous, and will be for the foreseeable future.

Conclusion

If you came into this post with the mindset that PHP is a legacy language nobody in their right mind would want to write code for today, well, I hope I've been able to at least somewhat change your mind on that.

PHP, of course, still has its share of warts, but more than anything else, what I wanted to convey with this post is that it's absolutely possible to write reliable, clean, maintainable code in PHP that you and/or your team will be happy with. Not only that, but there are parts of PHP that you might even prefer to how things work in other languages you're familiar with.

Still not convinced? You're more than welcome to peruse the rest of my site (https://bulletproofphp.dev) to perhaps get a better feel for what real-world PHP looks like, and if you have concerns you think I overlooked in this post, I'd be happy to talk about it on Twitter or in the comments here.

Simple, Privacy-Friendly, and Free Analytics Using Serverless Functions

Lynn Romich — Wed, 14 Apr 2021 23:25:18 +0000

Whether it's for work or play, most of us usually want some analytics on our websites, but the available options typically come with one or more pretty major downsides:

Massive JavaScript payload -- Most of the big analytics products have this problem. gtag.js is ~35kB minzipped, ~90kB uncompressed (at time of writing); some others are even worse. Yes, these days this is loaded asynchronously and doesn't directly hold up your page while it gets loaded and parsed, but that's still an absolutely indefensible amount of overhead just to get some super basic data on how your site is being used.

Privacy implications -- Again, this is one you're almost certainly going to hit if you're looking at a free, hosted analytics product, like Google Analytics or Yandex.Metrica. Third-party cookies may thankfully be going the way of the dodo, but tools like Google Analytics -- if you use the tracking code they give you -- will still insist on giving your users at least first-party cookies they can use to identify them across multiple requests (and visits), regardless of whether you want that feature or not.

From a practical perspective, this means you now need to ask your users to consent to these tracking cookies, and from an ethical perspective, you may just want to avoid tracking your users like this altogether, especially if it means doing it through someone like Google.

Inaccuracy due to people blocking analytics -- Whether it's through privacy-enhancing browser features, browser extensions like uBlock Origin or even something like Pi-hole, lots of people these days are running something that blocks obvious analytics requests. Depending on how privacy-conscious your audience is, as many as ~45% of your visitors could be blocking analytics entirely.

Serverside analytics naturally don't suffer from this problem, and some privacy-focused analytics products like Fathom Analytics and Plausible Analytics give you ways to use your own domain for analytics to avoid being caught by this, but if you're using a typical big-name analytics product (unless you're being particularly clever about it, which we'll get to), this is a huge drawback you're kind of just stuck with.

Cost -- If you're looking to add analytics to something like a personal site, this is probably your biggest problem. Modern, privacy-focused analytics products like Fathom Analytics, Plausible Analytics and Netlify Analytics give you ways to avoid many or even all of the other problems on this list, but they're not free -- and there's nothing wrong with that, but I can't justify paying a monthly subscription just to see how many people read my blog posts, and you probably can't either.

One way to get around this could be self-hosting an open-source analytics product like Matomo Analytics, but unless you already have somewhere you can put that without incurring any extra costs, that costs money, too.

That being said, if you're looking for an analytics solution for your business or something else that actually makes money, I think you should strongly consider just paying for one of these products and being done with it.

Enter Serverless

Okay, so what can we do about this? Well, we can be smart about the way we use analytics, and take control of how our analytics are collected while still leaving the bulk of the work to a third-party analytics product (if we want to).

How do we do that? With a serverless function.

More specifically, here's what this approach entails:

1. Write a serverless function that takes an analytics event -- whatever that means to you -- and pipes it wherever you want. This gives you complete control over what and how much data you send, what you do with it before sending it to a third party, and where it ends up.

The most immediately useful thing you could do here is pipe the event to a traditional analytics product like Google Analytics (giving you the benefits of a proper analytics product without many of the downsides we talked about), and I imagine this is what most people will want to do, but the place you store your events can be literally anything -- a log file, a database you can later build your own analytics tools on top of, hell, it could even be a spreadsheet.

You could also do stuff like pipe events to your own database while still sending them to Google Analytics, so you still own all of your data if you ever want to do something with it that Google Analytics doesn't let you do.

2. Write a tiny bit of clientside code (which, again, you now have complete control over) to send events to your analytics function.

If we go over those downsides we mentioned at the start of this post again, we can see that this approach allows us to pretty much completely sidestep them:

Massive JavaScript payload -- There is none, our clientside code can be as simple as a single fetch() call.
Privacy implications -- More-or-less none, we don't have to track anything we don't want to. Google will still have your data if that's where you choose to pipe it, but there's not a lot they can do with it if it's all anonymized and not tied to a specific user in any way (though you can still do that if you want to, of course).
Inaccuracy due to people blocking analytics -- Our analytics requests won't be blocked because they're not tied to a known analytics product. As long as we don't do something like use the word analytics in the name of our endpoint, they'll just look like any other request.
Cost -- On the analytics side this allows us to use free products like Google Analytics without many of the downsides they usually come with, and as for our serverless function, chances are you won't ever have to pay a dime to run it with how generous pretty much every platform's free tier is. For instance, AWS Lambda gives you one million free requests every month (at time of writing).

What This Looks Like in Practice

I have to stress that this post is much more about the general concept than it is about a specific implementation -- you don't have to do anything here the same way I did it. That being said, I'm including an example of how I implemented this pattern for my own website (veselin.dev) because I think it'll be helpful, and because I think my usecase is common enough that many people should be able to take what I did here and carry it over to their own website(s) with few or no changes.

Here's my analytics function. It's a Netlify Functions function that mostly just proxies events to Google Analytics using the Measurement Protocol (note: I'm using Universal Analytics here because the Measurement Protocol for GA4 is still in alpha). It anonymizes IP addresses before sending them to Google (though it also enables Google Analytics' IP anonymization feature that does the same thing, because why not), and sidesteps Google's requirement of a user identifier (a cid or uid) by just generating a new one for every event.

import { Handler, APIGatewayEvent } from "aws-lambda"
import axios from "axios"
import { URLSearchParams } from "url"
import * as uuid from "uuid"
import anonymizeIP from "ip-anonymize"

interface RequestBody {
  type: "pageview" | "event"
  params: any
}

interface Response {
  statusCode: number
}

const handler: Handler<APIGatewayEvent, Response> = async event => {
  const body: RequestBody = JSON.parse(event.body)

  const analyticsRequestBody = new URLSearchParams()
  analyticsRequestBody.append("v", "1")

  // enable IP anonymization, even though we're doing it here anyway
  analyticsRequestBody.append("aip", "1")

  // GA makes us send a cid parameter, so we send a new UUID every time
  // because we don't actually want to track users across requests
  analyticsRequestBody.append("cid", uuid.v4())

  // Override user agent
  analyticsRequestBody.append("ua", event.headers["user-agent"])

  // Override user IP (but anonymize it first)
  analyticsRequestBody.append("uip", anonymizeIP(event.headers["client-ip"]))

  // Set event data

  analyticsRequestBody.append("tid", process.env.GOOGLE_ANALYTICS_TRACKING_ID)
  analyticsRequestBody.append("t", body.type)

  for (const paramName in body.params) {
    analyticsRequestBody.append(paramName, body.params[paramName])
  }

  // Send event to Google Analytics

  await axios.post(
    "https://www.google-analytics.com/collect",
    analyticsRequestBody.toString()
  )

  return { statusCode: 200 }
}

export { handler }

For the time being I'm happy with this solution, but you could expand on this by implementing something like Plausible's daily identifier method (described here) to anonymously identify unique users, and sending that to Google as your uid. (Update: I've since published anonymous-user-id, an npm package that helps you do this!)

My clientside code is basically a single fetch() call that sends the same data Google Analytics usually sends for a pageview event. You'll want to put this code somewhere it'll be called both on the initial pageload and whenever the user navigates to a different page -- in my case, that's Gatsby's onRouteUpdate hook.

if (process.env.NODE_ENV !== `production`) {
  return null
}

const sendPageView = () => {
  const pagePath = location
    ? location.pathname + location.search + location.hash
    : undefined

  fetch("/.netlify/functions/event", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "pageview",
      params: {
        dh: window.location.hostname,
        dp: pagePath,
        dt: document.title,
        dr: document.referrer,
      },
    }),
  })
}

// wrap inside a rAF to make sure react-helmet is done with its changes
// (https://github.com/gatsbyjs/gatsby/issues/11592)

if (`requestAnimationFrame` in window) {
  requestAnimationFrame(() => {
    requestAnimationFrame(sendPageView)
  })
} else {
  // simulate 2 rAF calls
  setTimeout(sendPageView, 32)
}

I'm not sending any custom events on my site right now, but those would be handled similarly. If you use analytics heavily on your site, you'll probably want to extract this code into a utility function rather than duplicating it every time you want to send an event.

Why Serverless?

You wouldn't be wrong to notice that everything we're doing here could be implemented just fine in a traditional backend architecture. So, why am I focusing on serverless specifically? Well, there's a few reasons:

More and more sites (like the one I talk about in my example!) are being built on Jamstack or serverless architectures without a traditional backend. Using a serverless function for this works equally well regardless of what your existing stack is.
Even if you have an existing backend you could integrate this functionality into, using a serverless function has the benefit of ensuring that you don't have to worry about the performance impact of handling all these extra requests that would typically be handled directly by a third-party service.
While this isn't a usecase I talk about a lot in this post, a serverless function not tied to an existing backend is easier to use to collect events from a bunch of different places at once.
Circling back to the Jamstack point again, serverless functions are inherently infinitely scalable. If you have a site deployed to something like a CDN -- where your site will never get hugged to death -- the last thing you want to have to worry about is whether your analytics can keep up with your traffic.

That being said, of course you could apply all of these ideas to a traditional backend, too. I just focus on serverless as a solution in this post because I think it's a great fit for this usecase.

The Ethics of Circumventing Blockers

To address a bit of an elephant in the room, yes, a significant part of why this pattern is useful is that it allows you to do analytics for users running browser extensions or other tools that would typically block them.

My opinion on this overlaps significantly with Fathom's answer to this question in their post announcing their custom domain feature (which is explicitly designed to do this) -- I don't believe this is unethical because the reason people block analytics is that they're traditionally extremely invasive, and if you're doing what I've described here, you're doing everything possible to protect your users' privacy.

Or, to put it a different way -- you're not collecting any more data than serverside analytics would be, and nobody thinks serverside analytics are unethical because they can't be blocked by a browser extension, right?

That being said, it's possible to use the techniques I've talked about here in an unethical way, for example by proxying requests to Google Analytics through your own domain, but not doing anything to mitigate the privacy concerns of using Google Analytics. All I can do there is ask that you please don't do that.

Conclusion

That's pretty much it! I'm very curious to see how many other people have stumbled their way into similar solutions before (I know I've seen stuff like people proxy_passing requests to Google Analytics with nginx to make them less obvious), and I'm also curious to see if anyone comes up with more creative ways of building on top of this concept than just piping events to Google Analytics.

PHP Debugging With Xdebug 3 Inside a Docker Container

Lynn Romich — Tue, 13 Apr 2021 02:17:27 +0000

I recently spent a good few hours getting Xdebug to work with my development setup (which is PhpStorm running inside WSL 2 on Windows 10, and PHP/Xdebug running inside a Docker container, inside WSL 2, with Docker Desktop), so here I am writing up the surprisingly simple solution I ended up with -- partially for my own future reference, but also to help out anyone who finds themselves in a similar situation.

(Don't get discouraged by my ultra-convoluted setup -- this configuration should actually theoretically work for pretty much any environment, for reasons I'll get into a little later on.)

Preamble

Xdebug can be tricky to configure, because it works in reverse from the way you're probably used to interacting with your PHP application -- instead of sending requests to your PHP code, Xdebug needs to know how to send requests from where your code is running to your client application (i.e. probably your editor or IDE), in order to establish a debugging connection.

This is fine if your setup is relatively simple (i.e. Xdebug can just go to localhost:9003 and hit your client), but if your setup is a little more complicated than that -- i.e. if PHP/Xdebug is running on a different physical machine, in a VM, in a container, or similar -- it won't work out of the box.

Xdebug 3 makes this whole exercise a little easier for us by generally overhauling the way Xdebug is configured to make it simpler, but if your setup is a little convoluted (like mine), it can still be finicky to get right, hence this post.

The Meat and Potatoes

Okay, so here's what I ended up with.

This is the bit you need to put somewhere in your PHP configuration (i.e. your php.ini, or wherever you usually configure your PHP extensions):

[Xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.discover_client_host=true
xdebug.client_host=host.docker.internal

Let's go over this line-by-line:

xdebug.mode=debug enables step debugging (which is probably what you want to use Xdebug for.)

xdebug.start_with_request=yes tells Xdebug that we want to activate step debugging at the start of every request, for simplicity's sake. I recommend setting this to yes and forgetting about it, but if you've done this before and you know you prefer to activate step debugging only for specific requests, leave this line out and Xdebug will default to trigger.

The last two lines are where it gets interesting. xdebug.discover_client_host=true tells Xdebug to attempt to extract the IP of the client from the HTTP request, and xdebug.client_host tells it what to try if that doesn't work.

With all of these set the way we've set them, here's what happens every time you send a request to your PHP application:

Xdebug activates step debugging (because our xdebug.mode is debug, and xdebug.start_with_request is set to yes).
Xdebug attempts to automatically connect to the host the HTTP request came from (using $_SERVER['REMOTE_ADDR'], $_SERVER['HTTP_X_FORWARDED_FOR'], or a custom HTTP header you've configured).
If the above didn't work, it falls back to trying to connect to our xdebug.client_host, which is host.docker.internal, a DNS name for the host helpfully set for us by Docker Desktop on Windows or macOS (though unfortunately not on Linux).

The fact that Xdebug lets us set both xdebug.discover_client_host and xdebug.client_host as a fallback is the key to making this configuration work for just about any setup, whether you're on Linux, macOS or Windows, and even whether you're using Docker or not.

If you're using Docker Desktop, having host.docker.internal set as a fallback host means Xdebug will always be able to find its way to the host, and on most other setups, client discovery (via xdebug.discover_client_host) should just work. Theoretically, the only scenario this config should break in is if you're using something that breaks client discovery that isn't Docker (e.g. a Vagrant virtual machine), in which case there's probably something else you can set xdebug.client_host to to fix it.

Installing Xdebug in Your Docker Image

If you're using Docker (and if you're not, I highly recommend thinking about it!), the below is an example of what I do to install and enable Xdebug in development without carrying it over to the production image, using multi-stage builds:

# (or your base image)
FROM php:8.0-fpm-alpine as base

# whatever you do to set up your image
# for example:
#   - copying your source code
#   - installing extensions
#   - doing a `composer install`

FROM base as development

RUN pecl install xdebug && docker-php-ext-enable xdebug

FROM base as production

# whatever you do to prepare your image for production
# for example: removing packages you don't need in production

Conclusion

That's it! You should now have an Xdebug config that works for everything from Docker Desktop to just running PHP on the same Linux machine as your editor.

If you're using this config and you've found a setup it doesn't work for, please yell at me on Twitter and I'll probably add a note to this post!

On Docs, DX, and Developer Happiness

Lynn Romich — Sat, 31 Aug 2019 23:06:37 +0000

(This post was originally published on my blog.)

One thing I've increasingly taken notice of recently is that a lot of developers, especially in corporate environments, seem to tend to put a very low priority on the DX of their projects. Documentation is poor or non-existent; setting up a working development environment is like pulling teeth. You've got tickets to close and you're sure they'll figure it out, so who cares, right?

To be clear -- I totally understand why this happens, and I'm not here to judge anyone who might've recognized some of their own projects in that description. I do, however, strongly believe that you should care, and I'm here to tell you why.

A Little Work Now = A Lot Less Work Later

Think about how many times in your life you're going to find yourself setting up a local dev environment for a given project. At the very least, you're probably going to do it every time you get a new dev machine and git clone all the stuff you're working on, right? You're also going to do it every time you help someone do the same, e.g. a new person on your team.

If your project is a pain to set up, that quickly adds up to a lot of unnecessary frustration and wasted time. Doing this by hand is also bound to breed subtle inconsistencies in each environment, potentially leading to bugs.

On top of that, if running your app involves more than a single command (e.g. you need to run a web server and something like a module bundler), you have to remember to do this every single time you work on it.

Automate, Automate, Automate

Okay, so we're aware that some of our processes may be inefficient. How do we fix it?

The absolute best way you can choose to deal with this issue is by codifying your app's environment and other setup into some sort of automated tooling that can do all of this for you. Luckily, we live in the age of Docker and containerization, which means the tools for this we have at our disposal today are immensely more powerful than they were barely a few years ago.

This post isn't really the place for a deep dive into using Docker as a development environment, but the gist of what you want to do is:

Use a Dockerfile to codify as much as you can about the immediate environment your app needs to run -- this should include things like your language runtime, any binaries it needs (e.g. imagemagick), config files, and so on.
Use a docker-compose.yml to codify as much as you can about your app's external dependencies, such as cache servers, database servers, mail servers, and so on.

This will undoubtedly take some time, especially so if you first have to take the time to understand what this Docker thing is all about. Once everything's said and done, however, if you did everything right, you'll have reduced the process to set up a working instance of your app to this:

git clone <your-repo> .
docker-compose up

On top of that, if you've already done this once, it'll take you a lot less time to do it in the future -- especially if your apps share a common stack. It takes me maybe an hour to set all this stuff up for a typical new project these days.

Learning by Example

If the above seems a little too abstract, let's look at a simple example of a docker-compose.yml you could use for a WordPress project.

version: '3'

services:
  wp:
    image: wordpress:latest
    ports:
      - 8080:80
    volumes:
      - ./wordpress:/var/www/html:rw
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_DB_USER: root
      WORDPRESS_DB_PASSWORD: password
    depends_on:
      - db
    links:
      - db

  db:
    image: mysql:latest
    ports:
      - 3306:3306
    command: [
      '--default_authentication_plugin=mysql_native_password',
      '--character-set-server=utf8mb4',
      '--collation-server=utf8mb4_unicode_ci'
    ]
    environment:
      MYSQL_DATABASE: wordpress
      MYSQL_ROOT_PASSWORD: password

It's self-explanatory enough -- The wp service is the actual WordPress site, and the db service is a MySQL database (what we called an "external" dependency above). For the purposes of this example, this is all we need to get us to a point where you can just do a docker-compose up to run the project.

Now, you'll notice that I didn't provide a Dockerfile -- That's because, in this instance, the official wordpress image does all we need. For a more complex project, however (or if you wanted to deploy a Docker image to production, too), you'd probably want to write a Dockerfile that extends the official image.

A Word of Warning

This is a bit of a tangent in the context of this article, but one thing about Docker that I really need to mention, but nobody ever seems to talk about, is that the way you want to use Docker differs pretty significantly depending on whether you're using it for development, or deploying Docker images to production.

The main thing it comes down to is where your code is. Take the volume mounted onto the WordPress container in the example above:

volumes:
  - ./wordpress:/var/www/html:rw

The WordPress code on your host machine is mounted onto the container -- Any changes you make to it will immediately be reflected in your running app.

On the other hand, if you're building an image to deploy to production, you have to copy your code into your image at build time, so that it's self-contained, and so that it can do anything it needs to do with your code at build time (building binaries, module bundling, etc.).

I find it really important to point out this distinction whenever I get the chance to, because for some reason, a lot of high-profile tutorials out there will have you make a "development" Docker setup that has you rebuild your image every time you want it to reflect the changes in your code, even though this is totally impractical if you're actually using Docker as your dev environment. I dread to think how many people have given up on using Docker for development because they found the idea of constantly rebuilding your app ridiculous (and rightfully so).

Another thing worth mentioning is that, depending on your stack, you may need to have separate images for development and production (you can use multi-stage builds to do this without having to maintain multiple Dockerfiles). PHP, for instance, doesn't care -- you're using the exact same code and runtime in every environment. On the other hand, if you're using something like a static site generator, or a language like Go that doesn't have an external runtime, your production image is going to need to be much more lean than the one you use for development.

Automation Isn't Everything

We've just spent a bunch of time talking about Docker and Docker Compose, and while containerizing your app absolutely makes a huge difference and is probably the single most helpful thing you can do to improve the onboarding experience, we should take a moment to remember that reducing your setup to a docker-compose up isn't the be-all and end-all of making your app friendly to work with.

Here are a few other things to keep in mind.

If your app or library has any sort of public API, you must make it easy for people to see what it actually is; expecting people to dive into your code doesn't count. For HTTP APIs, tools like the OpenAPI spec and Swagger UI make it easy to automatically generate API docs and expose them in a friendly way; use them.
Even if you've simplified your dev environment setup and documented any public APIs you may have, there's probably still a bunch of stuff you could put in your README. What is this app? Who's it for? What standards/protocols does it implement? Is it a monorepo, or are there other projects one should look at to get the full picture? Hell, take a screenshot (if applicable) and put it at the top of the README. The more context people can glean from your docs, the better.
If you can't go the full-on containerization route for whatever reason (please make the effort to try, though!), make sure all the steps one needs to go through to set up a dev environment for your app are well-documented. Don't assume people will just know what to do with your code, even if your app uses a similar stack to other projects in your team or company.

Think Like a FOSS Maintainer

To conclude this post, I think the single most important piece of advice I can give on this topic is -- Think like a FOSS maintainer. Pretend for a second that you're not developing an internal project that people are obligated to use, but a personal open-source project nobody will ever use if the DX is poor and the extent of your docs is a near-blank README.

To an extent, you don't even have to pretend -- Yeah, of course you don't have to sell people on your project if they're obligated to work with it, but that doesn't mean the atittude you take towards the stuff in this post doesn't matter. Making the effort to make your coworkers' jobs easier makes a huge difference in how they see you, your project, your team, and even affects the culture of the company as a whole.

To be blunt, animosity between teams can grow from the most trivial of things; we have to make the extra effort to extend that olive branch when we can.

The way I personally see this (with the disclaimer that this is absolutely my personal opinion -- I can hardly pretend to speak for everyone) is that making sure your projects are well-documented is just a sign of basic respect towards your fellow devs. I wouldn't dream of making someone bang their head against a wall trying to work on a project of mine just because I couldn't be bothered to write proper docs.

Recap

Let's go over the important stuff one more time:

Do your best to automate your dev environments. This makes as much of a difference for you as it does for everyone else, especially if you switch between projects a lot.
Document your APIs. If you maintain an API other people are supposed to use, you can't expect them to dive into your code to understand it.
Put everything in your READMEs. The more comprehensive your docs are, the less often you'll have people tapping you on your shoulder to ask you things.
Think like a FOSS maintainer. Sell people on using your project, even if you don't have to.

And, of course: Be excellent to each other.