Package Management in Laravel

In this article, we'll go ahead and explore the package management feature in the Laravel framework. In the course of the article, we’ll go through a real-world example to demonstrate the purpose of the article.

Package management in Laravel is an important feature that allows you to bundle a piece of functionality so that it can be distributed easily. Moreover, you could always publish your package to repositories like Packagist and GitHub that allow other developers to benefit from your package.

To demonstrate the concept, we’ll build an example page in Laravel that uploads an image to the Amazon S3 cloud. Rather than going with the usual flow, we’ll develop it as a bundled package that can be distributed and maintained easily.

Before moving ahead, I assume that you are familiar with the Laravel framework already as I won't go into the details of basic Laravel concepts.

Also, you need to have a valid AWS account and the credentials to access the Amazon API in order to follow along with the example in this article. So, make sure that you set that up first.

With everything on hand, we are ready to dive into the actual development.

Setting Up the Package Files

Let's quickly look at the list of files that we'll implement throughout the course of this tutorial.

• 
  composer.json: We need to add the class mapping of our package in the existing composer.json file in the root of the package.


• 
  config/app.php: This is the existing file that we'll use to add an entry of our custom service provider so that we can load views and routes using that file.


• 
  composer.json: This is the package-specific composer.json file should you wish to distribute the package with others.


• 
  packages/envato/aws/src/Providers/AwsServiceProvider.php: The usual Laravel service provider file that will be used to load other components of the package.


• 
  packages/envato/aws/src/routes/web.php: It loads the custom routes of our package.


• 
  packages/envato/aws/src/Controllers/AwsController.php: This is the controller file that handles the application logic of our package.


• 
  packages/envato/aws/src/views/upload.blade.php: The view file that handles the rendering logic.

Don't worry if it doesn't make much sense yet as we'll discuss everything in detail as we go through it.

Setting Up the Prerequisites

As we discussed earlier, our package implements the use case of file upload to Amazon S3 cloud. In this section, we'll go through the prerequisites that need to be set up in order to run our package successfully.

As a Laravel developer, you must be familiar with Flysystem, which provides a nice abstraction layer to interact with the filesystem. It provides easy-to-use drivers so that you can interact with it easily no matter the type of filesystem you're dealing with—either it's the local file system or the AWS S3 cloud system.

In order to enable the support of Amazon S3 cloud filesystem with Flysystem, you need to install the corresponding adapter composer package.

Go ahead and run the following composer command from your project root to install the flysystem-aws-s3-v3 package.

$composer require league/flysystem-aws-s3-v3

Upon the successful execution of that command, now you're able to use Laravel Flysystem to interact with Amazon S3 cloud filesystem in the same way you would have used it for the local file system.

Now, let's quickly pull in the config/filesystems.php file to see the settings provided for the Amazon S3 filesystem.

...
...
'disks' => [
    'local' => [
        'driver' => 'local',
        'root' => storage_path('app'),
    ],

    'public' => [
        'driver' => 'local',
        'root' => storage_path('app/public'),
        'url' => env('APP_URL').'/storage',
        'visibility' => 'public',
    ],

    's3' => [
        'driver' => 's3',
        'key' => env('AWS_KEY'),
        'secret' => env('AWS_SECRET'),
        'region' => env('AWS_REGION'),
        'bucket' => env('AWS_BUCKET'),
    ],
],
...
...

As you can see, the configuration is already in place for the Amazon S3; it's just that we need to set appropriate ENV variables in the .env file.

Go ahead and add the following variables in your .env file.

AWS_KEY={AWS_KEY_VALUE}
AWS_SECRET={AWS_SECRET_VALUE}
AWS_REGION={AWS_REGION_VALUE}
AWS_BUCKET={AWS_BUCKET_VALUE}
AWS_CDN_URL={AWS_CDN_URL_VALUE}

Of course, you need to replace placeholders with their actual values. Now, you're ready to use the Flysystem AWS S3 adapter in your Laravel application.

Going Through the Package Files

To create your own Laravel package, the first thing is to create an appropriate directory structure that reflects the conventions of the Laravel system. I assume that you're already running a basic Laravel application; in fact, the default blog application will do as well.

Go ahead and create the packages directory in the root of your application. Considering that you're going to distribute your package with others, the preferred structure of your package should be {vendor_name}/{package_name}.

Following that convention, let's go ahead and create an envato/aws directory under the packages directory. As you may have guessed, envato is the vendor name, and aws stands for the package name itself. Finally, let's create a packages/envato/aws/src directory that holds the source files of our package.

Now, we need to inform Laravel about our new package. Go ahead and open the composer.json file in the root of your Laravel application and add the "Envato\\Aws\\": "packages/envato/aws/src" entry in the autoload section as shown below.

...
...
"autoload": {
    "classmap": [
        "database"
    ],
    "psr-4": {
        "App\\": "app/",
        "Envato\\Aws\\": "packages/envato/aws/src"
    }
},
...
...

As you can see, the Envato\Aws\ namespace is mapped to the packages/envato/aws/src directory. Now, we just need to run the dump-autoload command to regenerate the composer mappings.

$composer dump-autoload

Now, you can use the Envato\Aws\ namespace in your application and it'll pick up the files from the correct location!

Composer File of the Package

Now, let's go ahead and add a package-specific composer.json file so that you can distribute your package to the packagist repository.

Go to the packages/envato/aws directory and run the following command to generate a composer.json file for your package.

$composer init

You'll be prompted with the usual questions, so just go through it and it'll create a composer.json file.

At the very least, it should look something like this.

{
    "name": "envato/aws",
    "description": "Example of File Upload to AWS S3 Cloud",
    "minimum-stability": "dev",
    "require": {}
}

Route

In our package, we'll create a simple page that displays the status of the uploaded file. So we need to create a route associated with that page.

Let's create a route file at packages/envato/aws/src/routes/web.php.

<?php
Route::get('aws/s3/upload', 'Envato\Aws\Controllers\AwsController@upload');

Does it require any explanation at all? The obvious next step is to create the associated controller file.

Controller

Let's create a controller file at packages/envato/aws/src/Controllers/AwsController.php with the following contents.

<?php
namespace Envato\Aws\Controllers;

use App\Http\Controllers\Controller;

class AwsController extends Controller
{
  public function upload(\Illuminate\Contracts\Filesystem\Factory $storage)
  {
    // load s3 storage
    $awsS3Storage = $storage->disk('s3');
    
    // load local storage
    $localStorage = $storage->disk('local');

    // default path of local storage "storage/app"
    $sourceFileContents = $localStorage->get('test.jpg');
    
    // destination filepath in S3 cloud
    $destFilePath = 'test_new.jpg';
    
    // init vars
    $imageUrl = '';
    $errorMsg = '';

    // upload file to AWS S3
    if ($awsS3Storage->put($destFilePath, $sourceFileContents, 'public'))
    {
      $imageUrl = env('AWS_CDN_URL') . env('AWS_BUCKET') . '/' . $destFilePath;
    }
    else
    {
      $errorMsg = 'Oops! Something went wrong :(';
    }

    // call view
    return view('aws::upload', ['imageUrl' => $imageUrl, 'errorMsg' => $errorMsg]);
  }
}

Let's go through the file to understand what every piece of code is meant for.

We kick off the things by setting a namespace of our controller to namespace Envato\Aws\Controllers. Recall that we added the mapping of Envato\Aws to packages/envato/aws/src in the root composer.json file so that it could find our package files.

Next, we've defined the upload method that does the needful to sync local files to the Amazon S3 cloud. The important thing to note here is the first argument of the upload method that asks for the \Illuminate\Contracts\Filesystem\Factory dependency. During the execution, the appropriate Laravel contract will be injected.

Now, we could use the filesystem factory instance to create disk instances as needed. The disk instance in Laravel is the driver that allows you easy access to underlying filesystems such as the local disk, Amazon S3 cloud, and the like.

// load s3 storage
$awsS3Storage = $storage->disk('s3');
    
// load local storage
$localStorage = $storage->disk('local');

For simplicity, we'll transfer the static image file that's already available under the default local storage of Laravel, and the path is storage/app/test.jpg.

As a first step, let's grab the source file contents.

// default path of local storage "storage/app"
$sourceFileContents = $localStorage->get('test.jpg');

With everything set up as mentioned, you should be able to sync a file to Amazon S3 using the put method.

// upload file to AWS S3
if ($awsS3Storage->put($destFilePath, $sourceFileContents, 'public'))
{
  $imageUrl = env('AWS_CDN_URL') . env('AWS_BUCKET') . '/' . $destFilePath;
}
else
{
  $errorMsg = 'Oops! Something went wrong :(';
}

Make sure that you've set the AWS environment variables correctly, just in case something doesn't work as expected.

And the last thing is to call a view file that displays the synced image and an appropriate message.

// call view
return view('aws::upload', ['imageUrl' => $imageUrl, 'errorMsg' => $errorMsg]);

Of course, we haven't created a view file yet, and that's exactly what the next section is all about.

View

Let's create a view file at packages/envato/aws/src/views/upload.blade.php with the following contents.

<!DOCTYPE html>
<html lang="{{ config('app.locale') }}">
    <head>
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1">

        <title>Laravel</title>

        <!-- Fonts -->
        <link href="https://fonts.googleapis.com/css?family=Raleway:100,600" rel="stylesheet" type="text/css">

        <!-- Styles -->
        <style>
            html, body {
                background-color: #fff;
                color: #636b6f;
                font-family: 'Raleway', sans-serif;
                font-weight: 100;
                height: 100vh;
                margin: 0;
            }

            .full-height {
                height: 100vh;
            }

            .flex-center {
                align-items: center;
                display: flex;
                justify-content: center;
            }

            .position-ref {
                position: relative;
            }

            .top-right {
                position: absolute;
                right: 10px;
                top: 18px;
            }

            .content {
                text-align: center;
            }

            .title {
                font-size: 84px;
            }

            .links > a {
                color: #636b6f;
                padding: 0 25px;
                font-size: 12px;
                font-weight: 600;
                letter-spacing: .1rem;
                text-decoration: none;
                text-transform: uppercase;
            }

            .m-b-md {
                margin-bottom: 30px;
            }
        </style>
    </head>
    <body>
        <div class="flex-center position-ref full-height">
            @if (Route::has('login'))
                <div class="top-right links">
                    @if (Auth::check())
                        <a href="{{ url('/home') }}">Home</a>
                    @else
                        <a href="{{ url('/login') }}">Login</a>
                        <a href="{{ url('/register') }}">Register</a>
                    @endif
                </div>
            @endif

            <div class="content">
                <div class="title m-b-md">
                    File upload to S3 Cloud
                </div>

                <div>
                  @if ($imageUrl)
                      <img src="{{ $imageUrl }}" width="100"/>
                  @else
                      <span class="error">{{ $errorMsg }}</span>
                  @endif
                </div>
            </div>
        </div>
    </body>
</html>

It's a pretty standard view file that displays the uploaded image upon the successful upload, or otherwise an appropriate error message.

Service Provider

We're almost done with our package as we've created the necessary files. The next step is to create a service provider so that we can register the routes and views of our package.

Let's create a service provider file at packages/envato/aws/src/Providers/AwsServiceProvider.php with the following contents.

<?php

namespace Envato\Aws\Providers;

use Illuminate\Support\ServiceProvider;

class AwsServiceProvider extends ServiceProvider
{
  /**
   * Bootstrap the application services.
   *
   * @return void
   */
  public function boot()
  {
      // load routes
      $this->loadRoutesFrom(__DIR__.'/../routes/web.php');

      // load view files
      $this->loadViewsFrom(__DIR__.'/../views', 'aws');
      
      // publish files
      $this->publishes([
      __DIR__.'/../views' => resource_path('views/vendor/aws'),
    ]);
  }

  /**
   * Register the application services.
   *
   * @return void
   */
  public function register()
  {
  }
}

Obviously, you could have created the service provider file by using the artisan command as well. But it would have required an extra step of moving the file from app/Providers to our package.

Anyway, let's go through the service provider file that was just created.

Firstly, we load the routes and views associated with our package.

// load routes
$this->loadRoutesFrom(__DIR__.'/../routes/web.php');

// load view files
$this->loadViewsFrom(__DIR__.'/../views', 'aws');

Next, we provide the support of publishing the views of our packages so that the developers who want to override the views can do that. Next time they run the php artisan vendor:publish command, Laravel copies the views from packages/envato/aws/src/views/ to resources/views/vendor/aws.

Now, they can change the views under the resources/views/vendor/aws directory, and it'll be picked up automatically by Laravel instead of the views under packages/envato/aws/src/views/. In fact, it's the proper way to modify third-party package views, instead of directly modifying the package views.

That's it as far as the service provider is concerned. As you would have expected, we need to add the service provider entry in config/app.php. Add the following entry in the providers array.

...
...
/*
 * Application Service Providers...
 */
App\Providers\AppServiceProvider::class,
App\Providers\AuthServiceProvider::class,
App\Providers\BroadcastServiceProvider::class,
App\Providers\EventServiceProvider::class,
App\Providers\RouteServiceProvider::class,
Envato\Aws\Providers\AwsServiceProvider::class, // Our package service provider
...
...

And there you are—everything's in order now, so that we can go ahead and test our package.

Go ahead and run the https://your-laravel-application/aws/s3/upload URL in your browser. If everything goes fine, you should see the image on your page that's loaded from the Amazon S3 cloud. Please let me know if you face any problems, and I would be more than happy to answer those.

So we are on the closing note of this article, and I hope you've enjoyed it!

Conclusion

Today, we discussed one of the important features of the Laravel framework—package management. In the process of setting up our custom Laravel package, we went through a real-world example that demonstrated how you could upload an image to the Amazon S3 cloud.

It's a really nice feature should you wish to bundle and distribute a set of functionalities all together. In fact, you could look at this as an option to approach your custom module development in Laravel.

For those of you who are either just getting started with Laravel or looking to expand your knowledge, site, or application with extensions, we have a variety of things you can study on Envato Market.

As always, you could leave your valuable comments and feedback in the feed below!