Tag: advanced php

PHP

Self hosting Google Fonts

To self-host, you need to download the fonts and write the appropriate @font-face CSS rules. Instead of doing this myself, Seb came across an excellent tool to streamline this process Read More

By , ago
PHP

★ A lightweight Laravel package to track changes over time

[AdSense-A]

I'm proud to announce that our team has released a new package called spatie/laravel-stats. This package is a lightweight solution for summarizing changes in your database over time.

Tracking changes

Here's a quick example where we will track the number of subscriptions and cancellations over time.

First, you should create a stats class.

use SpatieStatsBaseStats;

class SubscriptionStats extends BaseStats {}

Next, you can call increase when somebody subscribes and decrease when somebody cancels their plan.

SubscriptionStats::increase(); // execute whenever somebody subscribes
SubscriptionStats::decrease() // execute whenever somebody cancels the subscription;

With this in place, you can query the stats. Here's how you can get the subscription stats for the past two months, grouped by week.

use Spatie<span class="hljs-title">Stats<span class="hljs-title">StatsQuery;

$stats = StatsQuery::for(SubscriptionStats::class)
->start(now()->subMonths(2))
->end(now()->subSecond())
->groupByWeek()
->get();

This will return an array like this one:

[
[
'start' => '2020-01-01',
'end' => '2020-01-08',
'value' => 102,
'increments' => 32,
'decrements' => 20,
'difference' => 12,
],
[
'start' => '2020-01-08',
'end' => '2020-01-15',
'value' => 114,
'increments' => 63,
'decrements' => 30,
'difference' => 33,
],
]

Instead of manually increasing and decreasing the stat, you can directly set it. This is useful when your particular stat does not get calculated by your own app but lives elsewhere. Using the subscription example, let's imagine that subscriptions live elsewhere and that there's an API call to get the count.

$count = AnAPi::getSubscriptionCount();

SubscriptionStats::set($count);

By default, that increase, decrease and sets methods assume that the event that caused your stats to change happened right now. Optionally, you can pass a date time as a second parameter to these methods. Your stat change will be recorded as if it happened at that moment.

SubscriptionStats::increase(1, $subscription->created_at);

How it works on under the hood

The implementation of this package is simple. The basic principles of event sourcing are being used: we don't store a result, but only the changes.

The package stores all "events" in the stats_event table

screenshot

Inside the StatsQuery class, you'll find the heart of the package. In its get function, you can see that all events for a given period are retrieved, summarized and mapped to DataPoint classes.

In closing

We are going to use laravel-stats in Flare, our exception tracker for Laravel/PHP/JavaScript projects, to keep tracker of changes in subscribers and other key metrics. We hope that the package can be helpful in your projects as well.

As mentioned above, the package uses a lightweight event sourcy approach. If you want to know more about event sourcing, check out our upcoming premium course on event sourcing in Laravel.

I'd like to thank my colleague Alex, who did the bulk of the work creating spatie/laravel-stats.

Do also take a look at this list of packages our team has created previously. I'm sure there's something there for your next project.

(more…)

By , ago
PHP

★ Data Transfer Object v3 has been released

[AdSense-A]

We've released a new major version of spatie/data-transfer-object. This package makes it easy to create objects that have a certain shape. Properties can even be validated.

In this post I'd like to tell you more the package.

A modern package to construct data transfer objects

When we original released the data-transfer-object package, it was meant to solve four problems:

  • Runtime type checks for class properties
  • Support for union types
  • Support for array types (these are not full blown generics!)
  • Named arguments

Typed properties are added in PHP 7.4, and union types and named arguments in PHP 8. So now that PHP 8 has been released, it makes sense that we leverage PHP's native type check abilities.

The renewed goal of our package is to make constructing objects from arrays of (serialized) data as easy as possible. Here's what a DTO looks like:

use SpatieDataTransferObjectDataTransferObject;

class MyDTO extends DataTransferObject
{
public OtherDTO $otherDTO;


<span class="hljs-keyword">public</span> OtherDTOCollection $collection;

<span class="hljs-comment">#[CastWith(ComplexObjectCaster::class)]</span>
<span class="hljs-keyword">public</span> ComplexObject $complexObject;

<span class="hljs-keyword">public</span> ComplexObjectWithCast $complexObjectWithCast;

<span class="hljs-comment">#[NumberBetween(1, 100)]</span>
<span class="hljs-keyword">public</span> int $a;



}

You could construct this DTO like so:

$dto = new MyDTO(
a: 5,
collection: [
['id' => 1],
['id' => 2],
['id' => 3],
],
complexObject: [
'name' => 'test',
],
complexObjectWithCast: [
'name' => 'test',
],
otherDTO: ['id' => 5],
);

Let's discuss all possibilities one by one.

Named arguments

Constructing a DTO can be done with named arguments. It's also possible to still use the old array notation. This example is equivalent to the one above.

$dto = new MyDTO([
'a' => 5,
'collection' => [
['id' => 1],
['id' => 2],
['id' => 3],
],
'complexObject' => [
'name' => 'test',
],
'complexObjectWithCast' => [
'name' => 'test',
],
'otherDTO' => ['id' => 5],
]);

Value casts

If a DTO has a property that is another DTO or a DTO collection, the package will take care of automatically casting arrays of data to those DTOs:

$dto = new MyDTO(
collection: [ // This will become an object of class OtherDTOCollection
['id' => 1],
['id' => 2], // Each item will be an instance of OtherDTO
['id' => 3],
],
otherDTO: ['id' => 5], // This data will be cast to OtherDTO
);

Custom casters

You can build your own caster classes, which will take whatever input they are given, and will cast that input to the desired result.

Take a look at the ComplexObject:

class ComplexObject
{
public string $name;
}

And its caster ComplexObjectCaster:

use Spatie<span class="hljs-title">DataTransferObject<span class="hljs-title">Caster;

class ComplexObjectCaster implements Caster
{
/**
* @param array|mixed $value
*
* @return mixed
*/
public function cast(mixed $value): ComplexObject
{
return new ComplexObject(
name: $value['name']
);
}
}

Class-specific casters

Instead of specifying which caster should be used for each property, you can also define that caster on the target class itself:

class MyDTO extends DataTransferObject
{
public ComplexObjectWithCast $complexObjectWithCast;
}

#[CastWith(ComplexObjectWithCastCaster::class)]
class ComplexObjectWithCast
{
public string $name;
}

Default casters

It's possible to define default casters on a DTO class itself. These casters will be used whenever a property with a given type is encountered within the DTO class.

#[
DefaultCast(DateTimeImmutable::class, DateTimeImmutableCaster::class),
DefaultCast(Enum::class, EnumCaster::class),
]
abstract class BaseDataTransferObject extends DataTransferObject
{
public MyEnum $status; // EnumCaster will be used

<span class="hljs-keyword">public</span> DateTimeImmutable $date; <span class="hljs-comment">// DateTimeImmutableCaster will be used</span>



}

Validation

This package doesn't offer any specific validation functionality, but it does give you a way to build your own validation attributes. For example, NumberBetween is a user-implemented validation attribute:

class MyDTO extends DataTransferObject
{
#[NumberBetween(1, 100)]
public int $a;
}

It works like this under the hood:

#[Attribute(Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE)]
class NumberBetween implements Validator
{
public function __construct(
private int $min,
private int $max
) {
}

<span class="hljs-keyword">public</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">validate</span><span class="hljs-params">(mixed $value)</span>: <span class="hljs-title">ValidationResult</span>
</span>{
    <span class="hljs-keyword">if</span> ($value &lt; <span class="hljs-keyword">$this</span>-&gt;min) {
        <span class="hljs-keyword">return</span> ValidationResult::invalid(<span class="hljs-string">"Value should be greater than or equal to {$this-&gt;min}"</span>);
    }

    <span class="hljs-keyword">if</span> ($value &gt; <span class="hljs-keyword">$this</span>-&gt;max) {
        <span class="hljs-keyword">return</span> ValidationResult::invalid(<span class="hljs-string">"Value should be less than or equal to {$this-&gt;max}"</span>);
    }

    <span class="hljs-keyword">return</span> ValidationResult::valid();
}



}

In closing

We use spatie/data-transfer-object in our bigger projects. We hope that this package can be handy for you as well. The package has a few more features, to learn them, head over to the readme on GitHub.

The principal author of this package is my colleague Brent, who, like always, did an excellent job.

Want to see more packages that our team has created? Head over to the open source section on spatie.be

(more…)

By , ago