The billed talk description:
Refactoring is often seen as a low-priority, time-intensive chore. Delegating refactors to an LLM is an option, but the PHP ecosystem offers some incredible tools that can automatically refactor your Laravel codebase with more confidence. Greg will showcase these tools and explain how you can get up and running with them

There’ll be plenty about Rector, PHPStan, and lessons I’ve learnt from trying to refactor codebases of varying ages and quality. If you’re interested in coming, you can RSVP on Meetup. There will also be a talk about mutation testing by Craig Duncan-Courcey.

I don’t get opportunity to play around with front-end tooling much in my day-to-day work as of late. I try to use this blog as an excuse to better familiarise myself with Tailwind. I didn’t know much about Jekyll when I first set up this blog, so I followed the recommended approach for installing Tailwind with Jekyll and went down the PostCSS route. I used the jekyll-postcss Ruby gem to have it integrate seemlessly with Jekyll.

When I saw that Tailwind v4 had been released, I figured I’d take the time to upgrade to it. At the time of writing, the jekyll-postcss gem hadn’t been updated for almost 4 years. I assumed that this wouldn’t be an issue because Tailwind v4 still supports PostCSS. As you might have guessed, I assumed wrong.

I bumbled along with the Tailwind v4 upgrade path. I ran the Tailwind upgrade tool (which is awesome) and it did 90% of the work, but it wouldn’t touch my PostCSS configuration file as it contained “dynamic JavaScript”. The upgrade guide mentions changing your postcss.config.mjs to be something like the below:

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  }
};

There’s just one problem there, my PostCSS configuration was a .js file with a CommonJS-style export statement. Before entertaining the idea of converting the file to be an .mjs file, I tried replacing require('tailwindcss') with require('@tailwindcss/postcss') in my postcss.config.js file, but I received the following error:

PostCSS Error!

Error: Can't resolve 'tailwindcss' in '/home/greg/Projects'
...
details: "resolve 'tailwindcss' in '/home/greg/Project Parsed request is a module"

The problem was likely that I was trying to require an ECMAScript module inside a CommonJS-style configuration file. I probably should have investigated it more, but I simply couldn’t be bothered. I then took the logical step of trying to convert the config file to be an .mjs file but immediately ran into another issue. The jekyll-postcss gem only supports a postcss.config.js file and it doesn’t allow for any kind of filename override.

I have an extremely low tolerance to productivity blockers. I want to be able to keep my tools on the latest versions with as little friction as possible. I don’t want to clear this hurdle and then have similar problems when the next major Tailwind version is released. Dependencies are great until they’re not. I made the decision to rip everything PostCSS out of my blog and replace it with the first-party Tailwind CLI. In Tailwind v3, the CLI tool is installed by default, but in v4 you have to explicitly install it.

Removing PostCSS

Because I was using jekyll-postcss, when I ran bundle exec jekyll serve it would also start a PostCSS “server” that would react to file changes. It would be great to have this level of Jekyll integration with the Tailwind CLI, but for now, I’m content to settle for an npm command that starts a Tailwind CLI watcher.

I removed the jekyll-postcss gem from my Gemfile as well as any mentions of PostCSS from my _config.yml file. I also removed the postcss, autoprefixer, and cssnano packages from my package.json. The Tailwind CLI handles vendor prefixing and minification, so I didn’t need those packages anymore.

Jekyll recommends the use of an assets directory to signify which assets (CSS, JS, images, etc.) should be brought across into the build. jekyll-postcss instructs you to append an empty front matter block at the top of your .css file(s) to denote that they should be processed by Jekyll. In my case, I had a assets/css/main.css file. I also had a syntax.css file which contained the styles for my code blocks, but I decided to fold it into main.css.

When using the Tailwind CLI, you don’t need the front matter in the raw or transpiled .css file because you don’t want it to be transformed by Jekyll, only moved over as is. I made a _src/css/ directory and popped my main.css file in there. I set the whole of the _src directory to be excluded by Jekyll, which means it won’t end up in the built version. I also made sure to add assets/css/main.css to my .gitignore file as it will always be a build process artifact.

I created the below npm commands to make my life easier for both development and production. I thought about making a dev command that would run jekyll:dev and tailwind:dev concurrently, but it’s not exactly arduous to open two terminal panes.

"scripts": {
  "jekyll:dev": "bundle exec jekyll serve",
  "tailwind:dev": "npx tailwindcss -i ./_src/css/main.css -o ./assets/css/main.css --watch",
  "tailwind:prod": "npx tailwindcss -i ./_src/css/main.css -o ./assets/css/main.css --minify"
}

Aftermath

Doing this migration meant that I was able to upgrade to Tailwind v4 via the migration tool, with only a couple of manual changes. I was able to drop 1 Ruby gem and 3 JavaScript packages. I did have to install the @tailwindcss/tailwind-cli package, but this feels like more of a technicality as it was previously included in Tailwind v3.

I don’t know how useful this blog post is, but maybe it’ll help other people who use Tailwind on their Jekyll blogs.

protected function setUp(): void
{
    static::$latestResponse = null;

    Facade::clearResolvedInstances();

    if (! $this->app) {
        $this->refreshApplication();

        ParallelTesting::callSetUpTestCaseCallbacks($this);
    }

    $this->setUpTraits();

    foreach ($this->afterApplicationCreatedCallbacks as $callback) {
        $callback();
    }

    Model::setEventDispatcher($this->app['events']);

    $this->setUpHasRun = true;
}

The setUp method inside that class is responsible for booting the Laravel framework in tests via the refreshApplication method. As data providers are executing before that setUp method has been called, you’re not going to have access to Laravel functionality such as facades and model factories at that point. You might think that this is the end of the road for using model factories inside your data providers. Fear not, there’s a neat trick that you can use to get around this limitation. If you wrap the provider’s data set within a closure, this will cause the expression to be evaluated lazily.

<?php

namespace Tests\Feature;

use App\Models\User;
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\Attributes\Test;
use Tests\TestCase;
use Closure;
use Generator;

class UserTest extends TestCase
{
    #[Test]
    #[DataProvider('singularUserProvider')]
    public function testing_a_single_user_model(Closure $userClosure): void
    {
        $user = $userClosure();

        $this->assertInstanceOf(User::class, $user);
        $this->assertSame('Greg Mayes', $user->name);
    }

    #[Test]
    #[DataProvider('multipleUsersProvider')]
    public function testing_multiple_user_models(Closure $usersClosure): void
    {
        foreach ($usersClosure() as $user) {
            $this->assertInstanceOf(User::class, $user);
            $this->assertNotEmpty($user->name);
        }
    }

    public static function singularUserProvider(): Generator
    {
        yield [static fn (): User => User::factory()->make(['name' => 'Greg Mayes'])];
    }

    public static function multipleUsersProvider(): Generator
    {
        yield [
            static fn (): array => [
                User::factory()->make(['name' => 'Greg Mayes']),
                User::factory()->make(['name' => 'Joe Bloggs']),
            ]
        ];
    }
}

The above approach does have the downside of requiring you to invoke the Closure inside the body of your test, but it’s a relatively small price to pay. For the sake of completeness, I’ve included examples of returning a singular User model in a data set as well as returning an array of User models.

If you want to learn more about PHPUnit data providers outside of the previously linked documentation, then I would highly recommend this blog post by Matt Barlow.

I’ve used the str_repeat function in the example below but it could have been another internal PHP function or a globally scoped function declared in something like a helpers.php file.

<?php

namespace Foo\Bar\Baz;

use function str_repeat;

echo str_repeat('teststring', 3);

I’m going to run the code snippet through an Opcode dumper called Vulcan Logic Dumper (VLD). If you’d like to play around with VLD without installing it on your local environment, you can easily run it using 3v4l.org. After you eval(); your code, you should see a tab called ‘VLD’ at the top of the results box. You can also look at the performance metrics of the executed code by using the ‘Performance’ tab.

In the Opcode dump below, we can see that on line 0 that there’s an INIT_FCALL Opcode for the invocation of str_repeat. On lines 1 and 2, there are SEND_VAL Opcodes on for passing the arguments to the function.

number of ops:  6
compiled vars:  none
line      #* E I O op                           fetch          ext  return  operands
-------------------------------------------------------------------------------------
    7     0  E >   INIT_FCALL                                               'str_repeat'
          1        SEND_VAL                                                 'teststring'
          2        SEND_VAL                                                 3
          3        DO_ICALL                                         $0      
          4        ECHO                                                     $0
          5      > RETURN                                                   1

You might think that this is how it always looks when you call a function such as str_repeat within namespaced code. However, that INIT_FCALL Opcode is only being used here because of the explicit importing of str_repeat function from the global namespace. This would also be the case if you removed the use function statement and called the function as \str_repeat('teststring', 3) instead.

If I run that snippet again without the import, I get slightly different results this time. The Opcode on line 0 in the below dump is now INIT_NS_FCALL_BY_NAME rather than INIT_FCALL. This means that PHP is looking for the function str_repeat inside the namespace Foo\Bar\Baz, which we know doesn’t exist. It will then traverse the namespace tree (Foo\Bar, Foo) until it hits the global namespace and finds the internal PHP function str_repeat. The performance implications of this are hard to quantify and will vary greatly depending on your application, but I think we can all agree that fewer operations to produce the same result is preferable.

number of ops:  6
compiled vars:  none
line      #* E I O op                           fetch          ext  return  operands
-------------------------------------------------------------------------------------
    5     0  E >   INIT_NS_FCALL_BY_NAME                                    'Foo%5CBar%5CBaz%5Cstr_repeat'
          1        SEND_VAL_EX                                              'teststring'
          2        SEND_VAL_EX                                              3
          3        DO_FCALL                                      0  $0      
          4        ECHO                                                     $0
          5      > RETURN                                                   1

Avoiding namespace traversal is just one reason to import global functions within namespaced code. I’ll explore the other reason by calling the strlen function with an explicit import; I’ve made a crude example function called isGreaterThanFiveCharacters that returns whether an ASCII string is greater than 5 characters or not.

<?php

namespace Foo\Bar\Baz;

use function strlen;

function isGreaterThanFiveCharacters(string $input): bool
{
    return strlen($input) > 5;
}

isGreaterThanFiveCharacters('test string');

On line 1 of the below Opcode dump, the Opcode is STRLEN rather than INIT_FCALL. This is because strlen is one of a limited number of internal PHP functions that have their own Opcodes. The STRLEN Opcode means that rather than the Zend Engine having to call a function to calculate the length of the string, it can instead access the len property from the zend_string struct. To my knowledge there isn’t an official list of the internal functions that have an accompanying Opcode, but this method from PHP-CS-Fixer looks to cover them all.

function name:  Foo\Bar\Baz\isGreaterThanFiveCharacters
number of ops:  7
compiled vars:  !0 = $input
line      #* E I O op                           fetch          ext  return  operands
-------------------------------------------------------------------------------------
    7     0  E >   RECV                                             !0      
    9     1        STRLEN                                           ~1      !0
          2        IS_SMALLER                                       ~2      5, ~1
          3        VERIFY_RETURN_TYPE                                       ~2
          4      > RETURN                                                   ~2
   10     5*       VERIFY_RETURN_TYPE                                       
          6*     > RETURN                                                   null

What if I was to run the isGreaterThanFiveCharacters function again, but this time without importing the strlen function?

function name:  Foo\Bar\Baz\isGreaterThanFiveCharacters
number of ops:  9
compiled vars:  !0 = $input
line      #* E I O op                           fetch          ext  return  operands
-------------------------------------------------------------------------------------
    5     0  E >   RECV                                             !0      
    7     1        INIT_NS_FCALL_BY_NAME                                    'Foo%5CBar%5CBaz%5Cstrlen'
          2        SEND_VAR_EX                                              !0
          3        DO_FCALL                                      0  $1      
          4        IS_SMALLER                                       ~2      5, $1
          5        VERIFY_RETURN_TYPE                                       ~2
          6      > RETURN                                                   ~2
    8     7*       VERIFY_RETURN_TYPE                                       
          8*     > RETURN                                                   null

I now get the INIT_NS_FCALL_BY_NAME Opcode instead of STRLEN, followed by SEND_VAR_EX and DO_FCALL. Huh, what’s going on here? Well, it turns out that internal PHP functions with accompanying Opcodes are only able to utilise them inside a namespace if the function has been imported or has been fully-qualified. This mechanic doesn’t apply to non-namespaced code, where the aforementioned functions will always use their accompanying Opcodes.

If you were to call that isGreaterThanFiveCharacters function hundreds of thousands of times in a performance sensitive loop inside namespaced code without having imported strlen, you’re going to suffer two performance penalties. The first being that your application is going to spend time needlessly traversing namespaces to find strlen. The second is that PHP will have to invoke the strlen function each time, when it could get the len property from the zend_string struct instead, and skip the function call entirely.