Forem: AriaieBOY

What is a Laravel Macro, and how can you write an IDE Helper for a Macro?

AriaieBOY — Fri, 08 Sep 2023 19:45:28 +0000

What is a Macro in Laravel?

Macro is a simple mechanism that lets you add extra functionality to the classes that use the Macroable trait.

For example, in my filament-jalali-datetime plugin for filament, I added a jalaliDate method to the filament TextColumn class using the code below:

TextColumn::macro('jalaliDate', function (?string $format = null, ?string $timezone = null): static {
            $format ??= config('filament-jalali-datetime.date_format');

            $this->formatStateUsing(static function (Column $column, $state) use ($format, $timezone): ?string {
                /** @var TextColumn $column */

                if (blank($state)) {
                    return null;
                }

                return Jalalian::fromCarbon(Carbon::parse($state)
                    ->setTimezone($timezone ?? $column->getTimezone()))
                    ->format($format);
            });

            return $this;
        });

You can add new functionality to any class that uses the Illuminate\Support\Traits\Macroable trait.

It's valuable, especially when you want to add new functionality to the core components of the framework and share it as a package.

The IDE-Helper

Laravel Macros are magical, and your IDE might not detect them correctly, so to have better IDE support, you must create some IDE helpers so the IDE can see your macros.

The simplest way I found is an ide_helpers.stubs.php on the root that contains the signature of your macros; for example, for my jalaliDate method, I created this file, and my IDE can detect this method without any problem:

<?php

namespace Filament\Tables\Columns {
    class TextColumn
    {
        /**
         * @source packages/filament-jalali-datetime/src/FilamentJalaliDatetimeServiceProvider.php:28
         */
        public function jalaliDate(?string $format = null, ?string $timezone = null): self
        {
            return $this;
        }
}

There is also a package to create automatic IDE-Helpers for macros named tutorigo/laravel-ide-macros.

If you have any other option to create IDE-Helpers for Laravel macros, you can share it in the comments.atabases, Object Storage, and git repositories.
I need to check the integrity of the backup files.

How I improved my backup strategies using TrueNAS Scale

AriaieBOY — Fri, 01 Sep 2023 15:08:08 +0000

In my previous blog post How do I backup my websites, and why should I improve, I described how I backup my websites.

In that article, I mentioned some problems with my backup plans. Since then I deployed a local NAS in my home using TrueNAS and improved my backup plans.

Redaundent storage using Raid-1

The first improvement is my Raid-1 configuration for backup storage.
This means that in the event of one of my drives failing, I can restore my backed-up files from the other disk.

Object storage backup

One missing part of my backup process was the object storage.
Thanks to TrueNAS, I can easily backup my object storage files using TrueNAS Data Protection Cloud Sync Task.
It will sync my object storage files with my Local NAS.

Gickup for git backup

Another service that I run is Gickup, which backup all my remote git repositories to my local NAS.

One last thing: Backup health check

Right now, I backup multiple things like my Databases, Object Storage, and git repositories.
I need to check the integrity of the backup files.

Why should you consider using AVIF on your website?

AriaieBOY — Fri, 25 Aug 2023 16:50:59 +0000

What is AVIF?

If you are reading tech news this day, you probably heard about the AV1 video coding format.
AV1 will reduce file sizes without losing quality. It's the next big coding format that big tech giants start supporting in their hardware and software.
AVIF is AV1 Image File Format. It uses AV1 to reduce image file sizes.
AVIF and AV1 were built by the Alliance for Open Media, a non-profit industry consortium that develops open, royalty-free technology for multimedia delivery.

Why should you use AVIF?

AVIF is excellent at reducing image file sizes without losing quality. There are many comparisons, but I like this post from ctrl.blog.
According to this post

AVIF outperformed both JPEG and WebP for every image in the test. AVIF's 85th percentile was the same as WebP's 15th percentile! A median saving of -50 % at the same DSSIM is a very good result!

But why should we use AVIF now?

If you heard about AVIF before, you probably know about its benefits compared to the WEBP. You can find great in-depth articles about the format and the technical details of how AVIF and AV1 work.

But you should consider using AVIF now because, unlike WEBP, AVIF will be the next modern image format for the web.

AVIF was released in 2019, and only four years later, almost every modern browser supports it (resource). while WEBP adoption was much slower; for example, Firefox added webp support nine years after the initial release, and Safari added support after ten years.

As I mentioned above, AVIF was developed by AOM, a non-profit industry consortium that Amazon, Cisco, Google, Intel, Microsoft, Mozilla, and Netflix founded.
And right now, it has over 43 members.

All this shows that, unlike WEBP, the AVIF adoption will be much faster. And you can start adopting the AVIF format in your sites to increase performance and reduce bandwidth usage.

How do I backup my websites, and why should I improve

AriaieBOY — Fri, 18 Aug 2023 13:32:22 +0000

In the old days, I didn't have any backup plans, and the only time I needed my website backed up, I was lucky that my host provider had an automatic backup system. I could restore my website using those backups, but I lost a week of data because the hosting provider would back up the host weekly.

I do not use a shared host these days, and I manage my servers, so I need to back up my websites personally.

How should I backup?

Determining which data requires backup and the frequency of changes is critical.

To determine the needed data, we can think that our server is gone, and we want to restore our website to its current state.

In my case, I need to know the services that my website needs, for example, the web server, application, database, object storage, and cache services.

Then I need to recreate these services using my website source code and run those on my new server.

After running the services, I first need to restore my databases. And if required, my object storage files.

How am I backing up my websites

I back up my databases to another server at least once daily. And in some cases, multiple times a day based on the application traffic.

I back up my codebases on my local machine and the remote git repository hosted on GitHub or GitLab.

Since I use docker for development, All my websites have a docker-compose file that can recreate all required services for the website.

What is missing?

The big missing part is the object storage part. I need to implement a way to automatically back up my files from my self-hosted object storage into another server.

I must implement the 3-2-1 strategy for all my backups.

I need to document the restoration process for each website.

Implement a way to verify the health of the backup files; the last thing I want is a corrupted backup file.

Laravel Pint: Easy-to-use Code Style Fixer For Artisans

AriaieBOY — Fri, 11 Aug 2023 20:09:00 +0000

For Laravel developers, having a standardized code style for each project is crucial.

It makes the code more readable and gives the entire project a uniform look.

However, adhering to these guidelines while focusing on writing code can be challenging.

Thankfully, code-style fixers like Prettier in the JS ecosystem and PHP-CS-Fixer in PHP exist to take care of this issue.

But installing and configuring these tools can pose a challenge.

That's where Laravel Pint comes in - it provides a pre-configured PHP-CS-Fixer for use in Laravel projects.

To install it, run the command composer requires laravel/pint --dev in your Laravel project.

Then, to fix your Laravel project file styles, run the ./vendor/bin/pint command.

Laravel Pint is highly customizable, and you can configure it to suit your needs with a JSON config file.

It also uses pre-existing rules from PHP-CS-Fixer in your configuration, making it a more straightforward and uncomplicated option.

The default configuration works for most Laravel projects, making Laravel Pint a must-have code-style fixer for Laravel developers.

Code-splitting and Lazy-loading Alpine Components using Async Alpine

AriaieBOY — Sat, 22 Jul 2023 13:27:15 +0000

Code-splitting and Lazy-loading Alpine Components using Async Alpine

With AlpineJs, you can create components in two ways: using inline HTML markup or the Alpine.data() function to define a component globally and use it throughout the entire project.

Each approach has its pros and cons. For example, It is not possible to cache the inline components. And are only reusable if you use your template engine to create reusable components. The benefit of this approach is that you don't need a build step; you can add the AlpineJS to your HTML markup using CDN and start building your application.

On the other hand, using Alpine.data() to declare the components, you can reuse them and cache them like other static files. This option has some downsides too.
You must set up a bundler like Vite or Webpack to bundle the codes. And if you have a big project, your bundled file size can grow over time.

To fix these issues, you can use Async Alpine to split your components into individual files and load them only when needed.

Installation

You can use Async Alpine using CDN or npm:

<script defer src="https://cdn.jsdelivr.net/npm/async-alpine@1.x.x/dist/async-alpine.script.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>

When you want to use CDN, you must load Async Alpine before loading the Alpine itself.

Install from npm with:

npm install async-alpine

Import it into your bundle alongside Alpine and run AsyncAlpine.init(Alpine) and AsyncAlpine.start() before Alpine.start():

import AsyncAlpine from 'async-alpine';
import Alpine from 'alpinejs';
AsyncAlpine.init(Alpine);
AsyncAlpine.start();
Alpine.start();

Usage

To use Async Alpine, you must create your components in individual files using ES Module format like the code below:

// publicly available at `/assets/path-to-component.js`
export default function myComponent() {
  return {
    message: '',
    init() {
      this.message = 'my component has initialised!'
    }
  }
}

After creating components in separate files, you can load them using one of these four options depending on your environment:
URL Components — most straightforward implementation declaring component URLs in JS;
Data Components — for building tools with dynamic import/code-splitting like Vite, WebPack, Rollup, and Parcel;
Alias Loading — if your components are in a very consistent file-system structure;
Inline Components — you need to declare components in HTML to get the asset URL, for example, using an asset CDN or for Shopify sites.

After loading components, you can use them asynchronously by adding x-ignore and ax-load with your x-data attribute like the code below:

<div
  x-ignore
  ax-load="visible"
  x-data="myComponent"
>
  <div x-text="message"></div>
</div>

Loading Strategies

In the code above, you can see that we used a value in the ax-load attribute. You can change the loading strategy by setting these values in the ax-load

Eager

It's the default behavior; if you do not provide any value, the component will load in this mode.
In eager mode, the component will start loading immediately on page load.
It will still load asynchronously in the background but with the highest priority possible.

This mode is useful when you want a component to be interactive as soon as possible.

Idle

It uses requestIdleCallback, where it's supported to load when the main thread is less busy.
Components not critical to the initial load are bests for this scenario.

Visible

It uses IntersectionObserver only to load when the component is in view, similar to lazy-loading images.

Media

The component will be loaded when the provided media query is true.

Event

The component will be loaded once it receives the async-alpine:load event on the window. Provide the id of the component in detail.id.

<!-- on a button click using Alpine's $dispatch -->
<button x-data @click="$dispatch('async-alpine:load', { id: 'my-component-1' })">Load component</button>
<div
  id="my-component-1"
  x-ignore
  ax-load="event"
  x-data="componentName"
></div>

<!-- load our component after `another-library-init` has loaded -->
<script>
window.addEventListener('another-library-init', () => {
  window.dispatchEvent(new CustomEvent('async-alpine:load', {
    detail: {
      id: 'my-component-2'
    }
  }))
})
</script>
<div
  id="my-component-2"
  x-ignore
  ax-load="media (prefers-reduced-motion: no-preference)"
  x-data="componentName"
></div>

For more information and more detailed examples, you can check out the official document of Async Alpine here.

Free Performance + Extra features for Laravel using Octane and Swoole

AriaieBOY — Sat, 22 Jul 2023 13:26:02 +0000

How Laravel Octane Boosts Performance?

As you know, in traditional Laravel applications, the PHP process will run the application from the ground up with each request, and the PHP process can only handle one request at a time.

But in Laravel Octane, the application will bootstrap once at the first request to the ram. After that, every request that hits the server will serve using the bootstrapped application in the ram instead of running the application from the ground up.

Another feature is that Laravel Octane can run multiple workers at once, so instead of handling one request at a time, it can take multiple requests at once.

How much faster is Octane?

A quick search in the internet you can find lots of benchmarks on the internet, but for a quick comparison, I tested my website using both Laravel Octane (swoole) and nginx + PHP-fpm with default settings and did a benchmark using this command:
ab -t 10 -c http://localhost

And here is the result:

nginx

octane

As you can see in the results above, it's about 25% faster than nginx-fpm.

Based on the configurations, it can perform much faster with fewer resources, but 25-30% boosts are a lot.

Boosting Performance is one of many things that Laravel Octane can do.

Laravel Octane under the hood uses some drivers to run the workers and bootstrap the application to the ram, including swoole, openswoole, and Roadrunner.

If you use swoole as the driver, you can access some cool extra features that can be useful depending on your application.

Concurrent Tasks

You can run operations concurrently using swoole task workers:

[$users, $servers] = Octane::concurrently([
 fn () => User::all(),
 fn () => Server::all(),
]);

All the functions above will run in parallel using swoole task workers. Isn't that awesome?

The Octane Cache

Octane using Swoole Table provides a cache driver that can handle up to 2 million reads and write operations per second.

You can also interact directly with Swoole Table using these codes:

Octane::table('example')->set('uuid', [
 'name' => 'Nuno Maduro',
 'votes' => 1000,
]);

return Octane::table('example')->get('uuid');

Ticks & Intervals

Using Octane with Swoole allows you to execute callables every specified second.

For example, the code below will run each 20 seconds after the application startup:

Octane::tick('simple-ticker', fn () => ray('Ticking...'))
 ->seconds(20);

How can you use Laravel Octane?

There is a good installation tutorial in the Laravel doc itself here

You need to install the drivers on your server first. For example, for installing swoole, you can use pecl:
pecl install swoole

After that, you need to install the laravel Octane itself using the code below:

composer require laravel/octane

Then you need to run this command:

php artisan octane:install

And at the end, for serving your application, you can use this artisan command:

php artisan octane:start

But can I use Octane on all Laravel applications?

The quick answer is Yes and also No!

You can use Octane on all Laravel applications, but since it handles requests differently, you must check that your application is compatible with Octane.

For example, your application's service providers register and boot methods will only be executed once when the request worker initially boots.

Because of that, You should double-check the injections in your boot and register methods.

You can read about the Dependency Injection & Octane in the Laravel Doc.

If you use Larastan, there is a rule that you can use to check Octane Compatibility. You can enable this rule by setting this parameter in your phpstan.neon file:

parameters:
    checkOctaneCompatibility: true

But don't be afraid of compatibility problems and memory leaks. After using Octane for almost two years, I only encounter one memory leak in barryvdh/laravel-debugbar.

Since You only use the debug bar in the development environment, it might not be a big deal. Still, I replaced it with itsgoingd/clockwork, and I can tell you it's as good as the laravel debug bar, and it supports Octane without any memory leak or compatibility problem.

ZSH Plugin for Laravel Sail

AriaieBOY — Sat, 22 Jul 2023 13:23:21 +0000

What is Laravel Sail

Laravel Sail is a development environment that uses docker under the hood.
By using Laravel Sail, you can use the power of docker without knowing much about it.
It has pre-defined services for your applications, including a web server, database, Redis, etc.

Sail also provides a CLI tool that helps you to manage the services and run commands like artisan, composer, npm, etc.
For example, you can start the service containers using ./vendor/bin/sail up or run artisan commands using ./vendor/bin/sail artisan

Laravel Sail ZSH Plugin features

As you can see from the examples above, you need to use the sail binary file path to run these commands.

I've created a plugin for ZSH with lots of aliases, so you can use Laravel Sail with shorter commands.

For example, you can start the service containers using the sup alias or run composer commands using the sc alias instead of ./vendor/bin/sail composer

Aside from simple aliases, the plugin also lets you use these aliases in any project sub-directories without you needing to provide the path to sail binary.

It also provides some basic autocompletion for the commands.

Another feature that makes this plugin much more helpful than a simple set of aliases is that you can install composer and npm dependencies using s cinit and ninit commands.

How to install this plugin

Run this command in your terminal and clone the source code to your ohmyzsh plugin directory.

 git clone --depth=1 https://github.com/ariaieboy/laravel-sail ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/laravel-sail

Then open the ~/.zshrc file in the editor of your choice and add laravel-sail to your ohmyzsh plugins list.

You can see the list of all aliases in the link below:

Laravel Sail ZSH Plugin

Nala: Modern Front-End for the APT Package Manager

AriaieBOY — Sat, 22 Jul 2023 13:21:38 +0000

As someone that uses Laravel and PestPHP, I am used to the beautiful CLI outputs. Nala is like a skin for apt with human-friendly outputs.
For example, look at the picture below which one do you prefer?

Besides the beautiful CLI outputs, Nala adds some nice to have features to the table.

The parallel download mode helps you to download lots of small and large packages faster than the default APT.

Another feature is nala fetch that test the latency of the available mirrors and then saves the 3 fastest mirrors and saves it in a file.

Another feature that I found out about Nala while I was writing this article is nala history it's like git but for the packages. It's save all installed removed or upgraded packages in var/lib/nala/history.json with a unique ID.
You can undo or redo changes using these IDs.
Nala is free and open-source and is written using Python.
If you use the latest version of Debian or Ubuntu you can install it as simply as an apt install:

sudo apt install Nala

Or you can check their wiki about other installation options:
Installation Page

Translate Your Laravel Application to 78 Languages

AriaieBOY — Sat, 22 Jul 2023 13:18:02 +0000

Laravel has localization tools that help you translate your applications into any language you want.
But by default, all the Laravel Lang files include the English language. And if your application needs other languages you must create and manage lang files for each language by yourself.

Right now that I am writing this article we have more than 1400 keys for each language in the Laravel-Lang package that includes Laravel and its first-party packages.

You can translate Laravel and its packages like Jetstream, Fortify, Cashier, etc into 78 Languages.

All you need to do is to install Laravel-lang/common packages using the command below:

composer require laravel-lang/common --dev

After that you can add any languages you want using the command below:

php artisan lang:add en de ro zh_CN lv

Laravel often introduces new localization keys to the lang files and the community might update the translations in the future you can update the added languages using the command below:

php artisan lang:update

You can translate missing keys or improve the translations and create a PR on the Laravel-Lang/lang and help improve this package.

CapRover - Easy and Free Self-Hosted PaaS!

AriaieBOY — Sat, 22 Jul 2023 13:14:33 +0000

What Is Caprover ?

If you managed a server on your own you know that configuring everything correctly is a very hard job to do.
Handling Nginx configuration, issuing SSL Certifications securing the services, etc.
Now imagine if you want to run more than a service on a server or you want to load balance your incoming requests between multiple servers and spin up more than one instance of a service on your servers. That's a hard job, right?
Not with Caprover, You can manage multiple services like your NodeJS, Python, PHP, ASP.NET, and Ruby Apps or your Databases like MySQL, MongoDB, Postgres, etc. on a single server or a cluster of servers.
It will load balance your app using a customizable Nginx proxy server and it can create free SSL certifications using Let's Encrypt.
CapRover Has a nice WEB GUI that helps you manage your services. you can also manage your services using the CLI of the CapRover.
Another awesome feature of CapRover is the rollback feature if you shipped a bad version on production you can easily roll back to any version of your APP with a single click.

But How It Is Working?

Under the hood, CapRover uses Docker to containerize your applications. An Nginx Reverse Proxy will manage your load balancing, the Reverse Proxy will also route the incoming requests to the specified services in your server(s).
And for clustering, Caprover uses Docker Swarm.
In the picture below you can see how CapRover works:

Is It Safe?

Caprover is an open-source project and you can check both the backend and frontend codes of it in their GitHub organization.
Since CapRover only uses docker in the background you can remove CapRover from your server any time you wanted to and your apps will continue working without any problem.

But I Didn't Work With Docker Before

CapRover has lots of one-click apps which means you can deploy lots of popular projects with a single click.
For example, you can deploy MySql, PostgreSQL, MariaDB, Redis, WordPress, Minio, etc.
You can find the full list of the apps here.
Besides one-click apps, there are some sample apps that you can use to practice or even deploy your application using these samples.

Last Word

CapRover might not be a good option for big teams and companies but it's a really good option for individuals or small to medium teams that want to reduce their costs and enjoy the power of Docker and Nginx without having to learn them or deal with their settings scripts to make things work!!

Test Your Codebase Without Testing It Using Larastan

AriaieBOY — Sat, 22 Jul 2023 13:10:10 +0000

Larastan is a wrapper around PHPStan for Laravel, and it let you test your source codes without writing any tests.

PHPStan is a static analyzer for PHP and it's working with legacy and modern codes.

Since lots of Laravel works magically PHPStan needs some justification to understand the magic behind Laravel it's when Larastan comes into place.

So if you have any PHP code base you can PHPStan and if you use Laravel you must go with Larastan. from here on I am gonna reference these tools as static analyzers.

But how it's working

Static Analyzers scan your code base before you even run your code in development or in CI to prevent any obvious & tricky bugs to reach your production.

PHPStan has 9 levels of rule sets that you can use on your code base. for example, level 0 only checks for:

basic checks, unknown classes, unknown functions, unknown methods called on $this, wrong number of arguments passed to those methods and functions, always undefined variables.

It's good practice to start using these tools with low levels and fix bugs and errors after you fixed all errors on that level you can bump your level up and try to make your code base more strict and bug-free.

For sure Static Analyzers are not going to test all possible outcomes of your code, but they can detect lots of annoying bugs and dead codes etc. and make your code base much cleaner and bug-free.