DEV Community: Tom Witkowski

PHP-Doc in Blade-Views

Tom Witkowski — Sun, 20 Dec 2020 19:30:30 +0000

In my Telegram Newsletter post I've used PHP-doc type-hints without explaining them as I'm doing it every day.
In the comments @alexfwulf mentioned that this was learning for him. So I'm dedicating a whole post on that topic.

With Laravel 7 we got Blade Components which are beautiful but also introduced even more ways to inject variables in a Blade View and for components we get some default variables.

Even before it was hard to know which variables are available in a Blade View and even harder what type they're.

The Laravel IDEA plug-in gets better and better in resolving them. But isn't perfect so some manual work is still required.
My solution is to put PHP-doc variable type-hints to the start of my Blade files.
This way I immediately know which variables I can use and what type they're.

I'm using a single line and PHP-tag per type-hint. This way it's easier to copy or remove them.

<?php /** @var \Illuminate\Support\Collection|\App\Models\User[] $users */ ?>
<?php /** @var string $name */ ?>

After I've added all the tags I can use the variables and can use PhpStorm awesome suggestions/autocompletion.

Blade components

I start every Blade component with one to two tags as these are default component variables.
Primary the $attributes variable has a lot of undocumented methods you can use to do cool things like cherry-picking special attributes.

<?php /** @var \Illuminate\View\ComponentAttributeBag $attributes */ ?>
<?php /** @var \Illuminate\Support\HtmlString $slot */ ?>

Blade-Component: Webmentions

Tom Witkowski — Sun, 20 Dec 2020 19:28:13 +0000

While developing my new website including this blog I've decided to go with a static site and don't want to handle comments and so on.
But I still wanted to include user contributed content below the articles.

So I searched for solutions and found some articles by my friends at Spatie how they've implemented webmention.io.

As I've created this site with Laravel 7 I wanted to create a simple to use Blade Component that will do everything for me.
The result is a PHP file that loads the webmentions and maps them into three collections - likes, reposts and comments - and a blade file that renders them.

The approach is pretty simple as webmention does the hard job for us.
At first I load all webmentions for the given or current URL.
As the API is paginated I'm using a do-while loop to load all pages.
After that I'm splitting the results in three collections.

namespace App\View\Components;

use Illuminate\Support\Collection;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
use Illuminate\View\Component;

class Webmentions extends Component
{
    public Collection $likes;
    public Collection $reposts;
    public Collection $comments;

    public function __construct(?string $url = null)
    {
        $url ??= request()->url();

        $webmentions = collect();
        $page = 0;
        do {
            $entries = Http::get('https://webmention.io/api/mentions.jf2', [
                'token' => config('services.webmention.token'),
                'domain' => parse_url($url, PHP_URL_HOST),
                'per-page' => 100,
                'page' => $page,
            ])->json()['children'] ?? [];
            $webmentions->push(...$entries);

            $page++;
        } while (count($entries) >= 100);

        $webmentions = $webmentions
            ->filter(fn (array $entry): bool => trim(parse_url($entry['wm-target'], PHP_URL_PATH), '/') === trim(parse_url($url, PHP_URL_PATH), '/'));

        $this->likes = $webmentions
            ->filter(fn (array $entry): bool => $entry['wm-property'] === 'like-of')
            ->mapInto(Like::class)
            ->sortByDesc('date');

        $this->reposts = $webmentions
            ->filter(function (array $entry): bool {
                if ($entry['wm-property'] === 'repost-of') {
                    return true;
                }

                if ($entry['wm-property'] === 'mention-of') {
                    return empty($entry['content']['text']);
                }

                return false;
            })
            ->mapInto(Repost::class)
            ->sortByDesc('date');

        $this->comments = $webmentions
            ->filter(fn (array $entry): bool => in_array($entry['wm-property'], ['mention-of', 'in-reply-to']))
            ->reject(fn (array $entry): bool => empty($entry['content']['text']))
            ->mapInto(Comment::class)
            ->sortBy('date');
    }

    public function render()
    {
        return view('components.webmentions');
    }
}

And the Blade view is super opinionated so I will reduce it to the important part.
You automatically have access to all public properties of the component class.
To use autocompletion in my blade files I'm always adding the variables to the top of the blade file as a doc-comment.

<?php /** @var \Illuminate\View\ComponentAttributeBag $attributes */ ?>
<?php /** @var \Illuminate\Support\Collection|\App\Webmentions\Like[] $likes */ ?>
<?php /** @var \Illuminate\Support\Collection|\App\Webmentions\Repost[] $reposts */ ?>
<?php /** @var \Illuminate\Support\Collection|\App\Webmentions\Comment[] $comments */ ?>

With this you can loop over the items and render them however you want.
And can use the new blade component wherever you need it.

<x-webmentions :url="$url" />

Human readable Intervals

Tom Witkowski — Sun, 13 Dec 2020 18:25:59 +0000

Every Laravel application has several configuration values that represent a given amount of seconds or minutes.
Like the session.lifetime, auth.password_timeout, queue.connections.*.retry_after and a lot more.
By default all these values are a single integer like 10800, some of them even missing the unit in the description.

Multiplication

I bet that most of you know and have already done the easiest way - replace the single integer with a multiplication like 3 * 60 * 60 which is the same as 10800.
Another benefit is that you can guess what's the interval as it's days * minutes * seconds.
But there are still problems:

it requires brain capacity to parse the multiplication
not all intervals are seconds - how would you differentiate between 10 * 60 (10 hours in minutes) and 10 * 60 (10 minutes in seconds)
it gets even harder when you need an interval like "2 days 6 hours" in seconds (2 * 24 * 60 * 60) + (6 * 60 * 60)

Luckily there's a solution for both issues.

Carbon Interval

Some time ago @marcelpociot posted this solution on Twitter.

If you don't know the class already - the nesbot/carbon (required by Laravel itself) provides the \Carbon\CarbonInterval class (docs).

This class comes with a human-readable fluent API to write your interval however you want.
The important part is the magic property totalSeconds - similar properties exist for minutes, days and so on.

use Carbon\CarbonInterval;

CarbonInterval::days(2)->hours(6)->totalSeconds;

This is helpful in every part of your application - not only the configuration but also the real app code, for example cache TTL, signed URL expiration and wherever you need a given amount of seconds, minutes or other time units.

Constants

@devfrey asked how this works with constants.

Short: it doesn't.

I would recommend using the multiplication or single integer solution with an explanatory comment. I'm always using two comments - one above the const which describes the value and one at the end of the line that contains the unit.

// 5 minutes
const DEFAULT_TTL = 5 * 60; // seconds

// 7 days
const REMINDER_DELAY = 7 * 24 * 60; // minutes

Environment Variables

In some cases you possibly want to use a .env variable to define your config interval and it should be possible to change the insert units - for example for development/testing purposes.
So by default it's 7 days but you want to be able to set it to 5 minutes without adjusting your code or complex conditions.
The solution is the static \Carbon\CarbonInterval::fromString() method that accepts a string, similar but different to strtotime() function.

In one of our projects we had to prevent password reset for 7 days after it was successfully reset. But for sure we had to use something like 5-10 minutes on our local machines and several hours on our staging system.

use Carbon\CarbonInterval;

return [
    // ...

    'password_reset_decay' => CarbonInterval::fromString(env('PASSWORD_RESET_DECAY', '7 days'))->totalSeconds,

    // ...
];

And in your .env file you can define the values like the following.

# production
PASSWORD_RESET_DECAY="7 days"
# staging
PASSWORD_RESET_DECAY="1 day"
# development
PASSWORD_RESET_DECAY="6 hours"
# local
PASSWORD_RESET_DECAY="10 minutes"

Telegram Newsletter Command

Tom Witkowski — Sun, 13 Dec 2020 18:22:11 +0000

After I've published my first post and got kind feedback from several readers I wanted to add something like a newsletter for my blog.

My goal is that it should inform the subscribers short after a post is published about the new post. Emails aren't an option as I hate emails and it's also not that easy and cheap to potentially scale them.
So I've searched for a different solution and thought about Telegram which has a powerful but still easy API and even creating a bot is as easy as sending messages to BotFather.

The next criteria are that I don't have any permanently running app for this site and my content is stored in markdown files. So it should work without any database and I need a runner that allows me to schedule commands.
The runner was quickly found, the same that deploys this site and does some checks - GitHub Actions.

Setting up Telegram

That's probably the easiest part as you only send some messages and have to create a new Telegram channel.

Bot

The commands I've sent to BotFather:

/newbot
/setdomain
/setuserpic
/setabouttext

After I've followed all the instructions I had my own GummibeerBot.

Channel

So now we need a channel that the bot will send the messages to. That's possible via the normal UI.
You must create a public channel as bots can't send messages to private channels. And you also want others to be able to join easily - otherwise it wouldn't be a newsletter. 😉

After you've created your channel you must add the bot as an administrator with the ability to send messages.
To do so open the channel => click on the name => click on administrators and add a new one.

Console Command

I've used artisan make:command PromotePost to create my new command - you can adjust the name however you want it.

Our command has to do two things:

pick a post to promote - it has to be published, should be promotable and shouldn't be promoted earlier
generate the message and send it to the Telegram channel

Configuration

At first we have to configure our app to know about some secrets that shouldn't be part of our app code.

I will use the services config as it's perfect for simple service configurations like Telegram in this case.
I will add the bot_token (you've received during setting up the Telegram bot and the Telegram channel chat_id.

'telegram' => [
    'bot_token' => env('TELEGRAM_BOT_TOKEN'),
    'chat_id' => '-xxxxxxxxxx',
],

The token is a secret you shouldn't share with anyone - so using the .env here is a good choice.
The chat ID isn't secret so it's up to you if you want to be able to adjust it via .env or not. Using env here would be useful if you want to use a test channel during development for example.

To retrieve the chat ID I've used a trick as the ID isn't copyable somewhere in the Telegram app.

You should send a message to your bot in the channel you want him to send the messages in - I've used @GummibeerBot test.
After this you should run the following code - Tinkerwell will be perfect for this but you can also use normal tinker or however you run one-shot code.

$chatId = Http::get(sprintf(
    'https://api.telegram.org/bot%s/getUpdates',
    config('services.telegram.bot_token')
))->json()['result'][0]['channel_post']['chat']['id'];

This should return the chat ID which looks something like -xxxxxxxxxx.

Picking your post

This part depends massively on your way you manage your posts and which attributes you use.
I've added a should_promote boolean attribute that indicates if this post should be promoted and a promoted_at datetime attribute that will indicate when/if the post was already promoted.
With these attributes you can use database query or collection filters to reduce your dataset.
As I only want to promote one post at a time I'm using this snippet to get the post I want to send out.

$post = $posts->sortBy('created_at')->first();

Send message via Telegram

That's the most important part but it's still not complicated thanks to Laravel Http helper class.

To send a message via Telegram you have to use the sendMessage endpoint.

use Illuminate\Support\Facades\Http;
use Spatie\Emoji\Emoji;

$response = Http::post(
    sprintf('https://api.telegram.org/bot%s/sendMessage', config('services.telegram.bot_token')),
    [
        'chat_id' => config('services.telegram.chat_id'),
        'text' => Emoji::orangeBook().' '.$post->title.PHP_EOL.$post->url,
    ]
);

I'm using the spatie/emoji package here to get the "📙" emoji and append the post title and after a line break the URL to the post (be sure that your code generates an absolute URL to your production system).

That's it - you've already sent the message to your Telegram channel and should see a message in it.

After this you should update/save your promoted post to prevent it from being sent out multiple times.

For everyone interested to see it in action you can join my Telegram Newsletter channel.