DEV Community: Koussay

Create Custom Blade Directives in Laravel

Koussay — Sun, 27 Aug 2023 21:27:34 +0000

Laravel Blade is awesome, really awesome. One of the greatest things about it, is the ability to add custom directives.
One use case I recently stumbled upon, is formatting money, with the currency. For sure I can create a helper function and call it.
Example

    if (! function_exists('formatMoney')) {
    function formatMoney(string|int|float $amount) {
        if (is_string($amount)) {
            $amount = floatval($amount);
        }

        $settings = app(GeneralSettings::class);

        $formatter = new NumberFormatter(config('app.currency_locale', 'en_US'), NumberFormatter::CURRENCY);

        return $formatter->formatCurrency($amount, $settings->app_currency);

    }

And then we could use it in our views like the following

...
{{ formatMoney($invoice->total) }}
...

And we're good to go, but in this context, let's use the power of Blade and create our own directive.
In order to do so, open AppServiceProvider.php and head to the boot method.
Inside the boot method, we will write our own custom directive.

Blade::directive($name, function ($expression) {
    some code here;
});

In our context we will use the code above, defined in a helper class, so we can format the money.
The blade directive will be named money

Blade::directive('money', function ($expression) {
    return "<?php echo app('App\Utils\Helpers')->formatMoney($expression); ?>";
});

So here is the final code, and in the view file, we can call it as follows

@money('somevalue')

The take here is in the return value, if you want to have some formatters, or some conditions, the return must be a PHP code. Let's take another example.
Laravel has @auth & @guest directives.
But let's make some thing on our own. Let's say we have customers in our application, so we will make a blade directive that checks if the authenticated user is a customer or not, and show some code based on that condition.
Usually, here is what we would do :

@if(auth()->user()->isCustomer)
//some code here
@endif

But, that would be hard if we have that piece of code everywhere in our views. Imagine if we will add another condition, like checks if the customer has an active subscription for example.
So yeah, you've got the point.
In this situation, we could leverage blade custom directives.
The use of the new directive would be as follows :

@customer
//somecode here
@endcustomer

As you can see here, we have two directives, so we will define two functions in our AppServiceProvider.php

Blade::directive('customer', function ($expression) {
    return "<?php if(auth()->check() && auth()->user()->isCustomer): ?>";
});

Blade::directive('endcustomer', function ($expression) {
    return "<?php endif; ?>";
});

The first one is to test the condition and open the colon for your code logic, and the other one, will close the the if statement.

In this short tutorial, we saw how we could write custom blade directives. I hope it was insightful for you to understand how to create and use them.
If there is any question or any suggestion, feel free to reach me on Twitter

Original Post

Laravel Livewire Multiple Selection with Virtual Select

Koussay — Tue, 27 Jun 2023 00:40:40 +0000

Hello.
Recently in of our projects, we had to create a multiple selection dropdown. We were using Livewire, and vanilla JavaScript (no AlpineJS), so the options were either using the default multiple select, which is to be honest, ugly.
So we have to check for something else. The next options was Select2 Js, a popular jQuery library.
The problem with Select2 was the jQuery, we have to import jQuery just for that, and also the design wasn't that good actually.

So after little research, and so many thanks for skywalker , we were introduced to Virtual Select.

What we like about Virtual Select is the looks and the performance of it. It was amazing really, no dependencies and it worked from the first try.
Unfortunately, the plugin doesn't support ES6 yet.
But if you want to contribute, here is the link to issue discussing the matter.

In this tutorial we will cover how to import Virtual Select, and how to retrieve data in our component.

NOTE: : This tutorial will assume you have a Laravel installation in place already and Livewire is also installed.

NOTE: : In this tutorial we will not cover how to get data from API, it maybe for another tutorial soon 🤞.

That being said, the first thing to do is to create the Livewire component. A common use case for this would be as follows:
Select multiple permissions for a specific user.
So our component would be named, for example EditUser.
So run this in your terminal :

php artisan livewire:make EditUser

After creating the component, the next thing to do is open the class, called EditUser.php, and edit the render method as follows :

use App\Models\Permission;
use Livewire\Component;

class EditUser extends Component
{
    public function render()
    {
        $permissions = Permission::query()->get();
        return view('livewire.edit-user')->with('permissions', $permissions);
    }
}

As you can see, we added the list of permissions needed to assign them to the desired user.
Another thing to do here, is to prepare a public property to hold those assigned permissions. So the class will be as follows :

use App\Models\Permission;
use Livewire\Component;

class EditUser extends Component
{

    public $selectedPermissions= [];


    public function render()
    {
        $permissions = Permission::query()->get();
        return view('livewire.edit-user')->with('permissions', $permissions);
    }
}

And of course your component would hold other properties such as the user property and other stuff, but for the sake of this tutorial, we are making it simple.

Anyways, moving on now to the frontend. The first thing you need to do is to "import" Virtual Select CSS & JS assets.
You can download them, or use a CDN.
For this example, we will use jsdelivr.com .
So the first thing you need, is to use them in your main layout file as follows:

    <script src="https://cdn.jsdelivr.net/npm/virtual-select-plugin@1.0.39/dist/virtual-select.min.js" integrity="sha256-Gsn2XyJGdUeHy0r4gaP1mJy1JkLiIWY6g6hJhV5UrIw=" crossorigin="anonymous"></script>

    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/virtual-select-plugin@1.0.39/dist/virtual-select.min.css" integrity="sha256-KqTuc/vUgQsb5EMyyxWf62qYinMUXDpWELyNx+cCUr0=" crossorigin="anonymous">

Also, you may want to use @stack for the JavaScript we will use in the component later.
After those modifications, our main layout file would be look like this

...
    @livewireStyles
    <script src="https://cdn.jsdelivr.net/npm/virtual-select-plugin@1.0.39/dist/virtual-select.min.js" integrity="sha256-Gsn2XyJGdUeHy0r4gaP1mJy1JkLiIWY6g6hJhV5UrIw=" crossorigin="anonymous"></script>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/virtual-select-plugin@1.0.39/dist/virtual-select.min.css" integrity="sha256-KqTuc/vUgQsb5EMyyxWf62qYinMUXDpWELyNx+cCUr0=" crossorigin="anonymous">
</head>

<body>




    @livewireScripts
    @stack('js')
    ...
</body>
...

Now moving on to our component.
The first thing to do is to initiate an empty div for the plugin to work. So open edit-user.blade.php and add the empty div with an id so we can reference it later.
At first, our component will look like this :

<div>
    <div id="permissions"></div>
</div>

After initializing the DOM element, the next thing to do is to initiate the plugin. In order to do so, we will "push" the stacked js we defined earlier. It will look like this :

<div>
    <div id="permissions"></div>
    @push('js')
        <script>

        </script>
    @endpush
</div>

And now let's get to work. We need to define our options, to do so, we can create a new JavaScript variable to hold the permissions coming from the database.

            const permissions = [
                @foreach ($permissions as $permission)
                    {
                        label: "{{ $permission->name }}",
                        value: "{{ $permission->id }}"
                    },
                @endforeach
            ];

This piece of code, will be able to transform the collection of permissions into a JavaScript array.
After that, what we need to do is to initiate the plugin itself.

<div>
    <div id="permissions"></div>
    @push('js')
        <script>
            const permissions = [
                @foreach ($permissions as $permission)
                    {
                        label: "{{ $permission->name }}",
                        value: "{{ $permission->id }}"
                    },
                @endforeach
            ];
            VirtualSelect.init({
                ele: '#permissions',
                multiple: true,
                options: permissions,
            });
        </script>
    @endpush
</div>

As you can see, we called the init method with the options :

ele : The element of the DOM that will render the dropdown

multiple : whether to indicate it's a multiple selection or not

options : the data the dropdown will populated with, which we defined earlier.

At this moment, if we visit the page, our component will be like this:

At this stage, everything is working perfectly, but the problem is how to tell Livewire about those selections. At this point, we will use Livewire beauty ❤️

In order to pass the data to Livewire, we will use the JavaScript event listener, whenever the selection is changed, we will send them to our component.
So in our view file, what we need to add is the following code

            let selectedPermissions = document.querySelector('#permissions');
            selectedPermissions.addEventListener('change', () => {
                let data = selectedPermissions.value;
                @this.set('selectedPermissions', data);
            });

What we did is we first get the DOM element defined earlier, then we attach to it an event listener, whenever the selection changes, we want to get the selection and send it to our component.
And then at the component level, the selected data will be available at $selectedPermissions property, so you can assign them to the user.

I hope you liked this tutorial, and you gain information about it.
If something is not clear or you want ask about further information, you can contact me on Twitter or comment down below.
Thank you again and have a nice day.

Original Post
Credits : Photo by Edu Grande on Unsplash

Effortless Email Archiving: Saving Sent Emails on Server with Laravel IMAP

Koussay — Sun, 11 Jun 2023 13:49:25 +0000

Hello,
Sending emails with Laravel is really one of the easiest things to do. For example, sending password resets, or account activation, but sometimes, you want to send emails to your users and leave a trail for that. In order to do so, you have 2 options, either storing the email in the database, or save it on the IMAP server.
In this tutorial we will see the second option, append the sent email to the IMAP server. So let's get started.

NOTE: : This tutorial will assume you have a Laravel installation in place already.

The first thing to do is to install laravel-imap package

composer require webklex/laravel-imap

After installing it, we will set up the IMAP credentials in our .env file.
After opening the .env file, paste the following code at the end of the file.

IMAP_HOST="imaphost"
IMAP_PORT="993"
IMAP_ENCRYPTION="ssl"
IMAP_VALIDATE_CERT="true"
IMAP_USERNAME="email"
IMAP_PASSWORD="password"
IMAP_DEFAULT_ACCOUNT=default
IMAP_PROTOCOL=imap

Then change the values in according to your configuration.

The next step is to generate a Mailable so we can send it, to do so, just run this command:

php artisan make:mail TestMail

This command will generate a new mailable class called TestMail.php.
All you need to do now is open the file and edit it (mainly adjust the view name).

NOTE: : You can see other tutorials about sending emails using Laravel.
Now after everything is in place, now we will try to send the email and save it on the IMAP server.

So to send the email, all you need to do is the following

$mail = Mail::to('hello@gmail.com')->send(new TestMail());

Note here, we saved the result in the $mail variable, because we will use that to store the sent email.
After the email was sent, we need to connect to our IMAP server now.

$client = Client::account('default');
$client->connect();
$folder = $client->getFolderByName('Sent');

The code above will try to connect to the IMAP server using the credentials we put earlier in the .env file. After the connection has been made, we will retrieve the Sent folder.

NOTE: : The sent folder name is usually Sent, this depends on your IMAP configuration.

After successfully getting the folder, all we need now is to append it, by using the appendMessage method.

$result = $folder->appendMessage($mail->getSymfonySentMessage()->toString(), ['\Seen'], now()->format("d-M-Y h:i:s O"));

Now let's break down this method, and see:
The first parameter, is the message in a string format.
The $mail variable will be a SymfonySentMessage type, so it has a method called getSymfonySentMessage()->toString(), this method will return the string format of the message.
This is an example of the result:

From: Laravel <hello@example.com>
To: hello@gmail.com
Subject: Test Mail
Message-ID: <1259c22f78de504c28beabdb9eda5636@example.com>
MIME-Version: 1.0
Date: Sun, 11 Jun 2023 13:37:36 +0000
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: quoted-printable

HELLO WORLD

Using this string, we will be able to append the sent message,

The second parameter is the flag, in this example, we will use the seen flag, so it will be seen on the IMAP. You can learn more about flags on this RFC 2060

And finally, the date, we will use that to indicate when this message will be saved at IMAP.

Finally, we will check the result of the appendMessage method.
The result will be something like that

'OK [APPENDUID 1655722943 20] Append completed (0.018 + 0.135 + 0.016 secs)';

If you have this string, then everything went okay.

Laravel Realtime with Ably & Laravel Livewire

Koussay — Sun, 21 May 2023 13:49:24 +0000

Welcome,
One of the things I love about Livewire, is the seamless integration with Laravel Echo, which makes listening to real time events a breeze.
In this tutorial, wel will see how to integrate Livewire with Ably.

NOTE: : The reason why I chose Ably, because of their generous free tier.
NOTE: : This guide will assume you have Laravel & Livewire installed and already configured.

So let's get started.
Firs thing to do is to create an account in Ably, so head there and create your account.
Then, you have to create an application, give it a name, and we are good to go.
The next thing to do, is to grab the API key.
From the Ably dashboard, head to API Keys, you will find 2 keys, we are interested in the first one

Click on Show, then click on Copy, and let's go to our project.
In your favorite text editor, open the .env file.
At the bottom of the file, add this entry :



ABLY_KEY=UDAfQA.yFhVpQ:*************************

The API key you copied should go to ABLY_KEY.
After setting up the key, now let's install the Ably Broadcaster.
In your terminal run this command :



composer require ably/laravel-broadcaster

After installing it, in your .env file, set BROADCAST_DRIVER as ably.
Then, go to config/app.php and uncomment



        App\Providers\BroadcastServiceProvider::class,

Now, let's install Ably Laravel Echo.
In your terminal, run this command



npm install @ably/laravel-echo ably

After the installation, put the following code, that will allow us to make connection to Ably SDK.
You can put this code in the bootstrap.js file, or in any other JavaScript file



import Echo from '@ably/laravel-echo';
import * as Ably from 'ably';

window.Ably = Ably;
window.Echo = new Echo({
    broadcaster: 'ably',
});
//this bit of code is optional, it's used to check the conntection to ably
window.Echo.connector.ably.connection.on(stateChange => {
    if (stateChange.current === 'connected') {
        console.log('connected to ably server');
    }
});

After setting up everything, now let's go create our Livewire components.
We will create a Sender component, a receiver component, and an event.
We will start with the event. In your terminal, run this command



 php artisan make:event TriggerEvent

The output of the command will be a class located under App/Events. Let's open the class, and edit it so it will be as follows:



class TriggerEvent implements ShouldBroadcast
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    /**
     * Create a new event instance.
     */
    public function __construct(
        public string $message
    ) {}

    /**
     * Get the channels the event should broadcast on.
     *
     * @return array<int, \Illuminate\Broadcasting\Channel>
     */
    public function broadcastOn(): array
    {
        return [
            new Channel('public-events'),
        ];
    }
}

The TriggerEvent class must implement ShouldBroadcast interface. Then in the constructor we passed a message, so we can get it later in the receiver component.
Then in the broadcastOn function, we returned an array of channels to broadcast on.
In our example, we returned an instance of Channel, which is a public channel, with the name of public-events.
The name is used to listen to it whenever an event is triggered.
Now let's get to our components.
The sender component will trigger the event, and the receiver will listen to it and update the UI.
So in your terminal, run those commands to create the components.



 php artisan livewire:make Sender



 php artisan livewire:make Receiver

Our focus for now is the sender component. In the view file we will have an input text and button to trigger the event.
In the sender.blade.php, put the following code :



<div>
    This is the sender component, the notification will be triggered from here.
    <div>
        <input type="text" wire:model='message'>
    </div>
    <button wire:click='trigger'>Trigger</button>
</div>

In the above code, we have a model binded input to a property called message and the button is binded to a method called trigger.
Now in the Sender.php class, our code will be as follows :



...
    public $message;

    public function render()
    {
        return view('livewire.sender');
    }

    public function trigger()
    {
        TriggerEvent::dispatch($this->message);
    }
...

Now, let's head to the Receiver component.
In the view file, we will have the following :



<div>
    Breaking News :
    <h1>{{ $message }}</h1>
</div>

A dead simple UI, with a message property.
But the magic will happen, in the php class.
So open the Receiver.php class, and let's edit it as follows:



...
    protected $listeners = ['echo:public-events,TriggerEvent' => 'responseToEvent'];

    public $message;

    public function render()
    {
        return view('livewire.receiver');
    }

    public function responseToEvent($event)
    {
        $this->message = $event['message'];
    }
...

The first thing to add is the $listeners property, which is the array responsible for defining our listeners.
In that array, echo:public-events,TriggerEvent where public-events is the name of the channel we defined earlier, and TriggerEvent is the name of the event, also we have responseToEvent which is the function will be fired whenever TriggerEvent is triggered.
Then we have a property called message which will be updated in the responseToEvent method.

And that's it, if everything went good, we will have the following result

If you have any questions, feel free to comment here, or DM me on Twitter
Original Post
Thank you for following the tutorial, and I will see you in other ones.

How to test a Laravel package locally

Koussay — Sun, 12 Dec 2021 00:32:55 +0000

Howdy!

Lately I’ve been working on submitting a PR to a package, Laravel package to be precise.

I forked & cloned the project to my local machine. I made my adjustments, and then I want to test it, because it has a visual interface.

But I had a problem linking it an existing Laravel app to see those adjustments. So reading Composer docs, I found “Repositories”, and you can use it to link a local composer package, How ?

First of all, after cloning or creating your own package, you can link it in your main application by editing composer.json, adding this :


"repositories": [
        {
            "type": "path",
            "url": "../../awesome/package"

        }
    ]

Note: the url must be the full path to the package.
After that, add the package to the require section

And finally

composer update

Composer now will link the package to the main app, and any change you make in the package will be reflected immediately into your app.
Thank you for reading.

Laravel Mapbox, easily integrate Mapbox inside your Laravel app

Koussay — Mon, 29 Nov 2021 22:54:59 +0000

I have just released Laravel Mapbox, a Laravel package that allows you to add Mapbox to your views easily, with highly flexibility.
It requires Laravel 8 and PHP 8.0 and up.

Before installing the package, create a Mapbox account to get your token.

Installation

To install the package, all you have to do is run this command

composer require koossaayy/laravel-mapbox

After the installation, add this key to the .env file

MAPBOX_TOKEN={your mapbox token here}

And lastly publish the config file using this command :

php artisan vendor:publish --tag="mapbox-config"

Also don't forget to add CSS and JS files of Mapbox

<link href='https://api.mapbox.com/mapbox-gl-js/v2.6.0/mapbox-gl.css' rel='stylesheet' />
<script src='https://api.mapbox.com/mapbox-gl-js/v2.6.0/mapbox-gl.js'></script>

And that's It you're good to go

Usage

To show a map on a page, all you have to do is use :

<x-mapbox id="map" />

The package comes with a lot with other options, like markers, popups, interactivity, and a lot.
You may check them here

If you like the package, give it a star, and everyone is more than welcome to contribute ♥

Redirect User based on condition in Laravel Fortify

Koussay — Thu, 26 Nov 2020 22:37:24 +0000

3aslema (means Hello in Tunisian)
Recently I had a Laravel project, where I had to redirect users based on their role, to their dashboards.
I'm using Laravel 8, so I thought about using Laravel Fortify.
So after installing and configure it, create a new PHP file, name it, let's say "LoginResponse"
This class will implement the "LoginResponseContract" and it will override the "toResponse" method, and in that method we will implement the logic.
So the class will be like this

use Illuminate\Support\Facades\Auth;
use Laravel\Fortify\Contracts\LoginResponse as LoginResponseContract;

class LoginResponse implements LoginResponseContract
{

    /**
     * toResponse
     *
     * @param mixed $request
     * 
     * @return RedirectResponse
     */
    public function toResponse($request): RedirectResponse
    {
        if(Auth::user()->role === "Admin")
            return redirect()->route('admin');
        return redirect()->route('user');

    }

}

In this example, we will check the role of the authenticated user, if it's admin, we will redirect it the admin route, otherwise, we will redirect it the default route.

After creating the class, all you need to do now, is to bind the newly creating class to Fortify.

All you need to do is open FortifyServiceProvider.php, and in the boot method, add this code

        $this->app->singleton(\Laravel\Fortify\Contracts\LoginResponse::class, LoginResponse::class);

And that's it ♥

P.S : I'm not a Laravel Expert, I'm just writing real-world examples I encounter, so Please correct me if I'm wrong.