Forem: Carlos Santos

⛵ Laravel Sail - Windows 10 Installation

Carlos Santos — Sun, 04 Sep 2022 23:31:22 +0000

Laravel Sail is a light-weight command-line interface for interacting with Laravel's default Docker development environment. Sail provides a great starting point for building a Laravel application using PHP, MySQL, and Redis without requiring prior Docker experience.

At its heart, Sail is the docker-compose.yml file and the sail script that is stored at the root of your project. The sail script provides a CLI with convenient methods for interacting with the Docker containers defined by the docker-compose.yml file.

Laravel Sail is supported on macOS, Linux, and Windows (via WSL2).

Install Docker Desktop

https://docs.docker.com/desktop/install/windows-install/

After the installation is complete go to your windows user directory (C:\Users\YOURUSER) and create a file named .wslconfig with the following content:

[wsl2]
memory=2GB # Limits VM memory in WSL 2 
processors=4 # Makes the WSL 2 VM use 4 virtual processors
localhostForwarding=true # Boolean specifying if ports bound to wildcard or localhost in the WSL 2 VM should be connectable from the host via localhost:port.
swap=8GB

You will need to restart your computer after this step.

WSL2 Configuration

Install Ubuntu distribution and set it as default using Windows PowerShell.

# Check list of available distributions
wsl --list --verbose

wsl --set-default-version 2

# Install Ubuntu-20.04 distribution
# Don't forget to add a user with password on this step
wsl --install -d "Ubuntu-20.04"

# Set distribution as default
wsl -s Ubuntu-20.04

# Start distribution
wsl -d Ubuntu-20.04

Then run wsl --list --verbose at the end and the Ubuntu distribution should look like this:

Now make sure Docker Desktop settings look like this:

Install PHP in Ubuntu 20.04 distribution.

In Windows Power Shell run the command wsl to start a new Ubuntu session. Once inside the Ubuntu terminal run:

sudo apt update
sudo add-apt-repository -y ppa:ondrej/php
sudo apt install -y php8.1-common php8.1-cli
sudo apt install -y php8.1-curl php8.1-gd php8.1-mbstring php8.1-xml php8.1-zip
php --version

Composer 2 should also be installed. Check version by running composer -V . If it is not installed follow this installation guide: https://www.digitalocean.com/community/tutorials/how-to-install-composer-on-ubuntu-20-04-quickstart

Conclusion

Now you should be able to run a laravel project with sail.

Adding Sail to a Project

Move to the project root directory and run:

composer require laravel/sail --dev
php artisan sail:install

# Start docker container
./vendor/bin/sail up

Running the container in a project with Sail already initialized (Existing docker-compose.yml):

# Start docker container
./vendor/bin/sail up

Sometimes container start might fail and its related to permissions issues so be mindful of where to place your project files and give them the proper permissions. (or run it with sudo prefix)

📋 Related articles

Laravel Sail installation guide

https://laravel.com/docs/9.x/installation#getting-started-on-windows

Laravel Sail usage guide

https://laravel.com/docs/9.x/sail#introduction

🔐 Laravel File Permissions Setup

Carlos Santos — Sat, 21 May 2022 23:35:17 +0000

Introduction

Hi, I wanted to offer a brief and straight to the point way to setup your Laravel project permissions. This examples are like a work for all case. You will have to taken into consideration your server users, configurations, etc.
‎‎
There are basically two ways to setup your ownership and permissions. Either you give yourself ownership or you make the webserver the owner of all files.

‏‏‎

Web Server as owner (Recommended for PROD)
Webserver as owner (the way most people do it, and the Laravel doc's way):

Assuming www-data (it could be something else) is your webserver user.

sudo chown -R www-data:www-data /path/to/your/laravel/root/directory

If you do that, the webserver owns all the files, and is also the group, and you will have some problems uploading files or working with files via FTP, because your FTP client will be logged in as you, not your webserver, so add your user to the webserver user group:

sudo usermod -a -G www-data ubuntu

Of course, this assumes your webserver is running as www-data (the Homestead default), and your user is ubuntu (it's vagrant if you are using Homestead).

Then you set all your directories to 755 and your files to 644... SET file permissions

sudo find /path/to/your/laravel/root/directory -type f -exec chmod 644 {} \;

Set directory permissions

sudo find /path/to/your/laravel/root/directory -type d -exec chmod 755 {} \;

Then you need to give read and write permissions to the webserver for storage, cache and any other directories the webserver needs to upload or write:

sudo chgrp -R www-data storage bootstrap/cache  
sudo chmod -R ug+rwx storage bootstrap/cache

‏‏‎

Your user as owner (Convenient for STAGING and DEV)

If you prefer to own all the directories and files (it makes working with everything much easier), go to your Laravel root directory:

cd /var/www/html/laravel >> assuming this is your current root directory

‏‏‎ ‎
If you do that, the webserver owns all the files, and is also the group, and you will have some problems uploading files or working with files via FTP, because your FTP client will be logged in as you, not your webserver, so add your user to the webserver user group:

sudo usermod -a -G www-data ubuntu

sudo chown -R $USER:www-data .

Then you give your user and the webserver permissions:

sudo find . -type f -exec chmod 664 {} \;  
sudo find . -type d -exec chmod 775 {} \;

‏‏‎
Then you need to give read and write permissions to the webserver for storage, cache and any other directories the webserver needs to upload or write:

sudo chgrp -R www-data storage bootstrap/cache  
sudo chmod -R ug+rwx storage bootstrap/cache

‏

Conclusion

I hope you found this article helpful.

If you have any feedback or found mistakes, please don’t hesitate to reach out to me.

Credit to: Andres Felipe and bgies answers.

NestJS ⚡ Multiple DB Setup with TypeORM

Carlos Santos — Sat, 07 May 2022 03:37:50 +0000

Introduction

Hi, in this post I will describe how to setup and use multiple database connections with a simple example.

NestJS Documentation is great for the most part but it has some important omissions on the multiple databases section.

I will proceed under the assumption that you already have created a NestJS application and have your 2 or more databases setup and ready to be connected to. Let's go straight to the point.
 

Let's get to it

Define DB connection options

Following NestJS docs we will find the connection options example credentials directly set on code.

...
@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: 'mysql',
      host: 'localhost',
      port: 3306,
      username: 'root',
      password: 'root',
      database: 'test',
      entities: [Customer],
      synchronize: true,
    }),
  ],
})
...

Instead of having credentials exposed on the code like that we should use an environment configuration file or a similar strategy.

For this example we will make use of the @nestjs/config package to get the database credentials from an environment file. You can find more information about how to install and use the config package at NestJS Configuration Docs. It is a simple process.

...
@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
    }),
    TypeOrmModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: async (configService: ConfigService) => {
        return {
          type: 'mssql',
          host: configService.get('MAIN_DB_HOST'),
          port: parseInt(configService.get('MAIN_DB_PORT')),
          database: configService.get('MAIN_DB_DATABASE'),
          username: configService.get('MAIN_DB_USERNAME'),
          password: configService.get('MAIN_DB_PASSWORD'),
          schema: configService.get('MAIN_DB_SCHEMA'),
          entities: [Customer],
          synchronize: false,
        };
      },
    }),
...

We don't need to define a connection name four our first connection. It will be named 'default' by default 😬. For any other defined connections we will need to provide a name.

NestJS docs tells us that the name property should be added inside the options object, at the same level as host, port, etc.

...
@Module({
  imports: [
    TypeOrmModule.forRoot({
      ...defaultOptions,
      host: 'user_db_host',
      entities: [User],
    }),
    TypeOrmModule.forRoot({
      ...defaultOptions,
      name: 'albumsConnection',
      host: 'album_db_host',
      entities: [Album],
    }),
  ],
})
...

Now, because we are getting our credentials from the .env file and using forRootAsync we need to add the connection name property outside of the useFactory function 👀. This is a really important detail that is not mentioned anywhere in the docs.

The final app.module.ts file should look like this.

Entities

We have created two entities for the sake of this excercise. Customer entity will use the main db connection and AccessLog entity will use the secondary db connection. For more information about TypeOrm Entity and Repository pattern check out NestJS TypeOrm Docs and TypeOrm Docs.
 

Use Main DB Connection

In order to have access to the Customer entity TypeOrm functionality we need to import TypeOrm into the Customer module.

And this is how we use it in the Customer service.

Use Secondary DB Connection

As we did for the main connection and the Customer entity we need to import TypeOrm into the AccessLog module, but this time we will also need to pass a connection name to the TypeOrmModule.forFeature([Entities, ...], connectionName) method.

And this is how we use it in the AccessLog service.

Conclusion

✅ We managed to setup a multiple db configuration with credentials values coming from an environment file.
✅ Defined what connection should each entity use.
✅ With the knowledge of how to add a secondary connection we should be able to add many more as needed.
✅ Learned about the little gotchas when initializing TypeOrm asynchronously.

I really hope this article was helpful.

If you have any feedback or found mistakes, please don’t hesitate to reach out to me.

Laravel Mailtrap Setup

Carlos Santos — Sat, 18 Dec 2021 21:57:19 +0000

Introduction

How will this email look? Will it look nice on mobile? Is the email data correct? You can test all that and more with Mailtrap.

Mailtrap is a testing tool designed to trap any emails coming out of your application. Setting up Mailtrap is a must for your development environment, this way you can test your application functionalities without worrying about spamming real users.

Step 1: Mailtrap Account

Go to https://mailtrap.io/ and sign up.
Once you are logged in you will see a menu with 3 options; Inboxes, API, and Billing. Go to Inboxes.

On the Inboxes page you will see a list of your inboxes and you will also have the option of creating a new project or creating a new inbox. We will use the default inbox for this setup.
Click on the inbox and on SMTP Settings select Integrations -> Laravel.

Here you will see the .env variables you need to copy.

Step 2: Laravel Configuration

Add (or replace) mail environment variables from Mailtrap to your application .env file.

MAIL_MAILER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=YOUR_INBOX_USERNAME
MAIL_PASSWORD=YOUR_INBOX_PASSWORD
MAIL_ENCRYPTION=tls

# Also
MAIL_FROM_ADDRESS=no-reply@test.local
MAIL_FROM_NAME="Mailtrap Test App"

Step 3: Test

Create simple test mailable with markdown.
php artisan make:mail MailtrapTest --markdown=emails.test

App\Mail\MailtrapTest.php

<?php

namespace App\Mail;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;

class MailtrapTest extends Mailable
{
    use Queueable, SerializesModels;

    /**
     * Create a new message instance.
     *
     * @return void
     */
    public function __construct()
    {
        //
    }

    /**
     * Build the message.
     *
     * @return $this
     */
    public function build()
    {
        return $this->markdown('emails.test');
    }
}

resources\views\emails\test.blade.php (Markdown file)

@component('mail::message')
# TEST EMAIL

The cake is a lie

Thanks,<br>
{{ config('app.name') }}
@endcomponent

Add test route

...
...

Route::get('/mailtrap/test', function () {
    // Using a temp email. 
    // This way we can test that emails are really trapped.
    $testEmail = 'rognodugni@vusra.com';

    return Mail::to($testEmail)->send(new MailtrapTest());
});

...
...

Now hit test URL. You should have a new email on your Mailtrap inbox and you should not have any email from your application on the test email inbox.

Conclusion

Mailtrap is a very useful tool for development and it's super easy to setup with Laravel. You can find more information at https://mailtrap.io/blog/send-email-in-laravel/

I hope this article was helpful.

If you have any feedback or found mistakes, please don’t hesitate to reach out to me.

✉ Laravel Twilio SMS Implementation

Carlos Santos — Wed, 15 Dec 2021 01:54:24 +0000

Introduction

Twilio integrations have been a lot more common than I thought during the last few years. So I wanted to write the article I wish I have found the first time a had to do it.

Twilio's SMS API is a flexible building block that can take you from sending your first text message all the way to sending and receiving millions.
In this article, I will talk about how to set up a Laravel application Twilio configuration and start sending SMS.

After that, we will dig deeper into how to keep track of the status of sent messages and keep a local updated representation of Twilio messages.

Finally, we will prepare the application to receive notifications every time your defined Twilio phone number gets a message and then store the received message locally.

Configuration and sending the first SMS

1. Get Twilio Credentials and Phone Number

Keep in mind that a trial phone number can only send SMS to verified phones. This means you will have to add the phone number you intend to send messages to a verified numbers list.

2. Add Twilio Credentials to Laravel configuration.

.env file

TWILIO_SID=YOUR_ACCOUNT_SID
TWILIO_AUTH_TOKEN=YOUR_ACCOUNT_AUTH_TOKEN
TWILIO_FROM_NUMBER=YOUR_ACCOUNT_FROM_NUMBER(e.g. +1XXXXXXXXXX)

/config/app.php

'twilio' => [
    'sid' => env('TWILIO_SID'),
    'auth_token' => env('TWILIO_AUTH_TOKEN'),
    'from_number' => env('TWILIO_FROM_NUMBER')
]

3. Install Twilio SDK for PHP
composer require twilio/sdk

4. Create Twilio Service Class
It is convenient to handle all Twilio SMS operations from a single class that is globally available. So every time you send a message you will do it through this service.

Remember to bind the service so it is globally accessible. In this case, we will create a provider CustomServiceProvider and bind TwilioService in the boot function.

php artisan make:provider CustomServiceProvider

And then add App\Providers\CustomServiceProvider::class into the $providers array on config/app.php.

Now the TwilioService should be available and we can test it from anywhere.

Also not required, but it will be convenient to add a new channel at /config/logging.php to log Twilio operations, at least for debugging.

...
'twilio' => [
    'driver' => 'single',
    'path' => storage_path('logs/twilio.log'),
    'level' => 'debug',
],
...

5. Create Twilio SMS Controller.
If you only care about sending messages then you don't really need to create a controller. You can test and use the TwilioService sendMessage function from anywhere.

For this implementation, we will use this controller to provide a sendTest function. Later it will also be used to handle Twilio SMS Status Callback requests and Twilio SMS Received requests.

php artisan make:controller TwilioSmsController

Add testing endpoint to your API routes.

Route::any(
'/twilio/send-test',
[TwilioSmsController::class, 'sendTest'])
->name('twilio.send-test');

You are ready to make your first test. Hopefully, everything goes right on the first try. If not, you will get a debug error message.

Common errors you can get:

Invalid number. The provided To number must have E.164 formatting.
To phone number not verified. If you are using a trial phone number then you can only send SMS to verified numbers.
Permission to send an SMS has not been enabled for the region indicated by the 'To' number.

That's it! 🎉 If you only need to send messages then you are ready to go.

If you want to keep track of the messages you sent and also be able to receive messages in your application then keep reading 👀.

Track Twilio SMS status changes

When we make a send SMS request to Twilio the message has to go through a sequence of statuses.

accepted
queued
sending
sent
delivery_unknown
delivered
undelivered
failed

The response we get from making a successful send SMS request will tell us that the message status is queued. This just means that Twilio accepted the request and it was added to the queue of messages to send, but we don't know if it was actually sent.

If we want to keep track of an SMS status we have to provide a statusCallback parameter on each request. The statusCallback will be the URL to a webhook in our application that will be prepared to receive requests from Twilio.

1. Create TwilioSms Model and TwilioSmsLog Model.
TwilioSms will represent a Twilio SMS in our application and TwilioSmsLog will represent each event related to an SMS (status change, error, etc).

php artisan make:model TwilioSms -m
php artisan make:model TwilioSmsLog -m

Models

Migrations

2. Create status callback webhook route and implement Twilio Request Validation middleware.
Add new webhook url to api routes.

/**
 * Twilio statusCallBack webhook
 * is-twilio-request middleware makes sure only twilio has access to this route
 */
Route::any('/twilio/webhook/status-changed', [TwilioController::class, 'statusChanged'])->middleware(['is-twilio-request'])->name('api.twilio.status-changed');

Notice that we are using the middleware is-twilio-request. This route will be open to the public so we need to make sure that it only serves valid requests from Twilio. We can accomplish that by using the RequestValidator method provided by the Twilio PHP SDK.

Create Middleware
php artisan make:middleware TwilioRequestIsValid

Add the new middleware to app/Http/Kernel.php $routeMiddleware array.

/**
 * The application's route middleware.
 *
 * These middleware may be assigned to groups or used individually.
 *
 * @var array
 */
protected $routeMiddleware = [
    ...
    'is-twilio-request' => \App\Http\Middleware\TwilioRequestIsValid::class,
];

3. Update Twilio Service. Add status callback, create TwilioSmsModel on send and log.

TwilioService final version:

Now every time we make a sendMessage request the following will happen:

Add callback URL to sendMessage request.
If the request was successful create TwilioSms record on DB.
Create TwilioSmsLog.

Created message.

Created log.

4. Handle Twilio Status Changed Request.
Add statusChanged Method to TwilioSmsController. The logic is just an example of implementation. You can make any adjustment as long as you return response(['success' => true], 200).

In summary, we log every request and if we can match the request with an SMS in our application and the request status is different from the current TwilioSms status we update it.

TwilioSmsController with status changed method:

With the webhook in place, we will start to see our messages go through different states. It usually just takes a few seconds to go from queued to sent.

It will look like this in the database.

That’s it for it tracking SMS status changes and keeping an updated representation of each Twilio SMS sent by the application. The next step is to receive and store messages.

Receive SMS

1. Create messageReceived method on TwilioSmsController.

TwilioSmsController final version:

2. Add webhook route.

...
...
/**
* Twilio message received webhook
* is-twilio-request middleware makes sure only twilio has access to this route
*/
Route::any('/twilio/webhook/message-received', [TwilioSmsController::class, 'messageReceived'])
->middleware(['is-twilio-request'])
->name('api.twilio.message-received');
...
...

3. Add webhook URL to a phone number in Twilio console.

Find your phone number details page.

Click on the phone number you want to manage and then find the Messaging section on the details page. Here you can define a “message comes in” action. Select webhook and input your webhook URL.

Save and you are all set to start receiving SMS in your application.

Whenever a message comes in we are going to create a TwilioSms record and a TwilioSmsLog record.

Conclusion

We accomplished:
✅ Send SMS.
✅ Track Sent SMS Status.
✅ Keep local updated representation of a Twilio SMS.
✅ Every time a Twilio phone receives a message we get it and store it.

Possible gotchas:

Test with phone numbers in E.164 formatting.
Trial phone numbers can only send messages to verified numbers.
Sometimes sending a message to a region is disabled, so you have to enable the region on the Twilio console.
Webhook URL must be publicly accessible. No auth. Not behind a server configuration restriction.

I hope this article was helpful.

If you have any feedback or found mistakes, please don’t hesitate to reach out to me.