DEV Community: Iwobi Okwudili Frank

Mailpit and Laravel Integration: A Complete Guide for Local Email Testing

Iwobi Okwudili Frank — Sat, 26 Oct 2024 11:20:52 +0000

Mailpit is a local email testing tool, similar to MailHog or MailCatcher, used by developers to capture and inspect emails sent by an application during development. It provides a web-based interface where you can view, search, and debug email messages without actually sending them to a live email server.

It is a very useful and developer friendly tool but there is no adequate documentation on how to set it up in a Laravel app. That's what we'll do today.

Basic Setup

Install Mailpit: You can install it via Homebrew on macOS.

   brew install mailpit

If you are on Windows or Linux you can download the static binary. Read this guide for more information.

Run Mailpit: Start the Mailpit server by running:

   mailpit

Or set it up to run automatically by running:

   brew services start mailpit

Access Mailpit Web Interface: Open your browser and go to http://localhost:8025 to view incoming emails in the Mailpit UI.

Laravel Setup

Go to you .env file and input this setup

MAIL_MAILER=smtp
MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=your username @ your system name here
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_FROM_ADDRESS="hello@example.com"
MAIL_FROM_NAME="${APP_NAME}"

You can get your user and system name by running the following command

   echo "$(whoami)@$(hostname)"

That's all! Now whenever an email is sent from your laravel app you would be able to view it in the browser.

Deploy Laravel Projects to Namecheap Server on Github Push with 3 Easy Steps (The only tutorial you would every need)

Iwobi Okwudili Frank — Sat, 27 Jul 2024 17:42:28 +0000

Alright, I know the title is a bit cliche 😌 but you're about to find out why!

I've been a Laravel Developer for 3 years now, I've built some projects to test my skills during these times but lately I have this need to showcase other people what I've been up to and also have some projects on My Portfolio. Since these projects may get updates regularly and I definately do not want to always re-upload to my Namecheap Server every single time I make a change, I found a way to make Laravel Deployment to Namecheap work as seamlessly as VueJs to Vercel.

You may ask why I chose Namecheap and not other Hosting providers like Hostinger or Server Managemment tools like Laravel Forge and Plio.io that already have this functionality baked in, well, simple answer, "I'm broke 🥲", and I do what broke people do, find the cheapest alternative. Enough about me, let's dive in!

Step One - Set Up Git On Namecheap Server.

In order for this post not to get too long, i'll assume you already:

Registered a Namecheap Account.
Bought a Hosting Account (I use shared hosting).
Have a domain setup on the hosting account, you can follow (this guide), if you have an existing hosting server, you can check out this guide to add a domain as an addon to a server.
Have a Github Account.
Have a Laravel Project you want to host.

With all these set up, we're good to go.

Log into your Namecheap Hosting Server and visit the "Terminal" tab.

You can also search for it.

If for some reason you do not have the Terminal Tab, go to the Manage Shell Tab and make sure the enable ssh access is toggled on.

Haven done that, you can now visit the terminal tab.

Git is already installed on all Namecheap Hosting Servers but to confirm you can run this command.

git --version

Make sure your Git version is at least 2.28 before proceeding. Update Git if it isn't.

Now it's time link your Github account to your Namecheap Server. You should first set up your local profile.

git config --global user.name "Your Name"
git config --global user.email "yourname@example.com"

replace with your name and the email address you use for Github

If you use private GitHub email address, the second command will look something like this:

git config --global user.email "123456789+franklin@users.noreply.github.com" # Remember to use your own private GitHub email here.

GitHub recently changed the default branch on new repositories from master to main. Change the default branch for Git using this command:

git config --global init.defaultBranch main

To enable colorful output with git, type

git config --global color.ui auto

You’ll also likely want to set your default branch reconciliation behavior to merging.

git config --global pull.rebase false

To verify that things are working properly, enter these commands and verify whether the output matches your name and email address.

git config --get user.name
git config --get user.email

Create an SSH Key

An SSH key is a cryptographically secure identifier. It’s like a really long password used to identify your machine. GitHub uses SSH keys to allow you to upload to your repository without having to type in your username and password every time.

First, we need to see if you have an Ed25519 algorithm SSH key already installed. Type this into the terminal and check the output with the information below:

ls ~/.ssh/id_ed25519.pub

If a message appears in the console containing the text “No such file or directory”, then you do not yet have an Ed25519 SSH key, and you will need to create one. If no such message has appeared in the console output, you can skip the next step.

To create a new SSH key, run the following command inside your terminal.

ssh-keygen -t ed25519

When it prompts you for a location to save the generated key, just push Enter.
Next, it will ask you for a password; enter one if you wish, but it’s not required.

Link your SSH key with GitHub

Now, you need to tell GitHub what your SSH key is so that you can push your code without typing in a password every time.

First, you’ll navigate to where GitHub receives our SSH key. Log into GitHub and click on your profile picture in the top right corner. Then, click on Settings in the drop-down menu.

Next, on the left-hand side, click SSH and GPG keys. Then, click the green button in the top right corner that says New SSH Key. Name your key something that is descriptive enough for you to remember what device this SSH key came from, for example Namecheap Server. Leave this window open while you do the next steps.

Now you need to copy your public SSH key. To do this, we’re going to use a command called cat to read the file to the console. (Note that the .pub file extension is important in this case.)

cat ~/.ssh/id_ed25519.pub

Highlight and copy the entire output from the command. If you followed the instructions above, the output will likely begin with ssh-ed25519 and end with your username@hostname.

Now, go back to GitHub in your browser window and paste the key you copied into the key field. Keep the key type as Authentication Key and then, click Add SSH key. You’re done! You’ve successfully added your SSH key!

Testing you key

Follow the GitHub directions for testing your SSH connection. Make sure the fingerprint output in the terminal matches one of the four GitHub’s public fingerprints. (Don’t forget to omit the $ when you copy and paste the code!).

You should see this response in your terminal: Hi username! You’ve successfully authenticated, but GitHub does not provide shell access. Don’t let GitHub’s lack of providing shell access trouble you. If you see this message, you’ve successfully added your SSH key and you can move on. If the output doesn’t correctly match up, then try going through these steps again.

Step Two - Clone Laravel Project To Your Namecheap Server.

Search for "SSH Access" on your cPanel and click on the first result. Click on Manage SSH Keys.

Find the SSH key you just generated (it should the only one for you, or last one), click and manage, and Authorize.

Now, search for Git version control and open the first option. Click on Create.

Set the clone Repo URL and set the Repository Path (directory to clone your Github Repo).

Set the Repository Name and click create.

Remember that the directory you are cloning to must be empty, else you would get an error.

If everything goes well you should have something like this:

Now you can easily go to your terminal, cd into your project directory and run composer install and all those other Laravel commands but where's the fun in that 😁

Final Step - Set Up Deploy On Push.

This is the topping on the ice, for this we'll use Github Webhooks and good ole' .htaccess file. Let's see how.

Laravel has a thing where it use the public directory as the root directory, this way, sensitive files and directory are secured, database management tools like Laravel Forge does this for you automatically but we'll have to it ourselves.

To get your project up and ready, you should create a .env file on the root of your project directory and setup Application Key and every other thing you would normally do in a typical Laravel app.

Now, you should create a .htaccess file on the root directory. Then paste the following code:

<IfModule mod_rewrite.c>
    RewriteEngine On

    # Redirect Trailing Slashes If Not A Folder...
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)/$ /$1 [L,R=301]

    # Ensure Authorization header is passed to PHP
    RewriteCond %{HTTP:Authorization} .
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

    # Redirect to the public folder
    RewriteCond %{REQUEST_URI} !^/public/
    RewriteRule ^(.*)$ /public/$1 [L]
</IfModule>

# Deny access to .env file
<Files .env>
    Order allow,deny
    Deny from all
</Files>

# Deny access to composer.json and composer.lock
<FilesMatch "^composer\.(json|lock)$">
    Order allow,deny
    Deny from all
</FilesMatch>

# Deny access to artisan
<Files artisan>
    Order allow,deny
    Deny from all
</Files>

# Deny access to anything starting with a dot
<Files ~ "^\.">
    Order allow,deny
    Deny from all
</Files>

# Prevent directory listing
Options -Indexes

This piece of code sets the public directory as the root directory and enables other security checks.

The next thing we want is a public route that is accessible to the internet, however we do not want everyone to have access to this file, rather we want only the Github IP to access it, since we will be receiving events from there. We can also use a .htaccess file for this.

Go to the public directory, create a file to store our deployment script, I would call mine deployment.php.

Open the file and paste the following code:

<?php

// Your secret key for verification
$secret = 'webhook password'; // you will use this when creating a webhook

// Get the payload from GitHub
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_HUB_SIGNATURE'];

// Verify the payload signature
list($algo, $hash) = explode('=', $signature, 2);
if ($hash !== hash_hmac($algo, $payload, $secret)) {
    header('HTTP/1.1 403 Forbidden');
    exit;
}


// Define the project root directory
$projectRoot = '/home/servername/projectdirectory';

// Pull the latest changes from the repository
$output = shell_exec("cd $projectRoot && git pull 2>&1");
echo "<pre>Git Pull Output:\n$output</pre>";

// Run composer install
$output = shell_exec("cd $projectRoot && composer install --no-interaction --prefer-dist --optimize-autoloader 2>&1");
echo "<pre>Composer Install Output:\n$output</pre>";

// Run artisan commands
$output = shell_exec("cd $projectRoot && php artisan optimize:clear 2>&1");
echo "<pre>Artisan Output:\n$output</pre>";

$output = shell_exec("cd $projectRoot && php artisan optimize 2>&1");
echo "<pre>Artisan Output:\n$output</pre>";

$output = shell_exec("cd $projectRoot && php artisan migrate 2>&1");
echo "<pre>Artisan Output:\n$output</pre>";

$output = shell_exec("cd $projectRoot && php artisan storage:link 2>&1");
echo "<pre>Artisan Output:\n$output</pre>";

?>

You can edit the artisan commands to meet your personal needs.

The last thing we need to do before moving over to Github is to protect the deployment.php file.

There is a .htaccess file on the public directory, it comes with all Laravel installation. That's where we would do that. Open the file and add the following code:

<Files "deployment.php">
    Order allow,deny
    Deny from all
    Allow from 192.30.252.0/22
    Allow from 185.199.108.0/22
    Allow from 140.82.112.0/20
</Files>

So the whole file content should look like this:

<IfModule mod_rewrite.c>
    <IfModule mod_negotiation.c>
        Options -MultiViews -Indexes
    </IfModule>

    RewriteEngine On

    # Handle Authorization Header
    RewriteCond %{HTTP:Authorization} .
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

    # Redirect Trailing Slashes If Not A Folder...
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_URI} (.+)/$
    RewriteRule ^ %1 [L,R=301]

    # Send Requests To Front Controller...
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
</IfModule>

<Files "deployment.php">
    Order allow,deny
    Deny from all
    Allow from 192.30.252.0/22
    Allow from 185.199.108.0/22
    Allow from 140.82.112.0/20
</Files>

Set up Github Webhook

Log into your Github account and open your project repository. Go to Settings and click on Webhooks, located on the left side panel, press Add New.

Provide all required informations and proceed to add webhook. The payload type should be application/json and the webhook url should be a link to the deployment script on your server. Here's mine:

That's all! 🥳

Now, whenever you push to your Github Repository, the code automatically deploys to the server.

If you did everything correctly, the webhook will look like this on your next push.

If you have any issues or questions you can comment below and I'll try to help as best as I can.

You can support by following me on X (formally Twitter). Thank you.

Happy Coding!

Mastering Global Functions in Laravel: Easy Methods for Versions 8,9,10,11.

Iwobi Okwudili Frank — Thu, 04 Apr 2024 18:15:16 +0000

If you've ever found yourself seeking for efficient ways to have global functions in your Laravel apps you're in the right place. Global functions offer a convenient way to enhance the functionality and productivity of your Laravel apps as you only have to write a function once and have access to it in any part of your app, in this comprehensive tutorial, we'll explore the easiest methods to achieve this. Whether you're a seasoned Laravel developer or just starting your journey, this guide will equip you with the knowledge and tools to leverage global functions effectively, making your development experience smoother and more efficient. Let's dive in!

For this example, we'll be displaying the user count on different pages, it may not a very good example but it would give you an idea on how to implement such functionality in you own app. Let's dive in!

Get your Laravel App running.

In this step we will install a fresh Laravel project using the Laravel installer, you can also use composer or any other means you use to get your Laravel applications up and running.

As at the time of writing this post, Laravel is on version 11. You have to make sure you have a PHP version of at least 8.2. We will now create a Laravel project with the new command:

I would not be using any starter kit for this example.

After installation, let's open the project on our code editor, I'm using Virtual Studio Code.

Serve the application and open on the browser:



php artisan serve

Let's get to the main job!

Now that our Laravel app is running, we can now start writing code. For the sake of this example, I'll populate the database with 35 users using the default UserFactory that comes with every Laravel installation. I'll use tinker for ease.

After that let's first display the users count on the home page, let's delete everything on the welcome.blade.php file and write this:



Total users: {{ $users }}

While on the web.php file, we do this:



<?php

use App\Models\User;
use Illuminate\Support\Facades\Route;

Route::get('/', function () {
    return view('welcome', [
        'users' => User::count()
    ]);
});

Our home page should look like this now:

We can now see that if we want to see a count of users on different pages we would have to repeat this line of code on both the view file and route file, this is a lot of work. Let's create a Global Function. There are so many ways to create a global function in Laravel but the best way is using a Service Provider. We'll create it through the terminal, you can name it what ever you want but I'll call mine GlobalFunctionsServiceProvider



php artisan make:provider GlobalFunctionsServiceProvider

This command creates a file on the App\Providers directory. Note that in Laravel 11, you do not need to register this provider in the app.php providers array since it is auto-discovered by Laravel but if you're using a lower version of Laravel you would need to do so. Just open the Config/app.php file and add it to the providers array like this:



'providers' => ServiceProvider::defaultProviders()->merge([
        /*
         * Package Service Providers...
         */

        /*
         * Application Service Providers...
         */
        App\Providers\AppServiceProvider::class,
        App\Providers\AuthServiceProvider::class,
        // App\Providers\BroadcastServiceProvider::class,
        App\Providers\EventServiceProvider::class,
        App\Providers\RouteServiceProvider::class,
        App\Providers\GlobalFunctionsServiceProvider::class, //our custom provider
    ])->toArray(),

Note: You do not need the above step if you're in Laravel 11

Now let's create a file to store our functions, I'll create mine in App\Functions\GlobalFunctions.php After that, open your GlobalFunctionsServiceProvider.php file and add the following code in the register method



<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;

class GlobalFunctionsServiceProvider extends ServiceProvider
{
    /**
     * Register services.
     */
    public function register(): void
    {
        require_once base_path().'/app/Functions/GlobalFunctions.php';
//remeber to point to the path of the file where your functions are
    }

    /**
     * Bootstrap services.
     */
    public function boot(): void
    {
        //
    }
}

Now let's write our global function. Open your GlobalFunctions.php file and write the following code



<?php

use App\Models\User;

function users_count()
{
    return User::count();
}

We can now remove the users key from our web.php routes file



<?php

use Illuminate\Support\Facades\Route;

Route::get('/', function () {
    return view('welcome');
});

And edit our welcome.blade.php file to use the function we wrote earlier



Total users: {{ users_count() }}

You can see now that we have the same result on the browser! With this approach, you can call the users_count() function from any part of your application, whether view, controller, class, config files, anywhere, and be certain to get the same result.

You can customize the code to fit your use case, this was just an example.

The source code for this example is on this Github repo.

Thank you. Happy coding.

You can follow me on X(former twitter) if you found this article helpful.