DEV Community: Peter Fox

Mastering PHP: Type Hinting techniques

Peter Fox — Fri, 27 Sep 2024 17:01:44 +0000

Photo by 𝓴𝓘𝓡𝓚 𝕝𝔸𝕀 on Unsplash

Type hinting is considered by some to be the holy grail of features. One that all programming languages must have. PHP for the longest time didn’t have such a system but has now been adopted widely by most developers.

That said, PHP’s type system doesn’t go as far as other languages. Many implement what are known as Generics. This is the ability to enforce a type among structures and Collections. For instance, in Java we can specify that Arrays must only contain items of a certain type, for example, an Array of Strings.

Maybe someday we’ll have this functionality in PHP as well, but until then we can actually solve this with a few different techniques. For a lack of a better description, I refer to these as Soft Type hints and Runtime hints.

Type Hints

The first and most obvious type hints are the ones introduced in PHP 7 and are still being added to PHP. Type-hinted constants were only added in PHP 8.3.

Type hints are useful to help convey what needs to be passed to a method or function as a parameter or what that method will return. Type hints are going to affect the signatures of any classes they use them with as extending a class with type hints already established will mean they can’t be overridden.

An example of a class that makes full use of types would be:

<?php

class Foo
{
    public function bar(array $strings): \Closure
    {
       return function (string $string) use ($strings): bool {
           return in_array($string, $strings);
       };
    }
}

There are, of course, limitations in our type hints because as previously mentioned, we can’t conform an array to be all of the same type and instead we must just use array . We also can’t constrain numbers to being only positive or within a certain range.

Another one can be Closures as there’s no way to describe anonymous functions within PHP’s native types. Instead, we must either use \Closure or callable . Often callable isn’t allowed to be used as a type as well.

Luckily, there’s still a way to describe these more complicated scenarios with type hints.

Soft Type Hints

Our next kinds of type hints are supplied via PHPDocs. While native types will throw exceptions during run time if a method is passed or returns the wrong type, PHPDoc type hints have no effect on the runtime of the application.

Instead, soft type hints help us purely when we’re using an IDE such as VS Code or PHPStorm, which will detect those types for us. The other use case is with static analysis tools like PHPStan and subsequently Rector.

The biggest advantage of using soft types is that it allows you to describe with more precision the type of any parameters, properties, etc. For instance, we can take the previous class and make it easier to understand the arrays or closures used.

<?php

class Foo
{
    /**
     * @param string[] $strings
     * @return \Closure(string): bool
     */
    public function bar(array $strings): \Closure
    {
       return function (string $string) use ($strings): bool {
           return in_array($string, $strings);
       };
    }
}

The best way to make sure all your type usage is correct is to install PHPStan. From there you’ll likely need to use at least level 5. This can then be enforced through continuous integration steps that check the type hinting is correct.

There’s actually a list you can use if you want to use the correct soft type hint. Even better, there’s a PHPStan tool you can use to test if all the type hinting it correct per PHPStan if you’re unsure and want to run a quick test.

Runtime Hints

Our next way of supporting types is to use runtime hints. What this actually means is executing our own code to check the types from parameters. For instance, we can check if an array only contains a particular type of object. If it doesn’t, then we throw an InvalidArgumentException.

<?php

/**
 * @param string[] $foo
 */
function bar(array $foo) {
    foreach ($foo as $string) {
        if (! is_string($string)) {
            throw new \InvalidArgumentException('foo contains non-string value');
        }
    }

    // rest of the code
}

By the way, this technique is sometimes referred to as defensive programming. Looking at the code example, this is pretty cumbersome. It’s a lot of code just to simply check if an array is correct. That’s why we often resort to a library instead, in this case webmozart/assert .

composer require webmozart/assert

Now with this package installed we can shorten this down to a simple one-liner.

<?php

use Webmozart\Assert;

/**
 * @param string[] $foo
 */
function bar(array $foo) {
    Assert::allStrings($foo);
}

One of the great things about this library is if you add the Assert extension to PHPStan, this will help your type coverage when the code is analysed.

Conclusion

In conclusion, mastering type hinting in PHP is an essential skill for developers looking to write clean, maintainable, and reliable code. While PHP’s type system still lacks some features found in other languages, such as generics, there are multiple strategies available to enforce stricter typing — whether through native type hints, PHPDoc annotations, or runtime checks. Leveraging tools like PHPStan and libraries like Assert can help you ensure type safety, even in complex scenarios. By integrating these techniques into your development workflow, you’ll be better equipped to handle PHP’s dynamic nature with confidence and precision.

I’m Peter Fox, a software developer in the UK who works with Laravel. Thank you for reading my article, I’ve got many more to read at https://articles.peterfox.me. I’m also now Sponsorable on GitHub. If you’d like to encourage me to write more articles like this please do consider dropping a small one-off donation.

PHP Upgrades: Block regressions with PHPStan

Peter Fox — Tue, 17 Sep 2024 22:17:58 +0000

Photo by Ron McClenny on Unsplash

Often when people think of PHPStan they typically think of improving Type Coverage. That is really only a small part of what PHPStan is capable of. In this article we’ll learn how to use it to stop upgrade regressions.

What is an upgrade regression?

An upgrade regression is when you have functionality in your application that you wish to move away from. This could be code within your application or code within a dependency you’ve installed.

Often when trying to perform upgrades we can’t do it all in one go. Instead we have to make small incremental changes. Equally as we do this we don’t want other developers to continue to use deprecated methods and properties. In this situation those new method calls etc. are regressions in your progress to upgrade your application.

Installing PHPStan and the Deprecation Rules extension

To start tackling upgrade regressions, the first step is to install PHPStan if you haven’t already. You can install it via Composer:

composer require --dev phpstan/phpstan

Next, you’ll want to add the Deprecation Rules extension, which specifically helps track the usage of deprecated methods, properties, and classes in your codebase:

composer require --dev phpstan/phpstan-deprecation-rules

Once installed, you can configure PHPStan to use the deprecation rules by adding it to your phpstan.neon configuration file:

includes:
    - vendor/phpstan/phpstan-deprecation-rules/rules.neon

Running PHPStan with this setup will now flag any deprecated methods, properties, or classes in your codebase. This is an essential step in preventing upgrade regressions as you’ll be notified when deprecated code is used. You can then refactor those instances to ensure your application moves towards newer, supported functionality.

Go further with the Disallowed Calls extension

While the Deprecation Rules extension catches deprecated code, the Disallowed Calls extension offers a way to block specific function calls, method calls, or even entire classes that you no longer want to allow in your codebase. This is particularly useful for more fine-grained control over your code such as code that does not have a deprecation warning.

composer require --dev spaze/phpstan-disallowed-calls

After installation, you’ll need to configure it in your phpstan.neon file. Here’s an example of how you can disallow certain method calls or functions:

includes:
    - vendor/phpstan/phpstan-deprecation-rules/rules.neon
    # add the extension
    - vendor/spaze/phpstan-disallowed-calls/extension.neon

parameters:
    # You can see more example at https://github.com/spaze/phpstan-disallowed-calls/blob/main/docs/custom-rules.md
    disallowedMethodCalls:
        -
            method: 'PotentiallyDangerous\Logger::log()' # `function` is an alias of `method`
            message: 'use our own logger instead'
            errorTip: 'see https://our-docs.example/logging on how logging should be used'Begin writing your own rules
    disallowedFunctionCalls:
        -
            function: 'var_dump()' # `method` is an alias of `function`
            message: 'use logger instead'

This extension is pretty comprehensive meaning you’ll be able to cover the majority of scenarios. Of course there might be some situations that don’t work and for that the best thing is to start learning to write your own rules.

This is something we’ll get into in another article.

Conclusion

Using PHPStan to catch upgrade regressions is a smart way to make the upgrade process easier, especially in large development teams. Applying PHPStan to your continuous integration setup

Fix your Type Hints with Configurable Rules and PHP Rector

Peter Fox — Mon, 02 Sep 2024 16:31:22 +0000

Photo by Conny Schneider on Unsplash

Making your own rules to work with Rector PHP can be a bit of a learning curve. That said we don’t have to create new rules to have a big impact on our code. Some rules in the Rector ecosystem can even be configured to make our code base better with minimal effort, you’ll begin to wonder how you could have ever lived without it.

Swapping out a Class Type hint for another

In this article I’m going to show you with one rule how you can fix a ridiculously common problem when using the PHP Package Carbon. Carbon is kind of the defacto Date Time library for the PHP language.

Now most people will instantly type hint everything in their applications as \Carbon\Carbon because that’s the class type. It’s how you create instances most of the time, it’s also the main type. If you didn’t know though there is also \Carbon\CarbonImmutable which is also a class type but both behave differently. I won’t get into the whole different of mutable and immutable, googling it will help you understand that better. The point is you might want to swap between Carbon and CarbonImmutable at some point in the future as often CarbonImmutable is less problematic.

So let’s now look at how we can swap between the two versions using Rector. Please note I won’t explain how to setup Rector here. I have another article for that.

We’ll add the RenameClassRector rule to our Rector config. Rather than use the withRules() method we’ll instead use the withConfiguredRule() method. This allows us to supply an array to the rule, specifying the fully qualified names that we want to find and what to replace it with. We can see how that comes together in the config file below.

// rector.php
<?php

use Rector\Config\RectorConfig;
use Rector\Renaming\Rector\Name\RenameClassRector;

return RectorConfig::configure()
    ->withConfiguredRule(RenameClassRector::class, [
        'Carbon\\Carbon' => 'Carbon\\CarbonImmutable',
    ]);

Then once we’ve run the rector command we can see what’s been affected. Hopefully you have an output that’s updated all instances. This is great! But actually, we can improve this.

-function now(): \Carbon\Carbon
+function now(): \Carbon\CarbonImmutable
{
- return new \Carbon\Carbon();
+ return new \Carbon\CarbonImmutable();
}

Swapping out a Class Type hint for an Interface

If you know the Carbon package well enough there’s actually a \Carbon\CarbonInterface and both \Carbon\Carbon and \Carbon\CarbonImmutable implement this. Well we can actually use this rule with interfaces as well.

// rector.php
<?php

use Rector\Config\RectorConfig;
use Rector\Renaming\Rector\Name\RenameClassRector;

return RectorConfig::configure()
    ->withConfiguredRule(RenameClassRector::class, [
        'Carbon\\Carbon' => 'Carbon\\CarbonInterface',
        'Carbon\\CarbonImmutable' => 'Carbon\\CarbonInterface',
    ]);

The RenameClassRector rule is actually incredibly clever and will only update the parts that can be changed to an interface. For instance, no name changes should occur with the new keyword.

Again we can run the Rector command and hopefully it all works as expected.

-function now(): \Carbon\Carbon
+function now(): \Carbon\CarbonInterface
{
    return new \Carbon\Carbon();
}

Conclusion

In conclusion, configuring rules with PHP Rector provides a powerful and efficient way to manage type hints and other code transformations in your project. By leveraging configurable rules like RenameClassRector, you can seamlessly swap out class type hints, or even replace them with interfaces, all with minimal effort. This not only improves your codebase’s flexibility but also ensures consistency across your project. Adding Rector to your Continuous Integration setup with these rules can have a huge impact on your development styles.

If you want to see more configurable rules I suggest looking at the Type Declaration at getrector.com.

Mastering Code Refactoring: A Complete Guide to Using Rector PHP

Peter Fox — Thu, 22 Aug 2024 15:01:42 +0000

Photo by Matteo del Piano on Unsplash

Introduction to Rector PHP

In the ever-evolving world of PHP development, keeping your codebase clean, up-to-date, and efficient is crucial. This is where Rector PHP comes into play. If you’ve been wondering how to use Rector PHP, how to install it, or what exactly Rector PHP is, this comprehensive guide is for you. We’ll walk you through the basics, provide a detailed Rector PHP tutorial, and offer insights on PHP Rector and how to use it effectively. By the end of this article, you’ll have a solid grasp of Rector PHP and how it can enhance your development workflow.

What is Rector PHP?

Rector was started in 2020, but only got it’s 1.0 release in 2024. It’s a command line tool that performs a static analysis of a code base. From that analysis changes can be applied. I guess a good example of this would be what if your code base was riddled with array() calls when this is now considered an old practise, now replaced by the [] short array syntax.

Going through a code base to replace this is tedious. We could use a simple find and replace tool but what if there were an array() encapsulated a string or inside a comment that shouldn’t be changed? Now we’re having to check every instance we’re replaced.

This kind of problem is what Rector excels at. Instead Rector is able to look at the code and know definitively if it’s an array to be replaced.

You might be asking, PHP CS Fixer can also do this, which is true. But Rector also has PHPStan working under the hood to not only recognise syntax but to also analyse types. This means Rector can detect when a Class has a particular parent class, when a variable is a particular type or what the expected return type of a function. Giving it a far bigger scope for making changes on mass to a codebase.

How to Install Rector PHP

This might seem obvious to experienced PHP developers but there’s two primary ways and it really depends how you want to use Rector.

If you want to use Rector as part of continuous integration it makes sense to install Rector different into your projects through composer.

composer require --dev rector/rector

But if you were wanting to experiment with Rector on a single or multiple projects to perform upgrades, you might be better off by installing Rector globally by using

composer global require rector/rector

Which ever step you chose, the next step will be to create a config in the root directory for a project and include all the folders containing PHP code that you wish to upgrade. That doesn’t include the vendor folder of course as we don’t want to modify that.

This is what a config for say a Laravel project might look like:

use Rector\Config\RectorConfig;
use Rector\Php71\Rector\List_\ListToArrayDestructRector;

return RectorConfig::configure()
    ->withPaths([__DIR__. '/config', __DIR__. '/src', __DIR__. '/tests', __DIR__. '/routes'])
    ->withImportNames(removeUnusedImports: true);

PHP Rector: How to Use It Effectively

Like in the last section, using Rector can be determined by how you want to use it. Rector applies changes through the selections of Rules. This is the same as PHP CS Fixer. These rules will both detect the issue and then try to fix the problem they’re designed to solve.

If we wish to use Rector in a continuous integration manner, because we want to make use all of code is as optimised as best as possible as we develop it, we might use only a particular set of rules.

Rector has sets of rules, often described as Dead Code or Code Quality, which removes code or enhances and optimises respectively. It’s quite advantagous to stick to just these sets as we can be confident they work most of the time. But you should absolutely be aware that the way Rector writes code is never perfect. Often when rules are written they may cover the typical scenarios and may miss some circumstances found it your code base. This could lead to broken code.

In the event you want to use Rector, you should absolutely have tests written for your application. Without them Rector can easily lead to introducing bugs that you won’t discover until it’s a problem.

Another thing to consider when using Rector is that you should use a linting tool like PHP CS Fixer. Rector doesn’t look at whitespace, the spaces and newlines between method calls and it’s arguments etc. Using a linting tool should keep the code formatting to the standard you expect after Rector has applied it’s fixes.

Step-by-Step Rector PHP Tutorial

Now we’re installed Rector and we’re ready to try it out, let’s try applying one rule. Let’s start by updating our config file we made earlier.

use Rector\Config\RectorConfig;
use Rector\Php71\Rector\List_\ListToArrayDestructRector;

return RectorConfig::configure()
    ->withPaths([__DIR__. '/config', __DIR__. '/src', __DIR__. '/tests', __DIR__. '/routes'])
    ->withImportNames(removeUnusedImports: true)
    ->withRules([
        ListToArrayDestructRector::class,
    ]);

In the case of this config we’re going to make a replacement of the use of listso that instead we use array restructuring. The changes we would expect to make are like the following:

-list($a, $b) = ['a', 'b'];
+[$a, $b] = ['a', 'b'];

Now we can test this config by performing a dry run of Rector.

rector --dry-run

If everything has been successful we should now see an output that contains a diff of all the changes to each file, with a list of the rules that made the changes. Our config only lists one rule so only one rule is applied but if more rules are added we’ll see a list of one or more here.

This is then a great time to review the changes and make sure the rule is performing as expected. Once we’re happy we can run Rector again. Without the dry run flag, changes will be written to the files.

rector

After it’s completed we should run our favourite linting tool and then run our tests. That’s it. We’ve now used Rector.

Conclusion: Boosting Your PHP Development with Rector

Rector PHP is a powerful tool that can significantly enhance your PHP development workflow by automating code refactoring and ensuring your codebase remains clean and modern. By understanding what Rector PHP is, learning how to install it, and mastering how to use it effectively, you can leverage its capabilities to streamline code updates, improve code quality, and reduce the risk of code feeling like a “legacy” project. Whether you’re integrating Rector into your continuous integration pipeline or using it for large-scale codebase upgrades, Rector is an indispensable asset for any PHP developer looking to maintain a high standard of code excellence.

You can continue your Rector journey by learning about configurable Rector Rules in this follow up article, Fix your Type Hints with Configurable Rules and PHP Rector.

If you want to take you knowledge of Rector further I suggest going to https://getrector.com/.

PHP: Mocking Closures and performing assertions

Peter Fox — Thu, 06 Jun 2024 13:02:15 +0000

Photo by rivage on Unsplash

Testing is crucial to ensuring code quality and reliability in modern PHP development. One powerful technique in testing is mocking, which allows you to simulate and control the behaviour of dependencies. Mocking closures can be useful when verifying interactions with anonymous functions or passing them around as first-class callables. This article will explore how to mock or spy closures in PHP using the popular testing library, Mockery.

What does our class that needs testing look like

For an example Class I will use a Laravel Validation rule. They’re simple classes that only implement one method, but the third argument for the method is for a Closure.

<?php

namespace App\Rules;

use Closure;
use Illuminate\Contracts\Validation\ValidationRule;

class Uppercase implements ValidationRule
{
    /**
     * Run the validation rule.
     */
    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        if (strtoupper($value) !== $value) {
            $fail('The :attribute must be uppercase.');
        }
    }
}

How can we easily test this class? Let's make a closure that manipulates a boolean to set it as true if it has been called.

<?php

class UppercaseTest extend TestCase
{
    public function testItFailsNonUppercaseValues()
    {
       $calledClosure = false;

       (new Uppercase)->validate(
           '', 
           'lowercase',
           fn () => $calledClosure = true
       );

       $this->assertTrue($called);
    }
}

That solution would be fine, but this might become difficult to manage for more complicated situations. For example, what if the Closure is called more than once? Or you want to check which parameters it’s received.

This is where it’s great to use Mockery.

Using Mockery and ShouldHaveBeenCalled

Solving this with mockery isn’t too obvious if you’ve looked through the documentation even. We can do it using the following code:

<?php

class UppercaseTest extend TestCase
{
    public function testItFailsNonUppercaseValues()
    {
       $closure = Mockery::mock(function () {
       });

       // we have to turn the mock into a Closure by using
       // a first-class callable
       (new Uppercase)->validate('', 'lowercase', $closure(...));

       $closure->shouldBeCalled()
          ->with('The :attribute must be uppercase.')
          ->once();
    }
}

As you can see in the example, we can now nicely check if the Closure has been called with a string for our validation message and we can check that it was only called once.

Conclusion

Mocking closures in PHP using Mockery provides a flexible and powerful way to test your code. By understanding and leveraging this technique, you can write more reliable tests and ensure your code behaves as expected in different scenarios. The provided code example demonstrates the basic steps to mock and assert closures, which you can adapt and expand upon in your projects.

Remember, testing is not just about verifying correctness; it’s also about building confidence in your code. So, start incorporating mocking into your test suite and enjoy the benefits of more robust and maintainable PHP applications.

If you’re struggling with using Mockery feel free to reach out as it’s personally a topic I enjoy talking about. Happy coding!

Laravel Scout: Eager loading models for indexing

Peter Fox — Fri, 12 Apr 2024 20:02:04 +0000

Photo by Maksym Kaharlytskyi on Unsplash

If you’re like me you want to get eager loading right from day one. One area that can initially seem difficult for this is when it comes to index models with Laravel Scout.

This can be a real problem if you’re using relational attributes in your indexes. For example, imagine we have a Post model that we wish to index with information about the person who created the Post.

class Post extends Model
{
    public function toSearchableArray(): array
    {
        return [
            'id' => $this->id,
            'content' => $this->content,
            'created_by' => $this->user->name,
        ];
    }
}

If we try to reindex the Post mode with this code we will end up with N+1 issues because the user will be loaded per Post method.

Luckily there is a method for being able to do this.

Implement MakeSearchableUsing

Using the method makeSearchableUsing we can take the collection of models to be indexed and we can then use the eager load functionality to make use the users are loaded.

use Illuminate\Database\Eloquent\Collection;

class Post extends Model
{
    public function toSearchableArray(): array
    {
        return [
            'id' => $this->id,
            'content' => $this->content,
            'comments_count' => $this->comment_count,
            'created_by' => $this->user->name,
        ];
    }

    public function makeSearchableUsing(Collection $models): Collection
    {
        return $models->load('user')->loadCount('comments');
    }
}

Conclusion

Often Laravel will have what you need. In the case of Laravel Scout, the documentation can be difficult to follow. While this feature is documented and mentions eager loading it can be difficult to find. It’s worth taking a deep dive into the source code and understanding what can and can’t be extended through models.

I’m Peter Fox, a software developer in the UK who works with Laravel. Thank you for reading my article, I’ve got several more available at https://articles.peterfox.me. I’m also now Sponsorable on GitHub. If you’d like to encourage me to write more articles like this please do consider dropping a small one-off donation.

Laravel Testing: Mocking static methods with the container

Peter Fox — Mon, 01 Apr 2024 13:01:59 +0000

Photo by ShareGrid on Unsplash

I came across a difficult challenge this week. How can I mock a static method being used? Ideally, static methods shouldn’t be used as factories, but sometimes you don’t want to go down that rabbit hole of having to refactor everything.

Example Problem

Take the following code.

class Bar
{
    public function bar(mixed $bar): mixed
    {
        return Foo::foo($bar);
    }
}

It’s simple enough, but what if we need to mock Foo::foo() for some particular reason, maybe it’s interacting with a database or something you don’t want to deal with in a continuous integration environment.

Either way, this could be difficult to do.

The Mockery Solution

If you’re a regular test writer for your Laravel applications you likely know you can use Mockery. Mocks are typically used for instances, but you can mock static methods as well.

public function test_it_works(): void
{
    Mockery::mock('alias:' . Foo::class)
        ->shouldReceive('bar')
        ->with('bar')
        ->andReturn('foo');

    $result = $bar->bar('bar');
    $this->assertSame('foo', $result);
}

This works but if you dig into the alias functionality in Mockery, it can lead to issues where the library is unable to replace the existing class. This will cause the test to throw an exception.

The Laravel Container Solution

What you might not realise is that Laravel’s facades are a great way to get around this kind of problem. In this case we’ll be using the App facade.

First we need to make a minor change to our original class.

class Bar
{
    public function bar(mixed $bar): mixed
    {
        return App::call(Foo::foo(...), [$bar]);
    }
}

What we have done is turn the static method into a closure and tell the container to execute the closure with the provided arguments.

Now we’ve done this we can write a test that instead uses the facade to create a mock.

public function test_it_works(): void
{
    App::shouldReceive('call')
        ->with(Mockery::type(\Closure), ['bar'])
        ->andReturn('foo');

    $bar = new Bar();
    $result = $bar->bar('bar');
    $this->assertSame('foo', $result);
}

And that’s it.

Conclusion

I hope this has been a quick and helpful little article. I put this together mainly as a solution when you’re up against the clock. Obviously, I would advise against which kinds of static methods but it’s possible that sometimes you can’t get around it without lots of extra work. This small trick works great with that legacy code you’re still struggling with.

PHP: 7 tricks to help with upgrading Composer packages

Peter Fox — Tue, 13 Feb 2024 17:27:29 +0000

Photo by JESHOOTS.COM on Unsplash

Recently I had the pleasure of taking an enterprise app and upgrading it from Laravel 9 to Laravel 10. Like a lot of applications we also had a good number of dependencies to upgrade. While I won’t go into any specifics of that upgrade I will point out some of the techniques I used to Composer, PHP’s package manager that allowed me to navigate some of the complexities.

Often we think an upgrade is just typing out composer update and then seeing what needs fixing. Personally I think this is fine for an application without many decencies and has been around for a year or two but for many this is just going to be too broad and leave you struggling to debug issues. That’s why the first thing I will talk about is selective update.

Selective updates

When using the update command it is possible to change just the composer.lock file for specific packages. When you do this you specify you only want to update that package. This might throw up some dependencies issues or just do nothing if you try to specify a version that doesn’t play nicely with other packages you have in your lock file.

You’ll notice in the output below that for this Laravel project, we can specify package versions that are required. For any that are sub dependencies we can only allow the package to be updated unless we use the --with option.

composer update \ 
laravel/framework:~10.0.0 \ # allows for specific versions 
spatie/laravel-ignition:^2.0 \ 
monolog/monolog \ # can only be a reference to allow an upgrade 
spatie/ignition \ # we'll use the --with option to set a specific version
symfony/http-foundation \ 
symfony/mailer \ 
nesbot/carbon \ 
symfony/mime \ 
spatie/flare-client-php \ 
spatie/laravel-package-tools \ 
spatie/laravel-activitylog \
--with spatie/ignition:1.11.3 # our specific version for a sub dependency

A good example of why you might want to specify versions and increment them is finding bugs as you go. Myself when upgrading this work project to Laravel 10 found that installing just 10.0.3 there was only one bug but when it came to Laravel 10.43.0 I had multiple others to fix.

I resolved this by simply finding which version of Laravel 10 caused the bug and fixing it by making educated guess from what was in the changelog for that version of the framework. Then I’d increment to the next version that had a bug until I reached the latest version.

Such approaches might seem tedious but they can be pretty beneficial.

Dry run

Something that can be useful is simply to try commands with the dry-run option. This doesn’t help that much in the long run but it allows you to try things out without actually writing the changes to composer.json or composer.lock. This command option works with both require and update.

composer require php:^8.3 --dry-run

Find what depends on a package

If you’re struggling to update a package and the output of that command update is confusing you can absolutely try using the depends command (also known as the whycommand). This can help you see if one of the sub packages is used by another package as a sub dependency.

When using this command you should have a nice out like below that lists any conflicting dependencies.

peterfox@Peters-MBP-2 project % composer depends nesbot/carbon  
laravel/framework v10.38.1 requires nesbot/carbon (^2.67)   
laravel/octane v2.2.4 requires nesbot/carbon (^2.66.0) 
laravel/pulse v1.0.0-beta10 requires nesbot/carbon (^2.67)   
spatie/flare-client-php 1.4.3 requires nesbot/carbon (^2.62.1)

Find packages blocking updates

Another command that you can use before getting started is simply the why-not command. It’s also called prohibits but honestly why-not just seems more memorable!

Now Laravel 11 is literally days away so lets try seeing what it will take to get this current Laravel 10 project update to date.

peterfox@Peters-MBP-2 project % composer why-not laravel/framework 11.0.0
Package "laravel/framework" could not be found with constraint "11.0.0", results below will most likely be incomplete.
laravel/laravel dev-main requires laravel/framework (^10.0)                              
laravel/fortify v1.19.1 requires illuminate/support (^8.82|^9.0|^10.0)                  
laravel/jetstream v4.2.0 requires illuminate/console (^10.17)                            
laravel/jetstream v4.2.0 requires illuminate/support (^10.17)                            
laravel/octane v2.2.4 requires laravel/framework (^10.10.1)                           
laravel/sanctum v3.3.2 requires illuminate/console (^9.21|^10.0)                       
laravel/sanctum v3.3.2 requires illuminate/contracts (^9.21|^10.0)                     
laravel/sanctum v3.3.2 requires illuminate/database (^9.21|^10.0)                      
laravel/sanctum v3.3.2 requires illuminate/support (^9.21|^10.0)                       
laravel/scout v10.6.1 requires illuminate/bus (^9.0|^10.0)                            
laravel/scout v10.6.1 requires illuminate/contracts (^9.0|^10.0)                      
laravel/scout v10.6.1 requires illuminate/database (^9.0|^10.0)                       
laravel/scout v10.6.1 requires illuminate/http (^9.0|^10.0)                           
laravel/scout v10.6.1 requires illuminate/pagination (^9.0|^10.0)                     
laravel/scout v10.6.1 requires illuminate/queue (^9.0|^10.0)                          
laravel/scout v10.6.1 requires illuminate/support (^9.0|^10.0)                        
laravel/slack-notification-channel v3.1.0 requires illuminate/http (^9.0|^10.0)                           
laravel/slack-notification-channel v3.1.0 requires illuminate/notifications (^9.0|^10.0)                  
laravel/slack-notification-channel v3.1.0 requires illuminate/support (^9.0|^10.0)                        
laravel/tinker v2.8.2 requires illuminate/console (^6.0|^7.0|^8.0|^9.0|^10.0)         
laravel/tinker v2.8.2 requires illuminate/contracts (^6.0|^7.0|^8.0|^9.0|^10.0)       
laravel/tinker v2.8.2 requires illuminate/support (^6.0|^7.0|^8.0|^9.0|^10.0)         
livewire/livewire v3.3.3 requires illuminate/database (^10.0)                            
livewire/livewire v3.3.3 requires illuminate/support (^10.0)                             
livewire/livewire v3.3.3 requires illuminate/validation (^10.0)                          
openai-php/laravel v0.4.3 requires laravel/framework (^9.46.0|^10.7.1)                    
spatie/laravel-ignition 2.3.2 requires illuminate/support (^10.0)                             
spatie/laravel-package-tools 1.16.1 requires illuminate/contracts (^9.28|^10.0)                     
spatie/laravel-ray 1.33.0 requires illuminate/contracts (^7.20|^8.19|^9.0|^10.0)          
spatie/laravel-ray 1.33.0 requires illuminate/database (^7.20|^8.19|^9.0|^10.0)           
spatie/laravel-ray 1.33.0 requires illuminate/queue (^7.20|^8.19|^9.0|^10.0)              
spatie/laravel-ray 1.33.0 requires illuminate/support (^7.20|^8.19|^9.0|^10.0)            
spatie/laravel-webhook-client 3.2.0 requires illuminate/bus (^8.50|^9.0|^10.0)                      
spatie/laravel-webhook-client 3.2.0 requires illuminate/database (^8.50|^9.0|^10.0)                 
spatie/laravel-webhook-client 3.2.0 requires illuminate/support (^8.50|^9.0|^10.0)                  
teamtnt/laravel-scout-tntsearch-driver v12.5.0 requires illuminate/bus (~5.4|^6.0|^7.0|^8.0|^9.0|^10.0)        
teamtnt/laravel-scout-tntsearch-driver v12.5.0 requires illuminate/contracts (~5.4|^6.0|^7.0|^8.0|^9.0|^10.0)  
teamtnt/laravel-scout-tntsearch-driver v12.5.0 requires illuminate/pagination (~5.4|^6.0|^7.0|^8.0|^9.0|^10.0) 
teamtnt/laravel-scout-tntsearch-driver v12.5.0 requires illuminate/queue (~5.4|^6.0|^7.0|^8.0|^9.0|^10.0)      
teamtnt/laravel-scout-tntsearch-driver v12.5.0 requires illuminate/support (~5.4|^6.0|^7.0|^8.0|^9.0|^10.0)    
Not finding what you were looking for? Try calling `composer require "laravel/framework:11.0.0" --dry-run` to get another view on the problem.

This gives us a nice list to work with that allows us to sign off which packages we might need to look at. Equally we can try upgrading these one by one until hopefully none of them show up anymore. For instance if I try just a slightly newer version of Laravel 10, here’s what I get:

peterfox@Peters-MBP-2 project % composer why-not laravel/framework 10.43.0
There is no installed package depending on “laravel/framework” in versions not matching 10.43.0
Not finding what you were looking for? Try calling `composer require “laravel/framework:10.43.0” — dry-run` to get another view on the problem.

There’s not issues so we’re ready to upgrade.

Ignore platform dependencies

This is also something worth knowing. We can actually ignore PHP platform dependencies when performing require or update commands. The reason you might want this is to ignore when a certain PHP extension isn’t install on your local machine but might be in production.

This does work as well with PHP as a dependency itself. That’s right, even if you are working with PHP 8.1 but you want to install package that rely on newer PHP versions like 8.2 and 8.3 you can tell composer to just bypass this.

composer update laravel/framework --ignore-platform-reqs=php

There is a level of risk and I probably wouldn’t use this in production but it allows you to at least try out packages early without having to do anything overly hacky like downloading with one version to run with another.

This is also just happy when working with static analysis tools as you can download dependencies for things like PHPStan or Rector when you don’t intend to run the code locally.

Require across versions

This is more of a tip that PHP package developers will know but others might not be aware of and that is you can specify different versions in composer.json allowing you to then run update to switch to a new version.

For instance when upgrading to Laravel 10 from 9, you must also update spatie/laravel-ignition to version 2 or higher. The problem is you can’t do it in one command as one is a dev requirement and one is a production requirement but if you do them in seperate commands they will cause update issues to occur.

Doing this allows you to specify a new version to work with while still keeping the possibility to install older ones using the update command as I mentioned earlier.

composer require “laravel/framework:^9.0|~10.0.0”
composer require "spatie/laravel-ignition:^1.2|^2.0" --dev

Once you’re happy with the upgrade you can now just require those fixed versions. Remember, if you’re using install and you’re keeping the composer.lock file under source control, the version in the lock file is what will be installed.

Use your own forks

You might sometimes hit a hurdle that can be quite annoying. What do you do when a package isn’t updated to the latest framework or PHP version. A quick fix for yourself is to fork the source code. Most PHP packages are likely to be on github or another git based system. In the example below we can point a different repository for Laravel Framework allowing me to try out a fork without setting up anything in Packagist.

Note with the following command I specify the laravel/framework and the url https://github.com/peterfox/laravel-framework which where composer can find the forked code.

composer config repositories.laravel/framework vcs https://github.com/peterfox/laravel-framework

Once we’ve done this, we can easily just require a particular branch. In this case the branch is my-upgrade-branch but to tell Composer it is a branch we put dev- before the name of the branch. With this, we have installed a forked branch of a popular package.

composer require laravel-framework:dev-my-upgrade-branch

We can always remove the repository we added later on with the following command.

composer config — unset repositories.laravel/framework

Conclusion

Thank you again for getting through all of these. I hope it will be useful in your larger projects where upgrading code is a complex mystery to unravel as it has often been for me. Remember you can learn more about these commands available in composer by running composer list.

I’m Peter Fox, a software developer in the UK who works with Laravel. Thank you for reading my article, I’ve got several more available at https://articles.peterfox.me. I’m also now also Sponsorable on GitHub. If you’d like to encourage me to write more articles like this please do consider dropping a small one off donation.

Laravel Feature Flags: Choosing a Package

Peter Fox — Sun, 12 Feb 2023 11:06:52 +0000

Photo by Vladislav Klapin on Unsplash

Introduction

Laravel Pennant is now available (although, at the time of writing, Pennant & Laravel 10 do not have stable releases). This means that more and more people will be learning about the concept of Feature Flags and how they can improve the developer experience and product management of their Laravel applications.

That said, the official package comes after several community-created packages that took different approaches to implement feature flags. In this article, I will briefly examine these popular packages, including the one I maintain, Feature Flags for Laravel.

What problem does using Feature Flags solve?

Feature Flags are a solution that is primarily aimed at those who are doing continuous integration.

To explain, if you don’t know what continuous integration is, code is constantly merged into your main branch and regularly deployed to move quickly and avoid things like merge conflicts. Continuous integration typically requires that you have lots of automated tests, but you will soon find this isn’t enough. Instead, it would be best if you also began to build feature flags.

Imagine this scenario. You’re building a new feature for your application, which requires communication of the end product with the users, training for your support team, and marketing, who wants to make a campaign to shout about the changes to customers. This is where feature flags come in. You will build your feature, merge it and deploy it but stop your end users from accessing it until your business is ready. Once everyone else has caught up, you change the application's state without merging or deploying new code, and now customers will have their shiny new feature to play with.

All of this can be complex to reach. How do you start segregating the functionality you want to be used versus the functionality you don’t want to be available when deploying code changes?

That’s where feature flags come in.

Do you even need a package for Feature Flags?

Honestly? It’s absolutely possible to implement feature flags using the mechanisms available in Laravel itself or with just small amounts of code. Laravel has something called Gates and Policies. These two together make it easy to control user activity in your Laravel app by calling the allows method on a Gate or a Policy. This will do what you want but will lead to more difficulties as your app scales.

This approach will mean that you must create a persistence layer for features. If you decide on using a gate, you’ll have to determine how it will store the flags. For example, it could be in the config and models, but be wary that feature flags might be accessed multiple times per request in every request that occurs and become a bottleneck for performance.

If this isn’t for you, you’d best look at one of the four following packages to help develop feature flags in your application.

The Laravel Pennant Alternatives

Spatie’s Flags Package

GitHub - spatie/laravel-model-flags: Add flags to Eloquent models

Spatie’s package is a relatively new entry to the Feature Flag space. The package itself is pretty simple and focuses on models completely. The implementation requires you to add and run a migration. Afterwards, you may use a provided trait on any models you have, allowing you to store boolean flags per model.

This is mainly about having a superficial persistence layer to control feature sets for, say, your Users or if you implement a Team model. This is fine but requires you to rely on things like Gates and Policies to perform checks on the User.

There’s no integration with the Laravel framework in any other sense, so you’ll need to create a Middleware or Blade directive to check if the user has the flags expected.

JustSteveKing’s Package

GitHub - JustSteveKing/laravel-feature-flags: A simple to use Feature Flag package for Laravel

This package is quite good in that, in the same way as the Spatie package, it interacts with the models, allowing you even to apply models to groups, something I’m sure many will want to do. You will need to add a migration to your app to install a persistence layer that your models can use with a trait.

The package allows you to interact with blade templates to isolate sections based on the page. Steve King’s package can also let you apply middleware that restricts the routes, but that’s about as far as it goes into the Laravel framework itself.

One of the neat features in JustSteveKing’s package is the TimeBomb feature. Something I can see many people wanting. TimeBomb allows you to throw an exception for a flag you no longer wish to exist in your app. Doing this means it’s easier to clean up your code as you decide to retire some flags.

ryangjchandler’s Package

GitHub - ryangjchandler/laravel-feature-flags: An opinionated feature flags package for Laravel.

I won’t waste a lot of time here. Ryan Chandler’s package is nearly identical to Steve King's. It equally allows for some integration with the framework via blade and middleware while also allowing you to manage the flags against models.

That said, one bonus feature to using Ryan’s package is first-party support for a UI using Filaments. Filaments is a component framework for Laravel Livewire designed around building an admin dashboard. If you’re using Filaments, this might push you into choosing this package over the others.

YLS Ideas’ Package

GitHub - ylsideas/feature-flags: A Laravel package for handling feature flags

Unlike the other packages mentioned, this one works with a pipeline (in version 2, at least). This means you can be selective of which features are used and where the flags persist. Nothing is stored against models. Instead, by default, you may store flags in a table, Redis or PHP file or even use Laravel’s built-in gate system. You can even use all of these in the pipeline, allowing you to query different places. There is also a cache mechanism available to reduce the time taken to discover the flag state for apps built for large scale. This means you can’t store flags against a User, unlike the other three packages or Laravel Pennant, which use this as their primary mechanism.

It is possible, though, to quickly implement your Gateway in this package if you wish to develop more complicated mechanisms, such as implementing Spatie’s package and using it to check if the user has a flag via a gate.

One of the advantages is like JustSteveKing’s package in that there are integrations to Laravel itself with the YLS Ideas package. It can perform the same tricks with blade templates and middleware but extends this further with validation rules and task scheduling based on the flag's status. A recently added feature was for a maintenance mode driver that will appeal to many who wish to control how an application might display maintenance mode in a few different scenarios.

If you want to use Feature Flags for Laravel, there is a tutorial for getting started and a dedicated documentation website.

Laravel Pennant Itself

It’s hard not to think that Laravel Pennant isn’t the best option, as the Laravel team will always maintain it. I’ve already tried it out, and it’s hard not to love it. The API for interacting with flags using different ‘Scopes’ (think Users or Teams) is cleverly simple.

At the moment, Pennant only supports the Database for persistent storage, but additional drivers can be created, so I’m sure more will be available soon.

One drawback for some is that you will need to use Laravel 10 to work with this package, but that likely won’t affect those starting new projects after this month.

Conclusion

It’s certainly not easy to suggest one particular option over the other. You’ll often need to start by thinking about how you’d like such a system to work within your app and then go from there.

While all of these packages are great, they need a well-thought-out and specifically designed user interface component to work in a more enterprise environment. This can make using feature flags challenging to scale. This is why I recently announced that I would work on something called Flagfox.

Flagfox is a premium package for Laravel designed to provide the frontend and UI experience for managing feature flags so that non-developers can enable and disable functionality when needed without having to perform any new deployments.

This will make the journey to having a full feature flagged application more straightforward than any current options available.

The landing page for Flagfox is already up, and a waiting list is available to join.

I’m Peter Fox, a UK software developer with a decade of experience with PHP and Laravel. I’ve started work on a new project. Flagfox for Laravel will build upon my established work creating open-source packages to help developers add feature flags to their applications. We currently have a waiting list for those interested in learning more.

Implementing Feature Flags

Peter Fox — Wed, 18 Jan 2023 21:25:45 +0000

Photo by Glen Rushton on Unsplash

Feature flags are not a new concept. You might already have what is effectively a feature flag within your application. One of the often most referenced pieces on Feature Flags is by Martin Fowler, written back in 2017.

His article describes feature toggles, also known as feature flags. You wouldn’t be blamed for being confused looking at the contents and not understanding where to start.

Several cloud services exist, but they’re not easy to start with. As an avid Laravel Developer, I decided to make a package in 2019 to solve many of those difficulties so you can quickly start building an application with feature flags.

To get started, let’s cover some basics.

What is a feature flag?

A feature flag is no different from adding any other application functionality. The flag hides functionality until it’s ready for customers to use. Sometimes this is also known as a feature toggle.

What makes feature flags worthwhile?

Feature flags help you separate feature development and feature deployment. When you build a feature and use source control, you will have to wait to merge new functionality until all parts of the new functionality are ready to be released to customers and visitors.

This can be problematic and leads to large and complex pull requests. Then when you think you’re ready to merge, another pull request goes in first, causing a round of complex conflicts that need to be resolved.

That puts your plans to deploy on time at risk.

For many developers, this is just how it is, right? You make code and merge it when it’s ready for viewing eyes.

This mindset, while understandable, needs to be revised for building modern web applications.

Feature flags can change that. At the same time, they bring additional complexity once you try to implement them at scale. This was my reason for creating Feature Flags for Laravel to remove some of the upfront work required to avoid that complexity.

Using Feature Flags for Laravel

I created a package for this back in 2019. You can manage feature flags very quickly by using Laravel’s configs. That said, it can become hard to manage and often to change an application’s environment variables to affect configs, which means you have to run a new deployment even if the code is the same.

Instead, using the Laravel Feature Flags package, we can configure things to rely on the database and fall back to a config file. The package provides the API for making it easier to swap around persistence mechanisms with minimal fuss.

Installing and Configuring

First, we’ll take a default app with the familiar Laravel Welcome page. We want to hide the application’s version number behind a flag. Doing this allows us to change the deployment of this vital information only when needed.

To begin, we will install the package using composer:

composer require ylsideas/feature-flags:^2.0

After this, we need to publish a few files, and because we intend to store our flags in the database and a configuration file, we need to generate the migration for our flags table and a .features.php file. We can do that with the following commands:

# install the config to config/features.php
php artisan vendor:publish — provider=”YlsIdeas\FeatureFlags\FeatureFlagsServiceProvider” — tag=config
# install .features.php
php artisan vendor:publish — provider=”YlsIdeas\FeatureFlags\FeatureFlagsServiceProvider” — tag=inmemory-config
# install a migration to database/migrations
php artisan vendor:publish — provider=”YlsIdeas\FeatureFlags\FeatureFlagsServiceProvider” — tag=features-migration

Let’s first edit our config/features.php config file and check that the pipeline is as follows:

‘pipeline’ => [‘database’, ‘in_memory’],

By choosing the following gateways, we’re telling the pipeline to look at the database and then the .features.php file as a backup.

Now we need to check each gateway. For the in-memory gateway, the settings should be as follows:

‘in_memory’ => [
 ‘file’ => env(‘FEATURE_FLAG_IN_MEMORY_FILE’, ‘.features.php’),
 ‘driver’ => ‘in_memory’,
],

We’re going to change the database gateway and include some caching. A 2-minute cache should do, which is 120 seconds. This will mean that if a feature is accessed a few times within that time frame, the same result will be returned, saving our database from additional queries to run.

‘database’ => [
 ‘driver’ =>’ database’,
 ‘cache’ => [
 ‘ttl’ => 120,
 ],
 ‘connection’ => env(‘FEATURE_FLAG_DATABASE_CONNECTION’),
 ‘table’ => env(‘FEATURE_FLAG_DATABASE_TABLE’, ‘features’),
],

As our backup, we will add a default flag value to our .features.php config.

<?php

use Illuminate\Contracts\Foundation\Application;

/**
 * @returns array<string, bool>
 */
return static function (Application $app): array {
 return [
 ‘laravel.version’ => true,
 ];
};

These are the values we can commit into our repository as defaults then.

We quickly need to run the migrations for the database. If you’re working with a new Laravel app, we can use SQLite.

php artisan migrate

Let’s add a flag

Now to keep things simple, let’s add our initial flag. For this, we’ll open up the welcome.blade.php file and edit the part showing the Laravel version.

We can wrap the version in a blade directive made available by the package.

@feature(‘laravel.version’)
<div class=”ml-4 text-center text-sm text-gray-500 sm:text-right sm:ml-0">
 Laravel v{{ Illuminate\Foundation\Application::VERSION }} (PHP v{{ PHP_VERSION }})
</div>
@endfeature

Doing so means the section will only show when the feature laravel.version is enabled.

Let’s run the server using the following:

php artisan serve

And now, we can go to the default Welcome page to see if the version is missing. Success!

Now we can run the following artisan command, again available from the package and see if it affects the Welcome page.

php artisan feature:on database laravel.version

We may have to wait for a second to see the result.

We only need to run the command with the off value and disable the flag from running. Again this might take up to two minutes to show and change.

php artisan feature:off database laravel.version

Conclusion

Feature flags might not be necessary for those working on a product with one or two other people, but beyond that, they can become a critical tool in helping you deliver features on time.

This only scratches the surface. The real power starts when you can begin building flags that will be turned on and off per user or team. Once we reach this point, we will need to start using the gate gateway in the package or build a custom gateway for Feature Flags for Laravel.

This brings me to talking about the next step in my journey to helping others build with feature flags, a premium package to support managing the deployment and rollout of features to specific users and more.

If you want to check out the finished code from this article, you can always check out the demo on GitHub. You can find the repository for Feature Flags for Laravel on GitHub and the dedicated documentation website for FFfL.

Laravel Tip: Store your test coverage with CodeCov

Peter Fox — Sat, 03 Dec 2022 17:55:45 +0000

Photo by Ricardo Resende on Unsplash

Before getting started, I'd love for you to consider checking out my latest venture FlagFox.

Introduction

If you’re not aware Laravel’s artisan test command has been able to generate code coverage reports in the console output for some time now. This is great, but receiving that output in the console only helps a little when you run many of your tests in continuous integration.

This is where CodeCov comes up, a service for keeping track of your application's code coverage over time.

This tutorial will cover Setting up CodeCov and creating a GitHub Action to store the results. Nothing is stopping you from using another CI service with CodeCov, but for publishing results, I'll be using specifically GitHub actions.

Create a CodeCov account

This is straightforward as setups go. You can create an account via GitHub, which makes sense if you're already hosting your repo with GitHub.

At that point, you can search for the git repo you want to collect code coverage for, and upon selecting that repository, you'll see the following screen.

This will stay blank until we start pushing any coverage reports. To do this, we need to create our testing action. On this page, you will see a Token that you'll need to copy if you're setting up a private GitHub repository. Open-source projects can skip the token setup.

Creating a GitHub Action

The first thing to do will be to set up a secret in your GitHub repository. This will be the safest place to keep the token so others won't be able to upload code reports to CodeCov.

You only need to create a new Actions Secret in the repository settings, copy the token into the Secret input, and then save it.

The next part all occurs within our code.

We need to add a .github/workflows/run-tests.yml file to our project's folder. It also should contain the following Yaml file.

Please note that sometimes your tests will have different requirements; you will need to make that work before sending coverage reports. What's important here is the following:

Your PHP setup must have a code coverage driver. In the example, it's PCov which, at the moment, is considered the best option for running tests with speed.
When we reach the code execution step, we're running PHPUnit (or, in this case, the Artisan Test command) with the coverage options and telling PHPUnit where to save the report.
In the project, I've added a /storage/coverage folder and put a .gitignore file so that reports can be generated to that folder but will never be committed to the repository.
We're using the CodeCov Github Action they provide to use the token from the secrets we've configured, and we've told it the file we want to upload.

You’ll find that if you have set up the secrets or the actions wrong, the CodeCov upload step will fail silently and require you to look at the action's output to explain why it's failed.

If you've been successful, your code coverage action will look like this:

Now when we go to CodeCov, we should be able to see the output of our actions.

You can browse the results on CodeCov directly for the demo project I created.

Adding that coverage Badge

Of course, what is the point of this all if you won't be showing off that (hopefully green) code coverage?

To do this, we only need to go to the settings of our repo on CodeCov, and then we can copy the provided Markdown.

Once we have this, we can paste it into our project's README.md file.

Once committed, we'll see the badge and click through to the report on Codecov.

Conclusion

Well, we can wrap this up quickly. Code coverage is a great metric to monitor, don't put too much faith in that 100% mark, instead treat the value as a way to track progress or regression. Suppose you find yourself starting with 50% or so. Then it would be best if you aimed to maintain or improve this value. If you see it dropping over the next few months, you can begin to question whether you need to evaluate why that is the case or not.

Either way, I hope you'll have fun getting that feedback. Feel free to tweet me your code coverage on Twitter; I'd love to hear what you got.

Like Always, if you want to see all the code, you can view the repository created on GitHub.

I’m Peter Fox, a UK software developer with a decade of experience with PHP and Laravel. I’ve started work on a new project. Flagfox for Laravel will build upon my already established work creating open-source packages to help developers add feature flags to their applications. We currently have a waiting list for those interested in learning more.

Laravel Tooling: 4 tools for static analysis

Peter Fox — Sun, 20 Nov 2022 18:05:11 +0000

Laravel Tooling: 4 useful tools for static analysis

Photo by Isaac Smith on Unsplash

I’ve learnt over the years to embrace the range of amazing tools you can use to develop PHP and Laravel Applications. I did a little tweet about this but it didn’t seem fair to not go into a bit of a wider explanation of why I use these tools.

Peter Fox on Twitter: "As a PHP developer, there are a great number of static tools that you can use. Here are four off the top of my head that I regularly go to:#php #laravel 🧵 / Twitter"

As a PHP developer, there are a great number of static tools that you can use. Here are four off the top of my head that I regularly go to:#php #laravel 🧵

What are static analysis tools?

To put it as best as I can, a static analysis tool looks at code and makes determinations about what it sees. In this list, there will be tools that, grade performance, discover things like unused code, look at and improve the visual readability of code and even perform upgrades to the code.

Pint

Technically Pint is fairly new as the official linting tool for Laravel. It can firstly be used in any PHP project despite being made for Laravel and is a little bit nicer than PHP CS Fixer which Pint uses under the hood. Linting is a common name for a static analysis tool which will format code and try to apply small changes to make code readable by a set of standards.

As of writing most PHP code will be developed to what is known as the PSR-12 standard, we’ve also had the PSR-1 and now deprecated PSR-2 standard.

PSR coding standards don’t cover everything though so often it’s a good idea to look at what additional rules you might apply.

The key takeaway and benefits here are readability and collaboration. If you work by yourself it’s not necessarily going to bring huge improvements. If you work as a team and collaborate regularly, will be of great benefit to you all. Some PSR standards are as much there to help make sure code merges have fewer conflicts. Equally just establishing a set of rules shared between you means code will be written in ways your brain will look at and understand quicker from muscle memory.

PHPStan (& Larastan)

PHPStan is well-established as a useful tool for PHP developers the world over. The purpose of PHPStan is to look at how code interacts, for example, it can look at the usage of a variable and find if a string variable will be used with a function as an array argument. This of course would be an error at runtime if it were to happen. Likewise, PHPStan is capable of finding code that is no longer used.

PHPStan is incredibly useful as many developers are looking to take advantage of the type hinting that PHP7 and PHP8 have pushed forward. This isn’t easy to do though without finding all the places in a project that aren’t type-hinted. PHPStan can do this by looking for where arguments or return types aren’t documented either by a type-hint or a PHPDoc tag.

There’s even a great bit of functionality for creating what’s known as a baseline if you wish to ignore past problems and only focus on not introducing new issues.

If you’re developing a package or app that uses Larastan you’re going to want to install Larastan over PHPStan. This is because the extension will understand more of the magic that occurs within Laravel such as models having dynamic attributes and scopes.

To summarise, the benefit here really just comes down to spotting mistakes early. The higher level you set with PHPStan, the more likely you will have removed silly mistakes you’ll find at run time and save yourself from painfully debugging problems in production.

PHPInsights

I will say that overall this tool is handy but can be a bit overwhelming at first. A number of different static analysis things are at play here. Insights will provide you with 4 groups of scores, code, complexity, architecture, and style.

I’ll start with the style insights first, this is essentially going to be exactly the same kind of processing as Pint, but it’s nice to at least have a scoring. It will also pick up a few other things that Pint won’t such as line counts.

Complexity is purely cyclomatic complexity, which is a very simple way of saying how many branches occur within code. You might want to brush up on the concept. Personally, I find the default for this a bit low so I’ll typically pump it up. That said it’s a good metric for when classes become unwieldy.

That goes onto the next category architecture. This covers a few things but is often just simple naming conventions or the length of functions or classes. Again I would normally bump up the length of classes allowed as I don’t like to be held to such a high standard I end up creating lots of classes just to encapsulate simple functionality right away.

The final stat is code and really just follows a lot of the similar things that you might find with PHPStan or Pint. These might range from useless variables to avoiding using some functions due to the way they can be unpredictable. It can be a little opinionated at times so do remove some rules if they’re just generating more noise for you.

Ultimately I would say Insights is interesting and is great as a tool for gauging code quality quickly and then using that initial score to see if you are moving in the right direction when refactoring code but you definitely need to take the time to form your own opinion on what rules are and aren’t used when generating such metrics.

Rector

So this tool is in many ways my new favourite toy within the static analysis tool kit. It’s built on top of components from PHPStan to be able to give you all of that type-hinting goodness but it goes further in that it can actually fix things. Unlike Pint which can lint code by looking at how the white space is structured in code, Rector can analyse more of the usage and also start to replace function calls or with new operators available in later PHP versions. It’s pretty marvellous and with more people using it, we could start to see fewer legacy burdens in the world.

There’s a straightforward ruleset for things like PHP and even PHPUnit which are worth using but also there are rules to perform upgrades of Laravel code as well. Things like changing factories before PHP 7 into the newer style ones. One recent thing to point out is that if you are working with Laravel, the rules used to be installed with Rector but are now maintained in their own package to install.

It does all these things pretty well but I do suggest being somewhat careful with code bases are have a lot of legacy debt before running the fix command with everything. You can run the command with the dry-run option which only finds and displays problems, instead of applying the changes right away. It’s best to try one rule at a time when adding to an old codebase, review the changes and then continue. Some rules can have adverse effects such as the rule to upgrade json_encode and json_decode to throw exceptions.

My personal feeling is Rector is a tool more PHP developers should be getting used to using in the future. It could make the difference between your developers using outdated operates and functions within PHP as well as making it easier to upgrade code bases that could do with some additional love.

One Last Thing…

If you didn’t notice by now, there’s actually one thing that these PHP tools have in common and that is that 3 out of the 4 of these highly effective tools for Laravel developers are made by the well-known developer Nuno Maduro.

I know he accepts sponsorships via GitHub, please please, do consider giving a one-time donation. Equally consider looking at the developers of PHPStan, PHP CS Fixer and Rector who make these awesome tools possible.

Thank you for reading!

I’m Peter Fox, a software developer in the UK who works with Laravel among other things. Thank you for reading my article, If you’d like to encourage me to write more articles like this please do consider dropping a small one-off donation! All my content is free to read and I hope to stay this way in the future.