Forem: Zubair Mohsin

Why Laravel requires `ramsey/uuid` package?

Zubair Mohsin — Sun, 02 May 2021 12:58:52 +0000

From the About section on GitHub of ramsey/uuid package:

A PHP library for generating universally unique identifiers (UUIDs).

First thing we notice that its not a Laravel package, instead a PHP library and it can be used in any PHP project. Secondly, universally unique identifiers (UUIDs), let's talk a bit about what are UUIDs.

What is a UUID?

UUID stands for Universally Unique Identifier. When it says Universally, it truly means Universally.

When you generate a UUID, its uniqueness can be guaranteed across space and time.

A UUID is 128 bits long and is usually represented as a hexadecimal string split into five groups with dashes, like below:

998fd066-c786-4064-9c98-e378e450cd4a

We can use these unique values and assign them to our database records and later identify the records by these hexadecimal strings.

UUIDs in Laravel

Laravel framework is famous for best Developer Experience (DX), therefore, Laravel makes it a cinch to work with UUIDs. If you open the tinker in Laravel project and write below code snippet:

(string) Str::uuid();

You'll get an output like below:

"220b94fc-04f9-48eb-a14a-ba868ff43919"

It's just that simple to create UUIDs in Laravel. Now let's take a look at how it works and where ramsey/uuid package comes into play.

Code Dive

If we dive into the definition of Str::uuid() method, we see the following:

<?php

namespace Illuminate\Support;

use Ramsey\Uuid\Uuid;

class Str
{

    /**
     * The callback that should be used to generate UUIDs.
     *
     * @var callable
     */
    protected static $uuidFactory;


    /**
     * Generate a UUID (version 4).
     *
     * @return \Ramsey\Uuid\UuidInterface
     */
    public static function uuid()
    {
        return static::$uuidFactory
                    ? call_user_func(static::$uuidFactory)
                    : Uuid::uuid4();
    }

    /**
     * Set the callable that will be used to generate UUIDs.
     *
     * @param  callable|null  $factory
     * @return void
     */
    public static function createUuidsUsing(callable $factory = null)
    {
        static::$uuidFactory = $factory;
    }

}

If we first call createUuidsUsing() method and provide a callback that will create UUIDs, then uuid() method will execute that callback to generate a UUID. But if that's not the case, it will use Uuid::uuid4() from ramsey/uuid to generate the UUID for us. This is how Laravel is able to generate UUIDs by leveraging ramsey/uuid package.

You might be wondering about why this method is named as uuid4() ? What does 4 mean here?

There are five versions of UUIDs. Each version has different algorithm to generate it. Read more about all versions in ramsey/uuid package docs.

UUIDs in Laravel migrations

Laravel provides a handy method on Illuminate\Database\Schema\Blueprint class named uuid to specify in migrations that this column will be used to store a UUID.

$table->uuid('id');

You might wonder if there's a column type in database which stores UUIDs, but that's not the case. If we look inside the Illuminate\Database\Schema\Grammars\MySqlGrammar class and find the typeUuid() method, we can see the following:

    /**
     * Create the column definition for a uuid type.
     *
     * @param  \Illuminate\Support\Fluent  $column
     * @return string
     */
    protected function typeUuid(Fluent $column)
    {
        return 'char(36)';
    }

Which means that $table->uuid() will be translated to a column wich char data type and its length would be 36 characters, always.

Laravel does not generate UUIDs automatically for uuid columns. Developer must provide the logic to generate UUIDs when inserting records in the database.

Interesting facts about `ramsey/uuid` in Laravel context

This package was first required on 08 Aug, 2016 by Taylor Otwell when he worked on channel specific notifications. UUIDs were used to identify the database notifications.
Link to commit by Taylor Otwell.
Version ~3.0 was used initially in Laravel v5.3
UUID helper methods were introduced in Laravel v5.6.
Link to commit by Taylor Otwell which added the helper methods

I hope you enjoyed this post. Next, we will see why Laravel requires swiftmailer/swiftmailer package. You can follow me on Twitter or join my newsletter for more content.

Why Laravel requires `psr/container` package?

Zubair Mohsin — Sat, 17 Apr 2021 10:16:20 +0000

From the About section of psr/container package on GitHub:

This repository holds all interfaces related to PSR-11 (Container Interface).
Note that this is not a Container implementation of its own. It is merely abstractions that describe the components of a Dependency Injection Container.

If we look at the code in this repository we can see that there are only three interface files.

ContainerInterface
ContainerExceptionInterface
NotFoundExceptionInterface

Let's take a look at ContainerInterface interface file:

<?php

declare(strict_types=1);

namespace Psr\Container;

/**
 * Describes the interface of a container that exposes methods to read its entries.
 */
interface ContainerInterface
{
    /**
     * Finds an entry of the container by its identifier and returns it.
     *
     * @param string $id Identifier of the entry to look for.
     *
     * @throws NotFoundExceptionInterface  No entry was found for **this** identifier.
     * @throws ContainerExceptionInterface Error while retrieving the entry.
     *
     * @return mixed Entry.
     */
    public function get(string $id);

    /**
     * Returns true if the container can return an entry for the given identifier.
     * Returns false otherwise.
     *
     * `has($id)` returning true does not mean that `get($id)` will not throw an exception.
     * It does however mean that `get($id)` will not throw a `NotFoundExceptionInterface`.
     *
     * @param string $id Identifier of the entry to look for.
     *
     * @return bool
     */
    public function has(string $id): bool;
}

It has two method signatures. get() and has(). Any class that implements that interface must have definitions for these two methods. Let's see if Laravel's container has these methods.

Laravel Container

I am assuming every Laravel Developer knows that there's a Container. It's simply a class somewhere in the framework code. Let's perform a search in our code editor. We find two files named Container.

Illuminate\Contracts\Container\Container.php , this is an interface
Illuminate\Container\Container , this is an implementation of above interface

If we look at the above mentioned Container interface file we can see that Laravel is extending the ContainerInterface from psr/container package and also adds some method signatures of its own.

<?php

namespace Illuminate\Contracts\Container;

use Closure;
use Psr\Container\ContainerInterface;

interface Container extends ContainerInterface
{
    /**
     * Determine if the given abstract type has been bound.
     *
     * @param  string  $abstract
     * @return bool
     */
    public function bound($abstract);
}

Now let's take a look at Laravel's Container implementation class.

<?php

namespace Illuminate\Container;

use Illuminate\Contracts\Container\Container as ContainerContract;

class Container implements ContainerContract
{
    /**
     *  {@inheritdoc}
     */
    public function get($id)
    {
        try {
            return $this->resolve($id);
        } catch (Exception $e) {
            if ($this->has($id) || $e instanceof CircularDependencyException) {
                throw $e;
            }

            throw new EntryNotFoundException($id, $e->getCode(), $e);
        }
    }

    /**
     *  {@inheritdoc}
     */
    public function has($id)
    {
        return $this->bound($id);
    }

   /**
     * Determine if the given abstract type has been bound.
     *
     * @param  string  $abstract
     * @return bool
     */
    public function bound($abstract)
    {
        return isset($this->bindings[$abstract]) ||
            isset($this->instances[$abstract]) ||
            $this->isAlias($abstract);
    }
}

We can see that this class implements get() and has() method from ContainerInterface of psr/container package.

But, Why?

The real question here is, why go through all this trouble? Laravel team could have just made these interfaces and they wouldn't have to add another dependency to the framework?

PHP-FIG

PHP-FIG stands for PHP Framework Interop Group.

From FAQ section of website, aims of PHP-FIG:

The idea behind the group is for project representatives to talk about the commonalities between our projects and find ways we can work together. Our main audience is each other, but we’re very aware that the rest of the PHP community is watching. If other folks want to adopt what we’re doing they are welcome to do so, but that is not the aim. Nobody in the group wants to tell you, as a programmer, how to build your application.

To understand it better, consider the following:

Wouldn't it better if all PHP frameworks would follow a common definition of Container class? PHP-FIG has a recommended definition of the Container class and Laravel, Symfony and Yii ( to name a few frameworks ) follow this recommendation.

PSR

PSR stands for PHP Standards Recommendation. That's what PHP-FIG does, just provide Standards Recommendations. Any project ( framework ) is welcome to adopt this standard.

You can find the list of all PHP Standard Recommendations in numerical order here.

The numbers concatenated to PSR like PSR-4 and PSR-11 just represent the order in which these standards were submitted/approved.

Conclusion

In order to comply with PHP-FIG provided PSR-11 Container Interface recommendation, Laravel requires the psr/container package.

Interesting facts about `psr/container` in Laravel context

Pull request for making Laravel's container compliant to PSR-11 Container Interface was opened by Marco Aurélio Deleu on 29 June, 2017 and was approved by Taylor Otwell.
It was added in Laravel v5.5
Laravel Container didn't have get() and has() method before compliance with PSR-11 Container Interface.
make() and bound() methods were available alternatives on Laravel Container.

I hope you enjoyed this post. Next, we will see how Laravel uses psr/simple-cache package. You can follow me on Twitter or join my newsletter for more content.

How closures are serialized in Laravel using `opis/closure` package

Zubair Mohsin — Sat, 03 Apr 2021 11:25:29 +0000

From the About section of opis/closure package on GitHub:

Serialize closures (anonymous functions)

Its pretty clear that it helps us serialize closures ( anonymous functions ) in PHP. Because PHP natively does not support serializing closures. It throws following error when you try to serialize a closure:

Exception with message 'Serialization of 'Closure' is not allowed'

Let's see how and where Laravel framework uses this package and where it needs to serialize and closures.

Code Dive

If we first look at the package itself, we can see that there are bunch of classes. SerializableClosure.php looks like the main class of this package. Also, there's no ServiceProvider for this package which means its not a Laravel package but a PHP package in general.

<?php

namespace Opis\Closure;

use Closure;
use Serializable;
use SplObjectStorage;
use ReflectionObject;

class SerializableClosure implements Serializable
{
    /**
     * Implementation of Serializable::serialize()
     *
     * @return  string  The serialized closure
     */
    public function serialize()
    {
    }

    /**
     * Implementation of Serializable::unserialize()
     *
     * @param   string $data Serialized data
     * @throws SecurityException
     */
    public function unserialize($data)
    {
    }
}

We can see that this class implements PHP's Serializable interface, therefore, it must provide serialize and unserialize methods. I have ripped off implementations of these methods as its out of scope this blog post to see how serialization is done.

Usage in Laravel

One of the major use of this package is Queueing Closures in Laravel. Read more about in docs.

Example of dispatching a closure in Laravel:

$post = App\Post::find(1);

dispatch(function () use ($post) {
    $post->publish();
});

To make this very feature possible, Laravel uses opis/closure package. Let's find out how.

dispatch() helper

    /**
     * Dispatch a job to its appropriate handler.
     *
     * @param  mixed  $job
     * @return \Illuminate\Foundation\Bus\PendingDispatch
     */
    function dispatch($job)
    {
        return $job instanceof Closure
                ? new PendingClosureDispatch(CallQueuedClosure::create($job))
                : new PendingDispatch($job);
    }

Inside dispatch helper, it checks if $job is instance of Closure class (provided by PHP). Other option here would be an instance of a job class that we create normally and they are serialized easily. We are interested in Closure so lets dig further into that.

CallQueuedClosure::create()

<?php

namespace Illuminate\Queue;

use Closure;
use Illuminate\Queue\SerializableClosure;
use Illuminate\Bus\Batchable;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Container\Container;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use ReflectionFunction;

class CallQueuedClosure implements ShouldQueue
{
    use Batchable, Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    /**
     * Create a new job instance.
     *
     * @param  \Illuminate\Queue\SerializableClosure  $closure
     * @return void
     */
    public function __construct(SerializableClosure $closure)
    {
        $this->closure = $closure;
    }

    /**
     * Create a new job instance.
     *
     * @param  \Closure  $job
     * @return self
     */
    public static function create(Closure $job)
    {
        return new self(new SerializableClosure($job));
    }
}

create() method is a static constructor for CallQueuedClosure job class. Our closure which publishes the post is passed to SerializableClosure class constructor and a new instance is returned. Which is then assigned to $this->closure property on CallQueuedClosure job class. At this point, our closure method is already serializable.

Illuminate\Queue\SerializableClosure class extends the SerializableClsoure class from opis/closure package.

<?php

namespace Illuminate\Queue;

use Opis\Closure\SerializableClosure as OpisSerializableClosure;

class SerializableClosure extends OpisSerializableClosure
{
    use SerializesAndRestoresModelIdentifiers;

    /**
     * Transform the use variables before serialization.
     *
     * @param  array  $data The Closure's use variables
     * @return array
     */
    protected function transformUseVariables($data)
    {
        foreach ($data as $key => $value) {
            $data[$key] = $this->getSerializedPropertyValue($value);
        }

        return $data;
    }

    /**
     * Resolve the use variables after unserialization.
     *
     * @param  array  $data The Closure's transformed use variables
     * @return array
     */
    protected function resolveUseVariables($data)
    {
        foreach ($data as $key => $value) {
            $data[$key] = $this->getRestoredPropertyValue($value);
        }

        return $data;
    }
}

Laravel tends to wrap base classes from third-party packages into its own implementation, mostly with same name. That makes it easy for developers to further extend the functionality if they want to.

So far, we have seen that CallQueuedClosure is a job class which needs a SerializableClosure type closure. After that, new PendingClosureDispatch() takes care of dispatching the CallQueuedClosure job.

PendingClosureDispatch

<?php

namespace Illuminate\Foundation\Bus;

use Closure;

class PendingClosureDispatch extends PendingDispatch
{
    /**
     * Add a callback to be executed if the job fails.
     *
     * @param  \Closure  $callback
     * @return $this
     */
    public function catch(Closure $callback)
    {
        $this->job->onFailure($callback);

        return $this;
    }
}

We can see that this class is extending PendingDispatch which is responsible for dispatching normal job classes to the queues.

Here's a link from Mohamed Said's blog f you want to read more on how jobs are dispatched and when serialization occurs.

Conclusion

To execute a task on a given queue, Laravel needs to serialize and un-serialize information on that task. It was okay for job classes as they can be serialized normally. But, in order to push closure based tasks to queue, Laravel team used opis/closure package to serialize and unserialize information on the closures ( anonymous functions ).

Interesting facts about `opis/closure` in Laravel context

Queueing Closures feature was first offered in Laravel v4.0
Link to very first commit on this feature by Taylor Otwell on 19 Apr, 2013 without using any third-party packages.
jeremeamia/SuperClosure package was then used to perform serialization closures. It is now deprecated.
Link to commit where Taylor Otwell required the above mentioned package.
From Laravel v5.1 to v5.6, this feature was discontinued ( I was unable more information on this in docs and on GitHub repository )
In Laravel v5.7, this feature was introduced again. Link to PR by Taylor Otwell. It can be seen that opis/closure package was used this time.

I hope you enjoyed this post. Next, we will see how Laravel uses psr/container package. You can follow me on Twitter or join my newsletter for more content.

How date and time work in Laravel using `nesbot/carbon` package

Zubair Mohsin — Mon, 29 Mar 2021 17:35:03 +0000

From the About section of nesbot/carbon package on GitHub:

A simple PHP API extension for DateTime.

It is an extension of PHP's native DateTime object. It adds lots of cool stuff onto DateTimeand makes it easier to do date and time manipulations.

Let's see how Laravel uses this package to provide even more simpler abstraction such as:

$now = now(); // returns current date and time as Carbon instance

Code Dive

Let's start from definition of now() method. It can be found in Illuminate\Foundation\helpers.php file.

use Illuminate\Support\Facades\Date;

/**
 * Create a new Carbon instance for the current time.
 *
 * @param  \DateTimeZone|string|null  $tz
 * @return \Illuminate\Support\Carbon
 */
function now($tz = null)
{
    return Date::now($tz);
}

We can see that its calling now() method on Date facade.

Date facade

namespace Illuminate\Support\Facades;

use Illuminate\Support\DateFactory;

class Date extends Facade
{
    const DEFAULT_FACADE = DateFactory::class;

    /**
     * Get the registered name of the component.
     *
     * @return string
     *
     * @throws \RuntimeException
     */
    protected static function getFacadeAccessor()
    {
        return 'date';
    }

    /**
     * Resolve the facade root instance from the container.
     *
     * @param  string  $name
     * @return mixed
     */
    protected static function resolveFacadeInstance($name)
    {
        if (! isset(static::$resolvedInstance[$name]) && 
            ! isset(static::$app, static::$app[$name])) {

            $class = static::DEFAULT_FACADE;

            static::swap(new $class);
        }

        return parent::resolveFacadeInstance($name);
    }
}

We have a typical getFacadeAccessor method that returns a string (date). But there are few other things that we haven't seen before. const DEFAULT_FACADE and resolveFacadeInstance method.

Since this is not a module like Log or Scheduling etc, there is no separate ServiceProvider for this to perform service container binding. Therefore inside resolveFacadeInstance method it is swapping the underlying instance behind Date facade to DateFactory class.

We can also confirm this by using app() helper like below:

app('date'); // returns instance of `Illuminate\Support\DateFactory` class

DateFactroy class

Below is a ripped off version of DateFactory class which helps us understand implementation detail behind now() helper method. This class has other stuff too, see full implementation here.

use Illuminate\Support\Carbon;

class DateFactory
{
    /**
     * The default class that will be used for all created dates.
     *
     * @var string
     */
    const DEFAULT_CLASS_NAME = Carbon::class;

    /**
     * The type (class) of dates that should be created.
     *
     * @var string
     */
    protected static $dateClass;

    /**
     * Handle dynamic calls to generate dates.
     *
     * @param  string  $method
     * @param  array  $parameters
     * @return mixed
     *
     * @throws \RuntimeException
     */
    public function __call($method, $parameters)
    {
        $defaultClassName = static::DEFAULT_CLASS_NAME;

        $dateClass = static::$dateClass ?: $defaultClassName;

        // Check if date can be created using public class method...
        if (
            method_exists($dateClass, $method) ||
            $dateClass::hasMacro($method)
        ) {
            return $dateClass::$method(...$parameters);
        }
    }
}

Since now() method does not exist on this class and we are also in object context from Date facade, therefore, __call() magic method will be triggered when we do Date::now().

Inside __call() method we can see that $dateClass is being set to Illuminate\Support\Carbon class. After that it checks if given method ( now() ) exists on that class or this method is a macro. Once decided, it calls that method on Illuminate\Support\Carbon class.

Illuminate\Support\Carbon

<?php

namespace Illuminate\Support;

use Carbon\Carbon as BaseCarbon;
use Carbon\CarbonImmutable as BaseCarbonImmutable;

class Carbon extends BaseCarbon
{
}

Here we can see that this class extends Carbon\Carbon class from nesbot/carbon package. It can be considered as wrapper class around Carbon\Carbon which allows you to do interesting stuff like adding Macros.

Finding now() method

With above findings we can safely assume that now() method should be on Carbon\Carbon class. But exactly where? Let's find out.

use Carbon\Traits\Date;

class Carbon extends DateTime implements CarbonInterface
{
    use Date;

    /**
     * Returns true if the current class/instance is mutable.
     *
     * @return bool
     */
    public static function isMutable()
    {
        return true;
    }
}

This class extends PHP's native DateTime class and also uses a Date trait. Since now() method does not exist on DateTime class, it must be inside the Date trait.

<?php

namespace Carbon\Traits;

use Carbon\Traits\Creator;

trait Date
{
    use Creator;
}

To my surprise, it was further inside a trait called Creator which is being used inside Date trait.

<?php

namespace Carbon\Traits;

trait Creator
{
    /**
     * Create a new Carbon instance.
     *
     * Please see the testing aids section (specifically static::setTestNow())
     * for more on the possibility of this constructor returning a test instance.
     *
     * @param DateTimeInterface|string|null $time
     * @param DateTimeZone|string|null      $tz
     *
     * @throws InvalidFormatException
     */
    public function __construct($time = null, $tz = null)
    {
        try {
            parent::__construct(
                $time ?: 'now',
                static::safeCreateDateTimeZone($tz) ?: null
            );
        } catch (Exception $exception) {
            throw new InvalidFormatException(
                $exception->getMessage(), 0, $exception
            );
        }
    }

    /**
     * Get a Carbon instance for the current date and time.
     *
     * @param DateTimeZone|string|null $tz
     *
     * @return static
     */
    public static function now($tz = null)
    {
        return new static(null, $tz);
    }
}

Here we can finally see the now() method's definition. It is returning a new Carbon\Carbon instance using static constructor approach. I included the __construct method here to highlight the parent::__construct being called on PHP's native DateTime class.

Therefore the About section of this package says extension of DateTime API.

Interesting facts about `nesbot/carbon` package in Laravel

This package was first added in Laravel v4.0 on 19 Apr, 2013 by Kapil Verma
v2 of carbon package was first supported in Laravel v5.8 and then support for v1 of the package was completely dropped in Laravel v6.0
Carbon\Carbon class wrapped by Illuminate\Support\Carbon class in Laravel v5.5 to make it Macroable. Pull Request can be found here.

I hope you enjoyed this post. Next, we will see how Laravel uses opis/closure package. You can follow me on Twitter or join my newsletter for more content.

How Logging works in Laravel using `monolog/monolog` package

Zubair Mohsin — Thu, 25 Mar 2021 06:34:18 +0000

From the GitHub About section of monolog package:

Sends your logs to files, sockets, inboxes, databases and various web services.

Take a look at Handlers directory of this package to see how many services it supports out of the box 🤯

Code Dive

In this blogpost, we'll start from the example so that we can get a taste of diving, instead of directly jumping to ServiceProvider. Let's start with an example usage of logging in Laravel.

use Illuminate\Support\Facades\Log;

Log::info('hello world', ['data' => 'hello world again']);

First of all, let's jump to Log facade where we can see its returning a string log.

I am assuming reader knows how Facade works in Laravel.

Log facade

class Log extends Facade
{
    /**
     * Get the registered name of the component.
     *
     * @return string
     */
    protected static function getFacadeAccessor()
    {
        return 'log';
    }
}

We know that this string log has been bound already to a concrete implementation inside service container using a dedicated ServiceProvider. By following the convention we can safely assume that it must be LogServiceProvider.

Let's take another approach this time and ask the container to tell us the concrete class behind log string.

How do we do it? Pretty easy, using the app() helper.

app('log');

If we dd() the result, we get:

Illuminate\Log\LogManager {#178 ▼
#app: Illuminate\Foundation\Application {#1 ▶}
#channels: array:2 [▶]
#customCreators: array:1 [▶]
#dateFormat: "Y-m-d H:i:s"
#levels: array:8 [▶] }

There we have it, class behind log string. To verify that we got the correct class, let's take a look at LogServiceProvider too.

<?php

namespace Illuminate\Log;

use Illuminate\Support\ServiceProvider;

class LogServiceProvider extends ServiceProvider
{
    /**
     * Register the service provider.
     *
     * @return void
     */
    public function register()
    {
        $this->app->singleton('log', function ($app) {
            return new LogManager($app);
        });
    }
}

Log::info()

Now that we know Log facade uses LogManager class under-the-hood, we can safely assume that info() must exist on this class.

/**
 * Interesting events.
 *
 * Example: User logs in, SQL logs.
 *
 * @param  string  $message
 * @param  array  $context
 *
 * @return void
 */
public function info($message, array $context = [])
{
    $this->driver()->info($message, $context);
}

info() method gets the driver() and calls info() method on that driver. Let's dig into driver() method and all its related methods.

        /**
     * Get a log driver instance.
     *
     * @param  string|null  $driver
     * @return \Psr\Log\LoggerInterface
     */
    public function driver($driver = null)
    {
        return $this->get($driver ?? $this->getDefaultDriver());
    }

        /**
     * Get the default log driver name.
     *
     * @return string
     */
    public function getDefaultDriver()
    {
        return $this->app['config']['logging.default'];
    }

        /**
     * Attempt to get the log from the local cache.
     *
     * @param  string  $name
     * @return \Psr\Log\LoggerInterface
     */
    protected function get($name)
    {
        try {
            return $this->channels[$name] ?? with(
                $this->resolve($name),
                function ($logger) use ($name) {
                    return $this->channels[$name] = $this->tap(
                        $name,
                        new Logger($logger, $this->app['events'])
                    );
                }
            );
        } catch (Throwable $e) {
            return tap(
                $this->createEmergencyLogger(),
                function ($logger) use ($e) {
                    $logger->emergency(
                        'Using emergency logger.',
                        ['exception' => $e,]
                    );
                }
            );
        }
    }

The driver() method is getting the default driver from config/logging.php file. Laravel supports multi-channel logging, and each channel has its own driver. For the sake of simplicity, we'll consider single as our default channel with below config:

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

Inside the get() method above, it's resolving the given channel driver by name and applying taps on it. (Read more about taps in the docs). If it can't resolve the channel driver, it creates an emergency logger which writes to laravel.log file. How can this happen? If you misspelled your channel name or driver name.

resolve() method

/**
 * Resolve the given log instance by name.
 *
 * @param  string  $name
 * @return \Psr\Log\LoggerInterface
 *
 * @throws \InvalidArgumentException
 */
protected function resolve($name)
{
    $config = $this->configurationFor($name);

    if (is_null($config)) {
        throw new InvalidArgumentException("Log [{$name}] is not defined.");
    }

    $driverMethod = 'create' . ucfirst($config['driver']) . 'Driver';

    if (method_exists($this, $driverMethod)) {
        return $this->{$driverMethod}($config);
    }

    throw new InvalidArgumentException(
        "Driver [{$config['driver']}] is not supported."
    );
}

It's getting the configuration for given driver and then creating a method name dynamically. In our case $name = 'single' so the $driverMethod = 'createSingleDriver' . After that, its calling that method with its configuration.

use Monolog\Logger as Monolog;
use Monolog\Handler\StreamHandler;

/**
 * Create an instance of the single file log driver.
 *
 * @param  array  $config
 * @return \Psr\Log\LoggerInterface
 */
protected function createSingleDriver(array $config)
{
    return new Monolog($this->parseChannel($config), [
        $this->prepareHandler(
            new StreamHandler(
                $config['path'],
                $this->level($config),
                $config['bubble'] ?? true,
                $config['permission'] ?? null,
                $config['locking'] ?? false
            ),
            $config
        ),
    ]);
}

Here we can see that a new instance of Monolog\Logger is returned with channel name and a handler which also provided by monolog package.

For the sake of understanding, in the end input() method is called on Monolog\Logger class.

/**
 * Adds a log record at the INFO level.
 *
 * This method allows for compatibility with common interfaces.
 *
 * @param string  $message The log message
 * @param mixed[] $context The log context
 */
public function info($message, array $context = []): void
{
    $this->addRecord(static::INFO, (string) $message, $context);
}

addRecord method is responsible for writing log record in the file. How it writes to the file is out of scope of this blogpost.

Interesting facts about Monolog in Laravel context

This package has been part of Laravel since the beginning ( maybe ).
Link to very first commit of laravel/framework on GitHub made by Taylor Otwell on 11 Jan, 2013 confirms the above statement.
On GitHub, we only have access to version 4.0 of laravel/framework, so, not sure if this package was part of Laravel in versions earlier than 4.0.

I hope you enjoyed this post. Next, we will see how Laravel uses monolog/monolog package. You can follow me on Twitter or join my newsletter for more content.

How Laravel uses `league/flysystem` package to create robust Filesystem

Zubair Mohsin — Sat, 20 Mar 2021 13:32:45 +0000

From the About section on GitHub of league/flysystem package:

Flysystem is a file storage library for PHP. It provides one interface to interact with many types of filesystems.

Thanks to this package, Laravel supports working with several filesystems, for example, local disk, FTP, SFTP and Amazon S3. We just have to change some configurations in config/filesystems.php file. We can even create our own filesystem driver with minimal effort.

Without further ado, let's figure how this package is used in Laravel.

Code Dive

In this blogpost, I am going to take a different approach of code-dive as compared to previous blogposts. I will start from the service provider of the filesystem in Laravel to see what happens when framework is booted.

laravel/framework repository has separate directories for each major module. We can easily find Filesystem module under vendor/laravel/framework/src/Illuminate/Filesystem

Let's take a look at FilesystemServiceProvider class.

<?php

namespace Illuminate\Filesystem;

use Illuminate\Support\ServiceProvider;

class FilesystemServiceProvider extends ServiceProvider
{
    /**
     * Register the service provider.
     *
     * @return void
     */
    public function register()
    {
        $this->registerNativeFilesystem();

        $this->registerFlysystem();
    }

    /**
     * Register the native filesystem implementation.
     *
     * @return void
     */
    protected function registerNativeFilesystem()
    {
        $this->app->singleton('files', function () {
            return new Filesystem;
        });
    }

    /**
     * Register the driver based filesystem.
     *
     * @return void
     */
    protected function registerFlysystem()
    {
        $this->registerManager();

        $this->app->singleton('filesystem.disk', function ($app) {
            return $app['filesystem']->disk($this->getDefaultDriver());
        });

        $this->app->singleton('filesystem.cloud', function ($app) {
            return $app['filesystem']->disk($this->getCloudDriver());
        });
    }

    /**
     * Register the filesystem manager.
     *
     * @return void
     */
    protected function registerManager()
    {
        $this->app->singleton('filesystem', function ($app) {
            return new FilesystemManager($app);
        });
    }

    /**
     * Get the default file driver.
     *
     * @return string
     */
    protected function getDefaultDriver()
    {
        return $this->app['config']['filesystems.default'];
    }

    /**
     * Get the default cloud based file driver.
     *
     * @return string
     */
    protected function getCloudDriver()
    {
        return $this->app['config']['filesystems.cloud'];
    }
}

Laravel first registers Native Filesystem and then explicitly register Flysystem. We are interested in flysystem so we will dig into that.

Native Filesystem uses native PHP file methods under-the-hood and are available via File facade, e.g. File::put()

Inside registerManager() method, we can see that a singleton is being bind to the container for filesystem string and it returns an instance of FilesystemManager class when resolved. After this, it's also binding the default (local) filesystem driver to the container.

The FilesystemManager

FilesystemManager class has methods that deal with instantiation of disk/driver class. Below I have only given the declarations of related methods. We'll look into their implementations later. We can see classes ( adapters ) from league/flysystem package here.

<?php

namespace Illuminate\Filesystem;

use League\Flysystem\Adapter\Ftp as FtpAdapter;
use League\Flysystem\Adapter\Local as LocalAdapter;
use League\Flysystem\AdapterInterface;
use League\Flysystem\AwsS3v3\AwsS3Adapter as S3Adapter;
use League\Flysystem\Cached\CachedAdapter;
use League\Flysystem\Cached\Storage\Memory as MemoryStore;
use League\Flysystem\Filesystem as Flysystem;
use League\Flysystem\FilesystemInterface;
use League\Flysystem\Sftp\SftpAdapter;

/**
 * @mixin \Illuminate\Contracts\Filesystem\Filesystem
 */
class FilesystemManager implements FactoryContract
{
    /**
     * Get a filesystem instance.
     *
     * @param  string|null  $name
     * @return \Illuminate\Contracts\Filesystem\Filesystem
     */
    public function disk($name = null);

        /**
     * Attempt to get the disk from the local cache.
     *
     * @param  string  $name
     * @return \Illuminate\Contracts\Filesystem\Filesystem
     */
    protected function get($name);

        /**
     * Resolve the given disk.
     *
     * @param  string  $name
     * @return \Illuminate\Contracts\Filesystem\Filesystem
     *
     * @throws \InvalidArgumentException
     */
    protected function resolve($name);

        /**
     * Create an instance of the local driver.
     *
     * @param  array  $config
     * @return \Illuminate\Contracts\Filesystem\Filesystem
     */
    public function createLocalDriver(array $config);

        /**
     * Adapt the filesystem implementation.
     *
     * @param  \League\Flysystem\FilesystemInterface  $filesystem
     * @return \Illuminate\Contracts\Filesystem\Filesystem
     */
    protected function adapt(FilesystemInterface $filesystem);
}

But, how it all works?

Laravel makes it extremely simple to interact with filesystem. In below snippet, we are creating a file named example.txt with Contents string and putting it on local disk.

use Illuminate\Support\Facades\Storage;

Storage::disk('local')->put('example.txt', 'Contents');

Let's try to understand the above code one part at a time.

Storage Facade

I am assuming reader knows how Laravel Facade pattern works as that is out of scope of this blogpost.

<?php

namespace Illuminate\Support\Facades;

use Illuminate\Filesystem\Filesystem;

class Storage extends Facade
{
        /**
     * Get the registered name of the component.
     *
     * @return string
     */
    protected static function getFacadeAccessor()
    {
        return 'filesystem';
    }
}

We can see inside getFacadeAccessor() it returns filesystem string. Which is exactly the same as we saw earlier inside FilesystemServiceProvider inside registerManager() method.

We can safely conclude that, by using Storage facade, we are basically interacting with FilesystemManager class.

Storage::disk('local')

disk() method on FilesystemManager class receives the disk name, which in this case is local ( it is also default ) and try to resolve an instance of that disk based Filesystem class.

        /**
     * Get a filesystem instance.
     *
     * @param  string|null  $name
     * @return \Illuminate\Contracts\Filesystem\Filesystem
     */
    public function disk($name = null)
    {
        $name = $name ?: $this->getDefaultDriver();

        return $this->disks[$name] = $this->get($name);
    }

        /**
     * Attempt to get the disk from the local cache.
     *
     * @param  string  $name
     * @return \Illuminate\Contracts\Filesystem\Filesystem
     */
    protected function get($name)
    {
        return $this->disks[$name] ?? $this->resolve($name);
    }

    /**
     * Resolve the given disk.
     *
     * @param  string  $name
     * @return \Illuminate\Contracts\Filesystem\Filesystem
     *
     * @throws \InvalidArgumentException
     */
    protected function resolve($name)
    {
        $config = $this->getConfig($name);

        if (empty($config['driver'])) {
            throw new InvalidArgumentException(
                "Disk [{$name}] does not have a configured driver."
            );
        }

        $name = $config['driver'];

        $driverMethod = 'create' . ucfirst($name) . 'Driver';

        if (!method_exists($this, $driverMethod)) {
            throw new InvalidArgumentException(
                "Driver [{$name}] is not supported."
            );
        }

        return $this->{$driverMethod}($config);
    }

If we look at resolve() method, we can see that its loading the config for the given disk and creating a method name dynamically.

$driverMethod = 'create' . ucfirst($name) . 'Driver';

In our case, it will result in createLocalDriver(). We can find this method inside FilesystemManager class along with others like createS3Driver(), createSftpDriver() .

use League\Flysystem\Filesystem as Flysystem;
use League\Flysystem\Adapter\Local as LocalAdapter;

/**
 * Create an instance of the local driver.
 *
 * @param  array  $config
 * @return \Illuminate\Contracts\Filesystem\Filesystem
 */
public function createLocalDriver(array $config)
{
    $permissions = $config['permissions'] ?? [];

    $links = ($config['links'] ?? null) === 'skip'
        ? LocalAdapter::SKIP_LINKS
        : LocalAdapter::DISALLOW_LINKS;

    return $this->adapt($this->createFlysystem(new LocalAdapter(
        $config['root'],
        $config['lock'] ?? LOCK_EX,
        $links,
        $permissions
    ), $config));
}

/**
 * Create a Flysystem instance with the given adapter.
 *
 * @param  \League\Flysystem\AdapterInterface  $adapter
 * @param  array  $config
 * @return \League\Flysystem\FilesystemInterface
 */
protected function createFlysystem(AdapterInterface $adapter, array $config)
{
    $config = Arr::only($config, ['visibility', 'disable_asserts', 'url']);

    return new Flysystem($adapter, count($config) > 0 ? $config : null);
}

/**
 * Adapt the filesystem implementation.
 *
 * @param  \League\Flysystem\FilesystemInterface  $filesystem
 * @return \Illuminate\Contracts\Filesystem\Filesystem
 */
protected function adapt(FilesystemInterface $filesystem)
{
    return new FilesystemAdapter($filesystem);
}

Inside createLocalDriver() method it is creating a new instance of Localadapter from flysystem package and then pass that adapter to base class Filesystem (aliased as Flysystem) of flysystem package.

In the end, Laravel wraps the base class instance in its own implementation inside adapt() method. FilesystemAdapter class can be found in the same directory as FilesystemManager class.

Storage::disk('local')→put()

By the end of disk() method execution, we have FilesystemAdapter instance. So we can safely assume that put() method must be inside FilesystemAdapter class.

<?php

namespace Illuminate\Filesystem;

class FilesystemAdapter
{
        /**
     * Write the contents of a file.
     *
     * @param  string  $path
     * @param  string|resource  $contents
     * @param  mixed  $options
     * @return bool
     */
    public function put($path, $contents, $options = [])
    {
        $options = is_string($options)
                     ? ['visibility' => $options]
                     : (array) $options;

        if ($contents instanceof File ||
            $contents instanceof UploadedFile) {
            return $this->putFile($path, $contents, $options);
        }

        if ($contents instanceof StreamInterface) {
            return $this->driver->putStream(
                            $path, $contents->detach(), $options
                        );
        }

        return is_resource($contents)
                ? $this->driver->putStream($path, $contents, $options)
                : $this->driver->put($path, $contents, $options);
    }
}

Other commonly used methods like Storage::get(), Storage::delete() , Storage::download() can also be found in FilesystemAdapter() class.

Link to source code of the class.

This is how Laravel leverages flysystem package to provide fluent and easy-to-use Filesystem API.

Interesting facts about Flysystem in Laravel context

league/flysystem package was first added to Laravel in v5.0
Taylor Otwell made the commit "Working on filesystem" on 24 Aug, 2014
Initial version of this packaged used in Laravel was v0.5 . It was upgraded to v1.0 in Dec, 2014.
Initially, Rackspace was also included along with AWS S3 as cloud filesystems.
league/flysystem package has major changes in v2 . Laravel v9 is expected to contain v2 of this package.
Pull request by Dries Vints already merged into master branch, which upgrades this package to v2 in Laravel v9.

I hope you enjoyed this post. Next, we will see how Laravel uses monolog/monolog package. You can follow me on Twitter or join my newsletter for more content.

Laracon Online 2021 talks Twitter thread links

Zubair Mohsin — Thu, 18 Mar 2021 06:55:54 +0000

I had the chance to live-tweet about all Laracon Online 2021 talks. Now these can be harder to find in the order.
So here are links to initial tweets of each talk.

Mohamed Said

// Detect dark theme var iframe = document.getElementById('tweet-1372185448173465600-349'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1372185448173465600&theme=dark" }

Taylor Otwell

// Detect dark theme var iframe = document.getElementById('tweet-1372238371314139136-225'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1372238371314139136&theme=dark" }

Christoph Rumpel

// Detect dark theme var iframe = document.getElementById('tweet-1372200983703478272-378'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1372200983703478272&theme=dark" }

Bobby Bouwmann

// Detect dark theme var iframe = document.getElementById('tweet-1372221634808004608-792'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1372221634808004608&theme=dark" }

Marcel Pociot

// Detect dark theme var iframe = document.getElementById('tweet-1372257042216448002-90'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1372257042216448002&theme=dark" }

MIGUEL Piedrafita

// Detect dark theme var iframe = document.getElementById('tweet-1372269070893060097-364'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1372269070893060097&theme=dark" }

Caleb Porzio

// Detect dark theme var iframe = document.getElementById('tweet-1372285811807371271-317'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1372285811807371271&theme=dark" }

Nuno Maduro

// Detect dark theme var iframe = document.getElementById('tweet-1372300267954319367-71'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1372300267954319367&theme=dark" }

I hope you enjoyed this post and these Twitter threads. You can follow me on Twitter or join my newsletter to keep getting such updates.

How markdown emails work in Laravel using `league/commonmark` package

Zubair Mohsin — Wed, 17 Mar 2021 10:31:52 +0000

From the About section of league/commonmark package:

Highly-extensible PHP Markdown parser which fully supports the CommonMark and GFM specs.

This package helps us parse markdown in PHP. If you are not familiar with markdown, GitHub has super helpful guide about it here.

Mail in Laravel

Laravel provides simple and easy ways to send emails. There are two options in Laravel to send emails:

Mailables
Notifications

I created a poll on Twitter to see how Developers usually send emails in their Laravel apps. Based on the results, seems like Mailable is the go-to choice. We'll also use Mailable to explore further.

(Interesting replies on this tweet, give them a read)

// Detect dark theme var iframe = document.getElementById('tweet-1371510380149805056-811'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1371510380149805056&theme=dark" }

Markdown Mailables

Let's generate a markdown mailable using Artisan.

> php artisan make:mail NewsletterSubscribed --markdown=emails.newsletter.subscribed

We get two files as a result of this command.

App\Mail\NewsletterSubscribed class
resources/views/emails/newsletter/subscribed.blade.php file

Let's take a look at view file:

@component('mail::message')
# Hello

You have subscribed to our newsletter.

@component('mail::button', ['url' => ''])
Button Text
@endcomponent

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

We can see that there's a combination of Blade Components and Markdown in this file. These components and others are made available by Laravel, read more about components here. When we send out this mailable, league/commonmark package comes into play and parse this markdown to HTML.

What happens when you Mail::to()→send() ?

Mail::to($request->user())->send(new NewsletterSubscribed());

We are specifying the recipient in to() method and the mailable class in send() method.

Code Dive

Let's dive into send() method. It leads us to Illuminate\Mail\PendingMail class.

<?php

namespace Illuminate\Mail

use Illuminate\Contracts\Mail\Mailable as MailableContract;
use Illuminate\Contracts\Mail\Mailer as MailerContract;

class PendingMail
{
        /**
     * The mailer instance.
     *
     * @var \Illuminate\Contracts\Mail\Mailer
     */
    protected $mailer;

        /**
     * Send a new mailable message instance.
     *
     * @param  \Illuminate\Contracts\Mail\Mailable  $mailable
     * @return mixed
     */
    public function send(MailableContract $mailable)
    {
        return $this->mailer->send($this->fill($mailable));
    }

        /**
     * Populate the mailable with the addresses.
     *
     * @param  \Illuminate\Contracts\Mail\Mailable  $mailable
     * @return \Illuminate\Mail\Mailable
     */
    protected function fill(MailableContract $mailable)
    {
        return tap($mailable->to($this->to)
            ->cc($this->cc)
            ->bcc($this->bcc), function (MailableContract $mailable) {
            if ($this->locale) {
                $mailable->locale($this->locale);
            }
        });
    }
}

Mailable class is being filled with addresses and then its calling send method on the given Mailer instance. As we can see, $mailer is an instance of class which implements the Mailer contract. Where do we find its concrete class implementation?

Finding the Mailer

When request comes in and Laravel registers the ServiceProviders, part of these providers is Illumiate\Mail\MailServiceProvider. Let's take a look at its register method.

    use Illuminate\Mail\MailManager;

        /**
     * Register the service provider.
     *
     * @return void
     */
    public function register()
    {
        $this->registerIlluminateMailer();
        $this->registerMarkdownRenderer();
    }

    /**
     * Register the Illuminate mailer instance.
     *
     * @return void
     */
    protected function registerIlluminateMailer()
    {
        $this->app->singleton('mail.manager', function ($app) {
            return new MailManager($app);
        });

        $this->app->bind('mailer', function ($app) {
            return $app->make('mail.manager')->mailer();
        });
    }

    /**
     * Register the Markdown renderer instance.
     *
     * @return void
     */
    protected function registerMarkdownRenderer()
    {
        $this->app->singleton(Markdown::class, function ($app) {
            $config = $app->make('config');

            return new Markdown($app->make('view'), [
                'theme' => $config->get('mail.markdown.theme', 'default'),
                'paths' => $config->get('mail.markdown.paths', []),
            ]);
        });
    }

It is binding a singleton of MailManager class and then bind Mailer by calling mailer() method on mail.manager singleton above.

We can already see a Markdown class being registered. We will eventually reach to this class.
Read more about singleton() and bind() binding methods in the documentation

Let's dig into mailer() method of MailManager class.

<?php

namespace Illuminate\Mail;

class MailManager
{
        /* Get a mailer instance by name.
     *
     * @param  string|null  $name
     * @return \Illuminate\Mail\Mailer
     */
    public function mailer($name = null)
    {
        $name = $name ?: $this->getDefaultDriver();

        return $this->mailers[$name] = $this->get($name);
    }

        /**
     * Get the default mail driver name.
     *
     * @return string
     */
    public function getDefaultDriver()
    {
        return $this->app['config']['mail.driver'] ??
            $this->app['config']['mail.default'];
    }

        /**
     * Attempt to get the mailer from the local cache.
     *
     * @param  string  $name
     * @return \Illuminate\Mail\Mailer
     */
    protected function get($name)
    {
        return $this->mailers[$name] ?? $this->resolve($name);
    }

    /**
     * Resolve the given mailer.
     *
     * @param  string  $name
     * @return \Illuminate\Mail\Mailer
     *
     * @throws \InvalidArgumentException
     */
    protected function resolve($name)
    {
        //ripped off version of resolve method

        $config = $this->getConfig($name);
            $mailer = new Mailer(
            $name,
            $this->app['view'],
            $this->createSwiftMailer($config),
            $this->app['events']
        );

        return $mailer;

    }
}

Above code can be roughly translated to:

Get the default mail driver / default mailer (which is smtp) then call get() method on it. get() method checks if given mailer has already been resolved ( local cache ), otherwise resolve the concrete class for the given mailer.

We found the Mailer concrete class. Yay!

It's located at Illuminate\Mail\Mailer. It was kind of obvious, but finding it through code-dive was fun. Alright, moving on...

The Mailer

We are interested in send() method on the Mailer class. Let's take a look:

<?php

namespace Illuminate\Mail;

use Illuminate\Contracts\Mail\Mailable as MailableContract;
use Illuminate\Contracts\Mail\Mailer as MailerContract;

class Mailer implements MailerContract
{

    /**
     * The name that is configured for the mailer.
     *
     * @var string
     */
    protected $name;

    /**
     * Send a new message using a view.
     *
     * @param  \Illuminate\Contracts\Mail\Mailable|string|array  $view
     * @param  array  $data
     * @param  \Closure|string|null  $callback
     * @return void
     */
    public function send($view, array $data = [], $callback = null)
    {
        if ($view instanceof MailableContract) {
            return $this->sendMailable($view);
        }

            //.. code ripped off
        }

    /**
     * Send the given mailable.
     *
     * @param  \Illuminate\Contracts\Mail\Mailable  $mailable
     * @return mixed
     */
    protected function sendMailable(MailableContract $mailable)
    {
        return $mailable instanceof ShouldQueue
            ? $mailable->mailer($this->name)->queue($this->queue)
            : $mailable->mailer($this->name)->send($this);
    }
}

In the send() method it checks if $view is an instance of Mailable , in our case this is true. We are indeed working with Mailable and we passed a mailable from PendingMail class.

Then it sets Mailer on Mailable class itself and then calls send method on the Mailable.

The Mailable

If we were to find concrete class that implements Mailable class, this post will become huge.

Therefore, we are just going to assume that Illuminate\Mail\Mailable class is what we need as our NewsletterSubscribed class extends it and it also implements Illuminate\Contracts\Mail\Mailable interface.

<?php

namespace Illuminate\Mail;

use Illuminate\Container\Container;
use Illuminate\Contracts\Mail\Mailable as MailableContract;

class Mailable implements MailableContract, Renderable
{
    /**
     * Set the name of the mailer that should send the message.
     *
     * @param  string  $mailer
     * @return $this
     */
    public function mailer($mailer)
    {
        $this->mailer = $mailer;

        return $this;
    }

    /**
     * Send the message using the given mailer.
     *
     * @param  \Illuminate\Contracts\Mail\Factory|\Illuminate\Contracts\Mail\Mailer  $mailer
     * @return void
     */
    public function send($mailer)
    {
        return $this->withLocale($this->locale, function () use ($mailer) {
            Container::getInstance()->call([$this, 'build']);

            $mailer = $mailer instanceof MailFactory
                ? $mailer->mailer($this->mailer)
                : $mailer;

            return $mailer->send(
                **$this->buildView(),
                $this->buildViewData()**,
                function ($message) {
                    $this->buildFrom($message)
                        ->buildRecipients($message)
                        ->buildSubject($message)
                        ->runCallbacks($message)
                        ->buildAttachments($message);
            });
        });
    }
}

In context of our topic, buildView() method is of our interest. Below is its implementation and related methods.

/**
     * Build the view for the message.
     *
     * @return array|string
     *
     * @throws \ReflectionException
     */
    protected function buildView()
    {
        //code ripped off

        if (isset($this->markdown)) {
            return $this->buildMarkdownView();
        }
    }

    /**
     * Build the Markdown view for the message.
     *
     * @return array
     *
     * @throws \ReflectionException
     */
    protected function buildMarkdownView()
    {
        $markdown = Container::getInstance()->make(Markdown::class);

        if (isset($this->theme)) {
            $markdown->theme($this->theme);
        }

        $data = $this->buildViewData();

        return [
            'html' => $markdown->render($this->markdown, $data),
            'text' => $this->buildMarkdownText($markdown, $data),
        ];
    }

buildMarkdownView() method is where it is initialising Markdown class from container and rendering the markdown view of our NewlsetterSubscribed mail.

The Markdown

In the Markdown class, there are two important methods. render and parse.

<?php

namespace Illuminate\Mail;

use Illuminate\Contracts\View\Factory as ViewFactory;
use Illuminate\Support\HtmlString;
use Illuminate\Support\Str;
use League\CommonMark\CommonMarkConverter;
use League\CommonMark\Environment;
use League\CommonMark\Extension\Table\TableExtension;
use TijsVerkoyen\CssToInlineStyles\CssToInlineStyles;

class Markdown
{
    /**
     * The view factory implementation.
     *
     * @var \Illuminate\Contracts\View\Factory
     */
    protected $view;

    protected $theme = 'default';

    public function __construct(ViewFactory $view, array $options = [])
    {
        $this->view = $view;
        $this->theme = $options['theme'] ?? 'default';
        $this->loadComponentsFrom($options['paths'] ?? []);
    }

    /**
     * Render the Markdown template into HTML.
     *
     * @param  string  $view
     * @param  array  $data
     * @param  \TijsVerkoyen\CssToInlineStyles\CssToInlineStyles|null  $inliner
     * @return \Illuminate\Support\HtmlString
     */
    public function render($view, array $data = [], $inliner = null)
    {
        $this->view->flushFinderCache();

        $contents = $this->view->replaceNamespace(
            'mail',
            $this->htmlComponentPaths()
        )->make($view, $data)->render();

        if ($this->view->exists($this->theme)) {
            $theme = $this->theme;
        } else {
            $theme = Str::contains($this->theme, '::')
                ? $this->theme
                : 'mail::themes.' . $this->theme;
        }

        return new HtmlString(($inliner ?: new CssToInlineStyles)->convert(
            $contents,
            $this->view->make($theme, $data)->render()
        ));
    }

    /**
     * Parse the given Markdown text into HTML.
     *
     * @param  string  $text
     * @return \Illuminate\Support\HtmlString
     */
    public static function parse($text)
    {
        $environment = Environment::createCommonMarkEnvironment();

        $environment->addExtension(new TableExtension);

        $converter = new CommonMarkConverter([
            'allow_unsafe_links' => false,
        ], $environment);

        return new HtmlString($converter->convertToHtml($text));
    }
}

And we can finally see inside the parse() method that it utilizes classes from league/commonmark package like CommonMarkConverter and TableExtension etc.

But we never called parse() method from anywhere? And we can see nothing inside the render() method related to markdown either?

Well, parse() method is called from within the email views. Our subscribed.blade.php view uses @component('mail::message') which in-turn uses @component('mail::layout') , and if we take a look at layout component at Mail\resources\views\html\layout.blade.php , we see an HTML template with table layout and some styling.

There we see the following code in which parse() method is being called.

<td class="content-cell">
{{ Illuminate\Mail\Markdown::parse($slot) }}

{{ $subcopy ?? '' }}
</td>

When the subscribed view is rendered, parse gets called and our markdown content is parsed using league/commonmark package.

Interesting facts about Markdown in Laravel

Laravel started supporting Markdown syntax in emails ****in **version 5.4**
The first package used to parse markdown was erusev/parsedown
In Laravel v6.0, they switched from erusev/parsedown to league/commonmark for safety features.
Taylor Otwell removed erusev/parsedown from composer.json and added league/commonmark on 30 Dec, 2019.
Commit on GitHub can be found on this link

I hope you enjoyed this post. Next, we will see how Laravel uses league/flysystem package. You can follow me on Twitter or join my newsletter to keep yourself updated.

How email validation works in Laravel using `egulias/email-validation` package'

Zubair Mohsin — Sun, 14 Mar 2021 18:57:28 +0000

It’s obvious from the name of this package that it helps with email address validation. It helps us make sure if the given email address is valid (according to some standards) or not.

Laravel has a powerful Validation engine which helps you validate your data on incoming requests. It also provides several ways to perform validation:

By calling validate method on Request object inside controller method
By calling $this->validate() method inside controller method
By using a separate FormRequest class
$this->valdiate() method is made available using ValidatesRequests trait on controller.

We'll follow the FormRequest based validation as it is becoming a standard in Laravel community.

Code Dive

Let's say we are validating an email address field like below inside a FormRequest:

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class UsersRequest extends FormRequest
{
    public function rules()
    {
        return [
            'email_address' => ['email']
        ];
    }
}

And then use UsersRequest inside a controller like below:

class UsersController
{
    public function store(UsersRequest $request)
    {
        User::create($request->validated());
    }
}

What happens when we send the request?

When we send the request to above controller method, a service provider named FormRequestServiceProvider is booted ( along with other service providers ).

Let's take a look at its boot method:

namespace Illuminate\Foundation\Providers;

use Illuminate\Contracts\Validation\ValidatesWhenResolved;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Routing\Redirector;
use Illuminate\Support\ServiceProvider;

class FormRequestServiceProvider extends ServiceProvider
{
    public function boot()
    {
        *$this->app->afterResolving(ValidatesWhenResolved::class,
                function ($resolved) {
            $resolved->validateResolved();
        });*

        $this->app->resolving(FormRequest::class, function ($request, $app) {
            $request = FormRequest::createFrom($app['request'], $request);

            $request->setContainer($app)
                ->setRedirector($app->make(Redirector::class));
        });
    }
}

If we interpret the highlighted code block, it says:

After resolving the class which implements ValidatesWhenResolved interface, call the validateResolved method on its instance.

Our UsersRequest class extends the FormRequest class which implements ValidatesWhenResolved interface. Implementation for validateResolved method has been added to a Trait which can be found at Illuminate\Foundation\Http\ValidatesWhenResolvedTrait which is given below:

public function validateResolved()
{
    $this->prepareForValidation();

    if (!$this->passesAuthorization()) {
        $this->failedAuthorization();
    }

    **$instance = $this->getValidatorInstance();**

    **if ($instance->fails()) {
        $this->failedValidation($instance);
    }**

    $this->passedValidation();
}

getValidatorInstance() method has been overridden inside FormRequest class like below:

/**
 * Get the validator instance for the request.
 *
 * @return \Illuminate\Contracts\Validation\Validator
*/
protected function getValidatorInstance()
{
    if ($this->validator) {
        return $this->validator;
    }

    $factory = $this->container->make(ValidationFactory::class);

    if (method_exists($this, 'validator')) {
        $validator = $this->container->call(
            [$this, 'validator'], compact('factory')
        );
    } else {
        $validator = $this->createDefaultValidator($factory);
    }

    if (method_exists($this, 'withValidator')) {
        $this->withValidator($validator);
    }

    $this->setValidator($validator);

    return $this->validator;
}

/**
 * Create the default validator instance.
 *
 * @param  \Illuminate\Contracts\Validation\Factory  $factory
 * @return \Illuminate\Contracts\Validation\Validator
*/
protected function createDefaultValidator(ValidationFactory $factory)
{
    return $factory->make(
        $this->validationData(),
        $this->container->call([$this, 'rules']),
        $this->messages(),
        $this->attributes()
    )->stopOnFirstFailure($this->stopOnFirstFailure);
}

For the ease of understanding, above code can be translated to:

If developer has provided their own implementation of validator using validator() method on UsersRequest class, use that Validator. Otherwise, createDefaultValidator and provide data to be validated, rules and messages etc. to Validator instance.

Now that a Validator instance has been created, next in validateResolved() method is calling fails() method the given instance.

namespace Illuminate\Validation;

class Validator implements ValidatorContract
{
    public function fails()
    {
        return ! $this->passes();
    }

        //ripped off implementation of passes() method
        public function passes()
    {
        foreach ($this->rules as $attribute => $rules) {
            **foreach ($rules as $rule) {
                $this->validateAttribute($attribute, $rule);
            }**
        }
    }

    //ripped off implementation of validateAttribute() method
    protected function validateAttribute($attribute, $rule)
    {
        $this->currentRule = $rule;

        [$rule, $parameters] = ValidationRuleParser::parse($rule);

        if ($rule == '') {
            return;
        }

        $value = $this->getValue($attribute);

        $validatable = $this->isValidatable($rule, $attribute, $value);

        **$method = "validate{$rule}";**

        if ($validatable &&! **$this->$method($attribute, $value, $parameters, $this)**)
        {
            $this->addFailure($attribute, $rule, $parameters);
        }
    }

}

fails() method calls for passes() method which in turn calls validateAttribute() method. This is where our data attributes are checked against the validation rules we provided.

validate{$rule} string is creating a method name for the given rule. Since we are exploring email validation rule, it will become validateEmail() . Next, this method is being called as part of if condition.

Since implementations of all available validation methods can be found in Illuminate\Validation\Concerns\ValidatesAttributes trait. Hence the validateEmail() method below:

namespace Illuminate\Validation\Concerns;

use Egulias\EmailValidator\EmailValidator;
use Egulias\EmailValidator\Validation\DNSCheckValidation;
use Egulias\EmailValidator\Validation\MultipleValidationWithAnd;
use Egulias\EmailValidator\Validation\NoRFCWarningsValidation;
use Egulias\EmailValidator\Validation\RFCValidation;
use Egulias\EmailValidator\Validation\SpoofCheckValidation;

trait ValidatesAttributes
{

        /**
     * Validate that an attribute is a valid e-mail address.
     *
     * @param  string  $attribute
     * @param  mixed  $value
     * @param  array  $parameters
     * @return bool
     */
    public function validateEmail($attribute, $value, $parameters)
    {
        $validations = collect($parameters)
            ->unique()
            ->map(function ($validation) {
                if ($validation === 'rfc') {
                    return new RFCValidation();
                } elseif ($validation === 'strict') {
                    return new NoRFCWarningsValidation();
                } elseif ($validation === 'dns') {
                    return new DNSCheckValidation();
                } elseif ($validation === 'spoof') {
                    return new SpoofCheckValidation();
                } elseif ($validation === 'filter') {
                    return new FilterEmailValidation();
                } elseif ($validation === 'filter_unicode') {
                    return FilterEmailValidation::unicode();
                } elseif (is_string($validation) && class_exists($validation)) {
                    return $this->container->make($validation);
                }
            })
            ->values()
            ->all() ?: [new RFCValidation()];

        return (new EmailValidator)->isValid($value, new MultipleValidationWithAnd($validations));
    }}

This is how Laravel validates an email address by leveraging various email validation classes from egulias/email-validation package.

Interesting facts about this package in Laravel context

This package was first used by Laravel in v5.8
Pull Request to add this functionality was opened by Leo Sjöberg and merged by Taylor Otwell in Nov, 2018
PR can be found here
Before the addition of this package, Laravel used filter_var function of PHP to validate email address.

I hope you enjoyed this post. Next, we will see how Laravel uses league/commonmark package. You can follow me on Twitter or join my newsletter to keep yourself updated.

How Laravel uses dragonmantank/cron-expression package in Task Scheduling

Zubair Mohsin — Wed, 10 Mar 2021 16:06:27 +0000

From the About section of dragonmantank/cron-expression package on GitHub:

CRON for PHP: Calculate the next or previous run date and determine if a CRON expression is due.

This package helps in dealing with CRON jobs in following ways:

Determine if a cron job is due running?
When will a job run next?
When a cron job was previously ran?

Let’s take a look at implementation of these features in CronExpression class of this package.

<?php

namespace Cron;

class CronExpression
{
    /**
     * Determine if the cron is due to run based on the current date or a
     * specific date.  This method assumes that the current number of
     * seconds are irrelevant, and should be called once per minute.
     *
     * @param string|\DateTimeInterface $currentTime Relative calculation date
     * @param null|string               $timeZone    TimeZone to use instead of the system default
     *
     * @return bool Returns TRUE if the cron is due to run or FALSE if not
     */
    public function isDue($currentTime = 'now', $timeZone = null): bool
    {
        $timeZone = $this->determineTimeZone($currentTime, $timeZone);

        if ('now' === $currentTime) {
            $currentTime = new DateTime();
        } elseif ($currentTime instanceof DateTime) {
            $currentTime = clone $currentTime;
        } elseif ($currentTime instanceof DateTimeImmutable) {
            $currentTime = DateTime::createFromFormat('U', $currentTime->format('U'));
        } elseif (\is_string($currentTime)) {
            $currentTime = new DateTime($currentTime);
        }

        Assert::isInstanceOf($currentTime, DateTime::class);
        $currentTime->setTimezone(new DateTimeZone($timeZone));

        // drop the seconds to 0
        $currentTime->setTime((int) $currentTime->format('H'), (int) $currentTime->format('i'), 0);

        try {
            return $this->getNextRunDate($currentTime, 0, true)->getTimestamp() === $currentTime->getTimestamp();
        } catch (Exception $e) {
            return false;
        }
    }

     /**
     * Get a next run date relative to the current date or a specific date
     *
     * @param string|\DateTimeInterface $currentTime      Relative calculation date
     * @param int                       $nth              Number of matches to skip before returning a
     *                                                    matching next run date.  0, the default, will return the
     *                                                    current date and time if the next run date falls on the
     *                                                    current date and time.  Setting this value to 1 will
     *                                                    skip the first match and go to the second match.
     *                                                    Setting this value to 2 will skip the first 2
     *                                                    matches and so on.
     * @param bool                      $allowCurrentDate Set to TRUE to return the current date if
     *                                                    it matches the cron expression.
     * @param null|string               $timeZone         TimeZone to use instead of the system default
     *
     * @throws \RuntimeException on too many iterations
     * @throws \Exception
     *
     * @return \DateTime
     */
    public function getNextRunDate($currentTime = 'now', int $nth = 0, bool $allowCurrentDate = false, $timeZone = null): DateTime
    {
        return $this->getRunDate($currentTime, $nth, false, $allowCurrentDate, $timeZone);
    }

    /**
     * Get a previous run date relative to the current date or a specific date.
     *
     * @param string|\DateTimeInterface $currentTime      Relative calculation date
     * @param int                       $nth              Number of matches to skip before returning
     * @param bool                      $allowCurrentDate Set to TRUE to return the
     *                                                    current date if it matches the cron expression
     * @param null|string               $timeZone         TimeZone to use instead of the system default
     *
     * @throws \RuntimeException on too many iterations
     * @throws \Exception
     *
     * @return \DateTime
     *
     * @see \Cron\CronExpression::getNextRunDate
     */
    public function getPreviousRunDate($currentTime = 'now', int $nth = 0, bool $allowCurrentDate = false, $timeZone = null): DateTime
    {
        return $this->getRunDate($currentTime, $nth, true, $allowCurrentDate, $timeZone);
    }
}

The real meat is getRunDate() method. But its implementation is huge, it will only increase length of the blog. Here you can find full source code.

Usage in `schedule:run` command

Laravel leverages this package in Task Scheduling. Let’s say we make a command named say:hello and we schedule it hourly() inside Console\Kernel.php like below:

    /**
     * Define the application's command schedule.
     *
     * @return void
     */
    protected function schedule(Schedule $schedule)
    {
        $schedule->command('say:hello')->hourly();
    }

Now, let’s see what happens when we run schedule:run command. Below is a ripped off version of schedule:run command’s handle method.

    public function handle(Schedule $schedule, ...)
    {
        foreach ($this->schedule->dueEvents($this->laravel) as $event) {
            if (! $event->filtersPass($this->laravel)) {
                $this->dispatcher->dispatch(new ScheduledTaskSkipped($event));

                continue;
            }

            if ($event->onOneServer) {
                $this->runSingleServerEvent($event);
            } else {
                $this->runEvent($event);
            }
        }
    }

As we can see it loops through all due events , checks if given filters for the event do not pass, it skips that event, otherwise run that event.

Let’s take a look at dueEvents() method on Schedule class and understand what are events.

    /**
     * Get all of the events on the schedule that are due.
     *
     * @param  \Illuminate\Contracts\Foundation\Application  $app
     * @return \Illuminate\Support\Collection
     */
    public function dueEvents($app)
    {
        return collect($this->events)->filter->isDue($app);
    }

    /**
     * Get all of the events on the schedule.
     *
     * @return \Illuminate\Console\Scheduling\Event[]
     */
    public function events()
    {
        return $this->events;
    }

dueEvents() return a collection of Illuminate\Console\Scheduling\Event objects, filtering these objects based on if they are due or not.

Now, let’s head over to Illuminate\Console\Scheduling\Event to see the implementation of isDue() method.

    /**
     * Determine if the given event should run based on the Cron expression.
     *
     * @param  \Illuminate\Contracts\Foundation\Application  $app
     * @return bool
     */
    public function isDue($app)
    {
        if (! $this->runsInMaintenanceMode() && $app->isDownForMaintenance()) {
            return false;
        }

        return $this->expressionPasses() &&
               $this->runsInEnvironment($app->environment());
    }

      /**
     * Determine if the Cron expression passes.
     *
     * @return bool
     */
    protected function expressionPasses()
    {
        $date = Carbon::now();

        if ($this->timezone) {
            $date->setTimezone($this->timezone);
        }

        return CronExpression::factory($this->expression)->isDue($date->toDateTimeString());
    }

isDue() method checks for maintenance first, after that it calls expressionPasses() method, where we can finally see CronExpression class being used to determine if the cron expression of an event ( scheduled command ) is due .

Usage in `schedule:list` command

php artisan schedule:list command outputs a table on the command line like shown below. It contains information about all schedule commands, e.g. their interval, description and when a command is next due.

Let’s take a look at the handle method of this command.

    /**
     * Execute the console command.
     *
     * @param  \Illuminate\Console\Scheduling\Schedule  $schedule
     * @return void
     * @throws \Exception
     */
    public function handle(Schedule $schedule)
    {
        foreach ($schedule->events() as $event) {
            $rows[] = [
                $event->command,
                $event->expression,
                $event->description,
                (new CronExpression($event->expression))
                            ->getNextRunDate(Carbon::now())
                            ->setTimezone($this->option('timezone', config('app.timezone'))),
            ];
        }

        $this->table([
            'Command',
            'Interval',
            'Description',
            'Next Due',
        ], $rows ?? []);
    }

As we can see, in order to get information about Next Due, Laravel utilises CronExpression class and it’s getNextRunDate() method.

Interesting facts about `cron-expression` package in Laravel context

It was first known as mtdowling/cron-expression , which was abandoned on 20 Dec, 2019 by Chris Tankersley
After that forked and maintained by Chris himself under dragonmantank/cron-expression
Taylor Otwell first used this package in Laravel v5.0 when he started working on scheduled commands back in 2014
Link to Taylor’s commit on GitHub when he first used this package in Laravel

I hope you find this blogpost useful. Next up we'll see how Laravel uses egulias/email-validator package. Stay in the loop by following me on Twitter

How Laravel uses `doctrine/inflector` package

Zubair Mohsin — Tue, 09 Mar 2021 12:56:25 +0000

doctrine/inflector is a small library which helps in uppercase/lowercase and singular/plural based manipulation of a string.

Laravel uses this package in a class called Pluralizer as shown below:

<?php

namespace Illuminate\Support;

use Doctrine\Inflector\CachedWordInflector;
use Doctrine\Inflector\Inflector;
use Doctrine\Inflector\Rules\English;
use Doctrine\Inflector\RulesetInflector;

class Pluralizer
{
    /**
     * Get the plural form of an English word.
     *
     * @param  string  $value
     * @param  int  $count
     * @return string
     */
    public static function plural($value, $count = 2)
    {
        if ((int) abs($count) === 1 || static::uncountable($value) || preg_match('/^(.*)[A-Za-z0-9\x{0080}-\x{FFFF}]$/u', $value) == 0) {
            return $value;
        }

        $plural = static::inflector()->pluralize($value);

        return static::matchCase($plural, $value);
    }

    /**
     * Get the singular form of an English word.
     *
     * @param  string  $value
     * @return string
     */
    public static function singular($value)
    {
        $singular = static::inflector()->singularize($value);

        return static::matchCase($singular, $value);
    }
}

Full source code can be found{' '} here

Laravel then uses Pluralizer class in Str helper class. Str::singular() and Str::plural() helper methods leverage Pluralizer::singular() and Pluralizer::plural() respectively as shown below:

<?php

namespace Illuminate\Support;

use Illuminate\Support\Traits\Macroable;

class Str
{
    use Macroable;

    /**
     * Get the plural form of an English word.
     *
     * @param  string  $value
     * @param  int  $count
     * @return string
     */
    public static function plural($value, $count = 2)
    {
        return Pluralizer::plural($value, $count);
    }

    /**
     * Get the singular form of an English word.
     *
     * @param  string  $value
     * @return string
     */
    public static function singular($value)
    {
        return Pluralizer::singular($value);
    }
}

Full source code can be found{' '} here

How Laravel deals with Uncountables?

If we look at the implementation of Pluralizer class, we can see that Laravel maintains an array of uncountables like education, audio, jedi etc. If you provide such value to Str::plural() helper method, it will be returned as it is.

I hope you find this blogpost useful. Next up we'll see how Laravel uses dragonmantank/cron-expression package. Stay in the loop by following me on Twitter.

Exploring service discovery attribute in Shopify CarrierService API

Zubair Mohsin — Mon, 11 Jan 2021 10:44:29 +0000

Overview

According to Shopify docs, a Carrier Service is:

A carrier service (also known as a carrier calculated service or shipping service) provides real-time shipping rates to Shopify. Some common carrier services include Canada Post, FedEx, UPS, and USPS. The term carrier is often used interchangeably with the terms shipping company and rate provider.

If we are creating an app that provides shipping rates on the checkout, then we need to provide an endpoint which will accept a POST request from Shopify and then return rates accordingly.

In order to do that, we need to use CarrierService API and send a request like below:

POST /admin/api/2021-01/carrier_services.json
{
  "carrier_service": {
    "name": "Shipping Rate Provider",
    "callback_url": "http://shippingrateprovider.com",
    "service_discovery": true
  }
}

callback_url points to the endpoint in our app which will accept the POST request from Shopify and provide rates in return.

There is also another attribute called service_discovery which is set to true. This post aims to explain all about this option.

Service Discovery

service_discovery attribute. What is it about?

According to Shopify docs:

Whether merchants are able to send dummy data to your service through the Shopify admin to see shipping rate examples, if set to true

Above statement is a bit misleading, as some would think that there will be a form in Shopify Admin which merchants would fill to send dummy data to get example rates. But that's not the case. We'll now see how this request is sent to our endpoint.

How service discovery request is sent?

After a merchant creates a Shipping Zone inside a Shipping Profile on Shopify. They can Add rate to that shipping zone. They can set up their own rates or use a third party app to calculate rates. We are interested in the second option. Apps which have registered their endpoint using CarrierService API will appear in the dropdown as shown in the screenshot below:

Postcode Shipping is a third-party app which provides rates.

The moment merchant selects the app from the dropdown, a request is sent to the registered callback endpoint of that app.

How to identify service discovery request?

Unfortunately, there is no special identifier for this request. You can explore the JSON data (shown below) to select an attribute for yourself to differentiate the service discovery request from original request of checkout.

What data is sent with service discovery request?

Dummy data is sent when Shopify makes the service discovery request. Merchants cannot alter that data ( at the time writing this article, but this may change in future ).
Below is the JSON structure of the dummy data sent with service discovery request.

{
      "rate":{
         "origin":{
            "country":"PK",
            "postal_code":"54700",
            "province":null,
            "city":"Lahore",
            "name":"House 584 Model Town Q Block",
            "address1":"House 584 Model Town Q Block",
            "address2":null,
            "address3":null,
            "phone":null,
            "fax":null,
            "email":null,
            "address_type":null,
            "company_name":"rateprovidertest"
         },
         "destination":{
            "country":"US",
            "postal_code":"90210",
            "province":"CA",
            "city":"rate test",
            "name":null,
            "address1":"rate test",
            "address2":null,
            "address3":null,
            "phone":null,
            "fax":null,
            "email":null,
            "address_type":null,
            "company_name":null
         },
         "items":[
            {
               "name":null,
               "sku":"XXXXXXXX",
               "quantity":1,
               "grams":100,
               "price":0,
               "vendor":null,
               "requires_shipping":true,
               "taxable":true,
               "fulfillment_service":"manual",
               "properties":null,
               "product_id":null,
               "variant_id":null
            }
         ],
         "currency":"PKR",
         "locale":"en"
      }
}

origin contains the address of pickup location for the selected shipping profile.
destination contains a dummy/random address of the country according to created shipping zone.
items attribute is an array which represent dummy cart items.

Rest of World shipping zone

If the shipping zone we created is only for one country then Shopify will send one request with destination country set to selected country.

If shipping zone is Rest of World then Shopify sends four requests for four different countries.

While working on it, we found out that Shopify sends four requests with country set to United States of America (US), Mexico (MX), Denmark (DE) and Japan (JP) respectively. This pattern of requests may change in future.

This can cause confusion in the case when merchant has setup a separate shipping zone and rates for a country like US and then also see those rates in Rest of World shipping zone. Be ready to answer some support tickets.

How rates/services are shown to merchants?

When merchant selects the app from dropdown and a request is sent to third-party app, if they return rates/services, it will be shown in the SERVICES section of the modal as shown below:

Two rates returned from third party app for the US country.

What happens when merchant selects a rate/service?

If a merchant selects one rate from above screenshot, only that rate will be shown on checkout.

Lets take a look at an example. If merchant creates a shipping zone for USA and third-party app returns two rates in response to service discovery request. Merchant selects one of them. Then only selected rate will be shown on the checkout. Even though third-party will still be providing two rates in response to request made on the checkout.

Conclusion

In this post we explored the service discovery request sent by Shopify to a third-party shipping rate provider app. We looked at service_discovery attribute, what is it and what happens when it is set to true. How service discovery is sent, identifying such request and what data is sent along with this request. We also looked at differences for Rest of World shipping zone. In the end, we discovered how rates/services are shown to merchants inside Shopify and what happens on the checkout when they select one of them.

Unfortunately, this feature is not properly documented in Shopify docs. All the information that is stated above, was found by trial and error approach.

You can follow me on Twitter as I keep learning and writing about Shopify, Laravel and React.

Forem: Zubair Mohsin

Why Laravel requires `ramsey/uuid` package?

What is a UUID?

UUIDs in Laravel

Code Dive

UUIDs in Laravel migrations

Interesting facts about ramsey/uuid in Laravel context

Why Laravel requires `psr/container` package?

Laravel Container

But, Why?

PHP-FIG

PSR

Conclusion

Interesting facts about psr/container in Laravel context

How closures are serialized in Laravel using `opis/closure` package

Code Dive

Usage in Laravel

dispatch() helper

CallQueuedClosure::create()

PendingClosureDispatch

Conclusion

Interesting facts about opis/closure in Laravel context

How date and time work in Laravel using `nesbot/carbon` package

Code Dive

Date facade

DateFactroy class

Illuminate\Support\Carbon

Finding now() method

Interesting facts about nesbot/carbon package in Laravel

How Logging works in Laravel using `monolog/monolog` package

Code Dive

Log facade

Log::info()

resolve() method

Interesting facts about Monolog in Laravel context

How Laravel uses `league/flysystem` package to create robust Filesystem

Code Dive

The FilesystemManager

But, how it all works?

Storage Facade

Storage::disk('local')

Storage::disk('local')→put()

Interesting facts about Flysystem in Laravel context

Laracon Online 2021 talks Twitter thread links

Mohamed Said

Taylor Otwell

Christoph Rumpel

Bobby Bouwmann

Marcel Pociot

MIGUEL Piedrafita

Caleb Porzio

Nuno Maduro

How markdown emails work in Laravel using `league/commonmark` package

Mail in Laravel

Markdown Mailables

What happens when you Mail::to()→send() ?

Code Dive

Finding the Mailer

The Mailer

The Mailable

The Markdown

Interesting facts about Markdown in Laravel

How email validation works in Laravel using `egulias/email-validation` package'

Code Dive

What happens when we send the request?

Interesting facts about this package in Laravel context

How Laravel uses dragonmantank/cron-expression package in Task Scheduling

Usage in schedule:run command

Usage in schedule:list command

Interesting facts about cron-expression package in Laravel context

How Laravel uses `doctrine/inflector` package

How Laravel deals with Uncountables?

Exploring service discovery attribute in Shopify CarrierService API

Overview

Service Discovery

service_discovery attribute. What is it about?

How service discovery request is sent?

How to identify service discovery request?

What data is sent with service discovery request?

Rest of World shipping zone

Interesting facts about `ramsey/uuid` in Laravel context

Interesting facts about `psr/container` in Laravel context

Interesting facts about `opis/closure` in Laravel context

Interesting facts about `nesbot/carbon` package in Laravel

Usage in `schedule:run` command

Usage in `schedule:list` command

Interesting facts about `cron-expression` package in Laravel context