Forem: Nad Lambino

Handling File Uploads in Laravel, Automatically.

Nad Lambino — Wed, 10 Jul 2024 13:15:52 +0000

Managing your file uploads in Laravel is really easy... or is it? Actually, it is really easy, and you can do this in so many ways which you might or might not like.

Today, I will introduce you to my first Laravel package which I have created to handle the file uploads for your models, automatically.

Laravel Uploadable takes care of the files from your request and upload them for your model. Below is the detailed documentation to get you started.

Installation
Usage
Customizing the Rules and Messages
Customizing the File Name and Upload Path
Uploading Files with Custom Options for the Storage
Manually Processing File Uploads
Temporarily Disable the File Upload Process
Uploading Files on Model Update
Uploading Files that are NOT from the Request
Relation Methods
Lifecycle and Events
Queueing

Installation

You can install the package via composer:

composer require nadlambino/uploadable

Publish and run the migrations with:

php artisan vendor:publish --tag="uploadable-migrations"
php artisan migrate

IMPORTANT

You can add more fields to the uploads table according to your needs, but the existing fields should remain.

Optionally, you can publish the Upload model using

php artisan vendor:publish --tag="uploadable-model"

You can publish the config file with:

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

Usage

Simply use the NadLambino\Uploadable\Concerns\Uploadable trait to your model that needs file uploads.

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use NadLambino\Uploadable\Concerns\Uploadable;

class Post extends Model
{
    use Uploadable;
}

Now, everytime you create or update a post, it will automatically upload the files that are included in your request and it will save the details in uploads table.

Customizing the Rules and Messages

Files from the request should have the following request names:

Request name	Use Case	Rules
document	Single document upload	sometimes, file, mime
documents	Multiple document uploads	sometimes, file, mime
image	Single image upload	sometimes, image, mime
images	Multiple image uploads	sometimes, image, mime
video	Single video upload	sometimes, mime
videos	Multiple video uploads	sometimes, mime

You can add more fields or override the default ones by defining the protected uploadRules
method in your model.

protected function uploadRules(): array
{
    return [
        // Override the rules for `document` field
        'document' => ['required', 'file', 'mime:application/pdf'], 

        // Add a new field with it's own set of rules
        'avatar' => ['required', 'image', 'mime:png'] 
    ];
}

To add or override the rules messages, you can define the protected uploadRuleMessages method in your model.

public function uploadRuleMessages(): array
{
    return [
        'document.required' => 'The file is required.',
        'document.mime' => 'The file must be a PDF file.',
        'avatar.required' => 'The avatar is required.',
        'avatar.mime' => 'The avatar must be a PNG file.'
    ];
}

Customizing the file name and upload path

You can customize the file name and path by defining the public methods getUploadFilename and getUploadPath in your model.

public function getUploadFilename(UploadedFile $file): string
{
    return str_replace('.', '', microtime(true)).'-'.$file->hashName();
}

public function getUploadPath(UploadedFile $file): string
{
    return $this->getTable().DIRECTORY_SEPARATOR.$this->{$this->getKeyName()};
}

IMPORTANT

Make sure that the file name is completely unique to avoid overriding existing files.

Uploading Files with Custom Options for the Storage

When you're uploading your files on cloud storage, oftentimes you want to provide options like visibility, cache control, and other metadata. To do so, you can define the getUploadStorageOptions in your uploadable model.

public function getUploadStorageOptions(): array
{
    return [
        'visibility' => 'public',
        'CacheControl' => 'max-age=315360000, no-transform, public'
    ];
}

Manually processing file uploads

File upload happens when the uploadable model's created or updated event was fired.
If you're creating or updating an uploadable model quietly, you can call the createUploads or updateUploads method to manually process the file uploads.

public function update(Request $request, Post $post)
{
    $post->update($request->all());

    // If the post did not change, the `updated` event won't be fired.
    // So, we need to manually call the `updateUploads` method.
    if (! $post->wasChanged()) {
        $post->updateUploads();
    }
}

IMPORTANT

Depending on your configuration, the createUploads will delete the uploadable model when the upload process fails, while updateUploads will update it to its original attributes.

Temporarily Disable the File Upload Process

You can temporarily disable the file uploads by calling the static method disableUpload.

public function update(Request $request, Post $post)
{
    // Temporarily disable the file uploads
    Post::disableUpload();

    $post->update($request->all());

    // Do more stuff here...

    // Manually process the uploads after everything you want to do.
    $post->updateUploads();
}

Caveat

When you are trying to create or update multiple uploadable models, the default behavior of this package is that all of the files from the request will be uploaded and will be attached to all of these models. This is because these models are firing the created or updated event which triggers the upload process.

There are multiple ways to prevent this from happening such as:

Silently create or update the models that you don't want to have the files being uploaded and attached to them. By doing so, the created or updated event won't be fired which will not trigger the upload process.
Disable the upload process on the specific model by calling the disableUpload() method.
Disable the upload process from the NadLambino\Uploadable\Actions\Upload action itself. The NadLambino\Uploadable\Actions\Upload::disableFor() method can accept a string class name of a model, a model instance, or an array of each or both. See below example:

use NadLambino\Uploadable\Actions\Upload;

public function store(Request $request)
{
    // Disable the uploads for all of the instances of Post model during this request lifecycle
    Upload::disableFor(Post::class);

    // User will be created with the files being uploaded and attached to it
    User::create($request->validated());

    // Post will be created without the files being uploaded and attached to it
    Post::create(...);
}

// OR

public function update(Request $request, User $user)
{
     // Disable the uploads only for this specific user during this request lifecycle
    Upload::disableFor($user);

    // $user will be updated without the files being uploaded and attached to it
    $user->update($request->validated());

    $anotherUser = User::find(...);

    // $anotherUser will be updated with the files being uploaded and attached to it
    $anotherUser->update(...);
}

Also, there is NadLambino\Uploadable\Actions\Upload::enableFor() method to let you enable the upload process for the given model. This will just remove the given model class or instance from the list of disabled models. Both of these methods will also work on queued uploads.

Uploading files on model update

By default, when you update an uploadable model, the files from the request will add up to the existing uploaded files. If you want to replace the existing files with the new ones, you can configure it in the uploadable.php config file.

'replace_previous_uploads' => true,

Or alternatively, you can call the static method replacePreviousUploads before updating the model.

public function update(Request $request, Post $post)
{
    // Replace the previous uploads
    Post::replacePreviousUploads();

    $post->update($request->all());
}

NOTE

The process of deleting the previous uploads will only happen when new files were successfully
uploaded.

Uploading files that are NOT from the request

If you wish to upload a file that is not from the request, you can do so by calling the uploadFrom method. This method can accept an instance or an array of \Illuminate\Http\UploadedFile or a string path of a file that is uploaded on your temporary_disk.

// DO
$post->uploadFrom(UploadedFile::fake()->image('avatar1.jpg'));

// OR
$post->uploadFrom([
    UploadedFile::fake()->image('avatar1.jpg'),
    UploadedFile::fake()->image('avatar2.jpg'),
]);

// OR
$fullpath = UploadedFile::fake()->image('avatar.jpg')->store('tmp', config('uploadable.temporary_disk', 'local'));

$post->uploadFrom($fullpath);

// OR
$post->uploadFrom([
    $fullpath1,
    $fullpath2
]);

// OR even a mixed of both
$post->uploadFrom([
    UploadedFile::fake()->image('avatar1.jpg'),
    $fullpath,
]);

$post->save();

IMPORTANT

Make sure that you've already validated the files that you're passing here as it does not run any validation like it does when uploading from request.

Relation methods

There are already pre-defined relation method for specific upload type.

// Relation for all types of uploads
public function upload(): MorphOne { }

// Relation for all types of uploads
public function uploads(): MorphMany { }

// Relation for uploads where extension or type is in the accepted image mimes
public function image(): MorphOne { }

// Relation for uploads where extension or type is in the accepted image mimes
public function images(): MorphMany { }

// Relation for uploads where extension or type is in the accepted video mimes
public function video(): MorphOne { }

// Relation for uploads where extension or type is in the accepted video mimes
public function videos(): MorphMany { }

// Relation for uploads where extension or type is in the accepted document mimes
public function document(): MorphOne { }

// Relation for uploads where extension or type is in the accepted document mimes
public function documents(): MorphMany { }

IMPORTANT

MorphOne relation method sets a limit of one in the query.

Lifecycle and Events

During the entire process of uploading your files, events are being fired in each step. This comes very helpful if you need to do something in between these steps or just for debugging purposes.

Event	When It Is Fired	What The Event Receives When Dispatched
`NadLambino\Uploadable\Events\BeforeUpload::class`	Fired before the upload process starts	`Model $uploadable`, `array $files`, `UploadOptions $options`
`NadLambino\Uploadable\Events\StartUpload::class`	Fired when the upload process has started and its about to upload the first file in the list. This event may fired up multiple times depending on the number of files that is being uploaded	`Model $uploadable`, `string $filename`, `string $path`
`NadLambino\Uploadable\Events\AfterUpload::class`	Fired when the file was successfully uploaded and file information has been stored in the `uploads` table. This event may fired up multiple times depending on the number of files that is being uploaded	`Model $uploadable`, `Upload $upload`
`NadLambino\Uploadable\Events\CompleteUpload::class`	Fired when all of the files are uploaded and all of the necessary clean ups has been made	`Model $uploadable`, `Collection $uploads`
`NadLambino\Uploadable\Events\FailedUpload::class`	Fired when an exception was thrown while trying to upload a specific file.	`Throwable $exception`, `Model $uploadable`

If you want to do something before the file information is stored to the uploads table, you can define the beforeSavingUpload public method in your model. This method will be called after the file is uploaded in the storage and before the file information is saved in the database.

public function beforeSavingUpload(Upload $upload, Model $model) : void
{
    $upload->additional_field = "some value";
}

Alternatively, you can statically call the beforeSavingUploadUsing method and pass a closure.
The closure will receive the same parameters as the beforeSavingUpload method.
Just make sure that you call this method before creating or updating the uploadable model.
Also, beforeSavingUploadUsing has the higher precedence than the beforeSavingUpload allowing you to override it when needed.

Post::beforeSavingUploadUsing(function (Upload $upload, Post $model) use ($value) {
    $model->additional_field = $value;
});

$post->save();

IMPORTANT

Remember, when you're on a queue, you are actually running your upload process in a different
application instance so you don't have access to the current application state like the request object.
Also, make sure that the closure and its dependencies you passed to the beforeSavingUploadUsing method are serializable.

Queueing

You can queue the file upload process by defining the queue name in the config.

'upload_on_queue' => null,

Alternatively, you can also call the static method uploadOnQueue.

Post::uploadOnQueue('default');

$post->save();

DI Container: What is it and how to create one

Nad Lambino — Fri, 01 Sep 2023 11:53:35 +0000

Have you ever wondered how does Laravel provide us an instance of a class that we’re injecting on our controllers? Whether it’s an interface, an abstract class, or a concrete class. It feels like a lot of magic is happening, right? Well, it’s all because of Dependency Injection Container.

If you don’t have any idea yet about dependency injection, you can read my article about SOLID Principle with Laravel and go to the last section which is about dependency injection.

Basically, Dependency Injection Container is an object that knows how to instantiate an object and configure all of its dependencies. Whenever we try to inject a class into a controller’s constructor or its method, Laravel’s DI Container tries to resolve and create this object for us, including all of its dependencies. Laravel, as a powerful framework is not just limited to resolving concrete classes but also has a lot of features, such as binding interfaces or abstract classes into concrete class, singleton binding, contextual binding, and many more. In this article, we will try to create our very own DI container with basic functionality, so let's get started.

To create our DI Container, we will be using PHP’s Reflection API. It is a set of built-in classes and functions in PHP that allows us to inspect the structure of classes, methods, properties, and other objects at runtime. Aside from Reflection API, we can also use PSR-11: Container interface — PHP-FIG to have a guide on how we can implement our DI Container. However, I won’t be using it here to keep it short and simple.

Let us first create our Container class and its properties.

<?php

declare(strict_types=1);

class Container
{

  /** Array of [abstract => concrete] bindings */
  private array $bindings = [];

  /** Array of resolved instances */
  private array $resolved = [];

}

In the above code, $bindings property will hold all of our bindings. Such example of binding is whenever we inject a StorageInterface in our controller, we may want it to be an instance of a LocalStorageService or S3StorageService depending on our environment.

<?php

declare(strict_types=1);

class Container
{

  /** ...property declarations here */

  /** Add binding into $bindings array */
  public function bind(string $abstract, string $concrete = null): void
  {
    $concrete = $concrete ?? $abstract;

    if (!class_exists($concrete)) {
      throw new Exception("Non-existing $concrete class");
    }

    $this->bindings[$abstract] = $concrete;
  }
}

/** Example usage */
$container = new Container();
$container->bind(StorageInterface::class, LocalStorageService::class);

/** FileController constructor */
public function __construct(StorageInterface $storage)
{
  /** 
   * Code goes here using the $storage which we expect to be an 
   * instance of LocalStorageService class 
   */
}

Next on our code is the bind method. This method requires a string $abstract class name or interface name that we will inject on our controller, and an optional string $concrete class name that we want to be instantiated when the given abstract class was injected. Note that bind method simply binds a concrete class into an abstract class or interface, it’s not yet resolving or instantiating it.

<?php

declare(strict_types=1);

class Container
{

  /** ...property declarations here */

  /** Add binding into $bindings array */
  public function bind(string $abstract, string $concrete = null): void
  { ... }

  /** Create an instance of the give class */
  public function make(string $abstract, string $concrete = null): mixed
  {
    $concrete = $concrete ?? $abstract;

    if (isset($this->bindings[$abstract])) {
      $class = $this->bindings[$abstract];
    } else {
      $this->bind($abstract, $concrete);
      $class = $concrete;
    }

    /** Don't worry about this method for now */
    return $this->resolve($class);
  }
}

/** Example usage */
$container = new Container();
$container->bind(StorageInterface::class, LocalStorageService::class);

/** Expected to be an instance of LocalStorageService */
$storage = $container->make(StorageInterface::class);

Next method is the make which is responsible for creating an instance of the given abstract or concrete class. If $concrete was not provided, it will use the $abstract parameter as the concrete class. If we already have a binding for this abstract, we will just use its binding, otherwise, we will bind it so that whenever there’s another class or method that is dependent on this abstract along the same request, we can just use this binding. After we get its concrete class, we will then pass it to the resolve method.

<?php

declare(strict_types=1);

class Container
{

  /** ...property declarations here */

  /** Add binding into $bindings array */
  public function bind(string $abstract, string $concrete = null): void
  { ... }

  /** Create an instance of the give class */
  public function make(string $abstract, string $concrete = null): mixed
  { ... }

  /** Resolve the given class and all of its dependencies */
  public function resolve(string $class): mixed
  {
    /** Immediately return a new instance of the class if its already resolved */
    if ($this->resolved[$class]) {
      try {
        return new ($this->resolved[$class]);
      } catch (Throwable) { }
    }

    /** Use ReflectionClass to inspect the given class */
    $reflection = new ReflectionClass($class);
    if (! $reflection->isInstantiable()) {
      throw new Exception("Unable to instantiate a non-instantiable $class");
    }

    /** Create the class constructor and resolve its dependencies */
    $constructor = $reflection->getConstructor();
    $dependencies = $constructor ? $this->resolveDependencies($constructor) : [];

    try {
      /** Return a new instance of the reflected class with its dependencies */
      return $reflection->newInstanceArgs($dependencies);
    } catch (ReflectionException) {
      $dependencyString = implode(', ', $dependencies);
      throw new Exception("Unable to resolve the following dependencies $dependencyString");
    }
  }

  /** 
   * Returns an array of class dependencies 
   * It can be an instantiated class, or the provided default value
   */
  private function resolveDependencies(ReflectionMethod|ReflectionClass $class): array
  {
    $dependencies = [];

    foreach ($class->getParameters() as $param) {
      $type = $param->getType();
      $parameter = $param->getName();

      if ($param->isDefaultValueAvailable()) {
        $dependencies[] = $param->getDefaultValue();
        continue;
      }

      if ($type?->isBuiltin()) {
        throw new Exception("Unable to resolve built in parameter type");
      }

      if ($type === null) {
        throw new Exception("Unable to resolve missing parameter type");
      }

      $name = $type->getName();

      if ($this->resolved[$name]) {
        $dependencies[] = new ($this->resolved[$name]);
        continue;
      }

      $resolved = $this->resolve($name);
      $dependencies[] = $resolved;
      $this->resolved[$name] = $resolved;
    }

    return $dependencies;
  }
}

Lastly, we will have these two methods, resolve and resolveDependencies.

resolve method is the one that is responsible for creating an instance of the given class. If the class was already resolved, it will immediately return that instance. If not, then we will use PHP’s ReflectionClass class to check if it can be instantiated.

Next is to get the constructor of the class from Reflection API. $reflection->getConstructor() returns null when the class doesn’t have a constructor, meaning that it doesn’t have any dependency, so we can just set the $dependencies variable to empty array, otherwise, it returns a ReflectionMethod which we then passed to the resolveDependencies method.

resolveDependencies method is responsible for resolving all of the method’s parameters, in this case, the class constructor. $class->getParameters() returns an array of parameters. We can then inspect each parameter, like its type, name, whether it has default values, get that default value, and check if the type is built in or null if not provided. We can then get the name of its type and use recursion to call the resolve method again to try resolve this parameter.

We now have a working implementation of a DI Container.

<?php

$container = new Container();
$container->bind(StorageInterface::class, LocalStorageService::class);

// Instance of the UploadController injected with LocalStorageService class
$uploadController = $container->make(UploadController::class);

Note that this is a very basic implementation of a DI Container. It does not have a lot of features which is usually offered by powerful frameworks like Laravel. However, I hope that you have learned new things in this article and get the idea of how it works when we use it on our favorite frameworks.

Thank you for reading :)

Database Normalization: Simplifying your tables

Nad Lambino — Fri, 04 Aug 2023 06:48:12 +0000

Database normalization

Is a process in database design that helps eliminate data redundancy and improve data integrity by organizing data into logical and efficient structures. It involves breaking down a database into multiple related tables and defining relationships between them.

The main goals of database normalization are:

Minimized data redundancy: Normalization eliminates data redundancy by ensuring that each piece of data is stored in only one place. This reduces storage space requirements and avoids inconsistencies that can arise from storing redundant data. It also simplifies data maintenance since updates and modifications need to be made in only one location.
Improved data integrity: By organizing data into logical and normalized structures, data integrity is enhanced. Relationships between tables are defined and enforced through constraints, such as primary keys and foreign keys, ensuring the accuracy, consistency, and reliability of data. This reduces the risk of data anomalies and inconsistencies.
Simplified data maintenance: Normalization simplifies the process of modifying and updating data. Since data is stored in smaller, more manageable units, changes made to a particular piece of data only need to be applied in one location. This reduces the chances of introducing errors during data maintenance and ensures consistent updates throughout the database.
Enhanced query efficiency: Normalized databases typically require less complex and faster queries compared to denormalized databases. With well-defined relationships between tables, queries can be written to retrieve and manipulate data more efficiently. This can improve overall performance and response times in database operations.
Facilitated database design: Database normalization provides a systematic approach to database design. It helps designers break down complex data structures into smaller, more manageable tables and define relationships between them. This promotes clarity and organization in the database schema, making it easier to understand, maintain, and extend as the system evolves.
Scalability and flexibility: Normalized databases are generally more scalable and flexible. As new requirements arise or the system grows, it is easier to extend and modify a normalized database schema without impacting the existing data or structure. This adaptability is particularly useful in dynamic and evolving systems.

Forms of Database Normalization

The normalization process involves decomposing a database schema into multiple normalization levels, known as normal forms. The most commonly used normal forms are:

First Normal Form (1NF): Ensures atomicity by eliminating repeating groups and ensuring that each column in a table contains only atomic values.

Second Normal Form (2NF): Builds upon 1NF by eliminating partial dependencies. It involves removing columns that depend on only a portion of the primary key and placing them in separate tables.

Third Normal Form (3NF): Builds upon 2NF by eliminating transitive dependencies. It involves removing columns that depend on non-key attributes and placing them in separate tables.

There are higher normal forms beyond 3NF, such as Boyce-Codd Normal Form (BCNF) and Fourth Normal Form (4NF), which address more complex dependencies. The choice of the appropriate normal form depends on the specific requirements and complexity of the database schema. However, in this article, we will be tackling only the first, second, and third normal form.

Examples

Non-normalized Form

In this non-normalized form, the Books table contains redundancy. The book The Great Gatsby by F. Scott Fitzgerald appears twice, leading to data redundancy and potential inconsistencies. If, for example, the author's name was to be updated, it would need to be modified in multiple places.

1st Normal Form

In this 1NF form, the Books table has been divided into two separate tables: Books and Authors. The Books table now contains a foreign key, author_id, which references the primary key in the Authors table. This eliminates the data redundancy issue, as the author's information is stored in the Authors table only once.

2nd Normal Form

In this 2NF form, the Category column has been moved to a separate Categories table. This eliminates the partial dependency, where the Category column was dependent on the Book ID rather than the primary key of the table.

3rd Normal Form

In this 3NF form, a new table called Book_Author has been introduced to represent the many-to-many relationship between books and authors. This eliminates the transitive dependency, where the relationship between books and authors was indirectly dependent on the primary key of the Books table.

By following 1NF, 2NF, and 3NF, the database is structured with reduced redundancy, improved data integrity, and more flexible and maintainable data management.

Normalization is an essential concept in relational database design and is widely used to improve data organization, efficiency, and integrity. However, it's important to strike a balance between normalization and performance, as excessive normalization can lead to increased complexity in querying and joining tables.

SOLID Principle with Laravel

Nad Lambino — Mon, 31 Jul 2023 01:54:04 +0000

SOLID Principle with Laravel

What is SOLID principle?

The SOLID principles are a set of five design principles that aim to guide developers in creating software systems that are modular, maintainable, and extensible. These principles provide guidelines for writing clean, robust, and flexible code. Each principle focuses on a specific aspect of software design and encourages the separation of concerns, flexibility, and adherence to good coding practices. By following the SOLID principles, developers can build software that is easier to understand, test, and modify, leading to improved quality and long-term sustainability.

Benefits of SOLID principle

Code maintainability: SOLID principles promote clean and organized code, making it easier to understand, modify, and maintain over time.
Code reusability: By adhering to SOLID principles, code becomes modular and loosely coupled, allowing for easier reuse in different parts of the application or in future projects.
Testability: SOLID principles encourage code that is easy to test in isolation, leading to more reliable and effective unit tests.
Flexibility and adaptability: Following SOLID principles results in code that is flexible and can be easily extended or modified to accommodate changing requirements or new features.
Collaboration: SOLID principles make code easier to understand and work with, facilitating better collaboration among team members.
Scalability: SOLID principles help in building scalable systems by enabling the creation of loosely coupled, modular components that can be easily scaled up or down as needed.
Reduced time and cost: Following SOLID principles from the start of a project can save time and reduce costs by minimizing bugs, refactoring needs, and making changes later in the development cycle.

By addressing these areas, the SOLID principles contribute to overall software quality, maintainability, and developer productivity.

Single Responsibility Principle

The Single Responsibility Principle (SRP) states that a class should have only one reason to change. It means that a class should have only one responsibility or job.

In the context of a Laravel application, let's consider a scenario where we have a UserController class that handles user-related operations like creating a new user, updating user information, and sending welcome emails. However, this violates the SRP because the class has multiple responsibilities.

Here's an example that violates the SRP



// UserController.php

class UserController
{
    public function create(Request $request)
    {
        // Validation and user creation logic

        $user = User::create($request->all());

        $this->sendWelcomeEmail($user); // Move this responsibility out of UserController
    }

    private function sendWelcomeEmail(User $user)
    {
        // Code to send the welcome email
    }
}

Here's an example that follows the SRP



// UserController.php

class UserController
{
    public function create(Request $request, EmailService $emailService)
    {
        // Validation and user creation logic

        $user = User::create($request->all());

        // Delegate the responsibility to the EmailService class
        $emailService->sendWelcomeEmail($user);
    }
}



// EmailService.php

class EmailService
{
    public function sendWelcomeEmail(User $user)
    {
        // Code to send the welcome email
    }

    public function sendEmailWithAttachment()
    {
        // Code to send email with attachment
    }
}

In the refactored code, we extract the responsibility of sending a welcome email into a separate EmailService class. This separates the concerns, allowing the UserController to focus solely on user-related operations, while the EmailService class handles email-related tasks. This makes its functions to be reusable on other controllers or service that needs mail related tasks without repeating our code. This adheres to the SRP, as each class now has a single responsibility, making the code more modular, maintainable, and easier to extend or change in the future.

Open-Closed Principle

The Open-Closed Principle (OCP) states that software entities (classes, modules, functions, etc.) should be open for extension but closed for modification. In simple terms, it means that you should be able to add new functionality to a system without modifying its existing code.

Let's consider an example in a Laravel application where we have a PaymentController that handles different payment methods: PayPal and Stripe. Initially, the controller has a switch statement to determine the payment method and perform the corresponding actions.



// PaymentController.php

class PaymentController
{
    public function processPayment(Request $request)
    {
        $paymentMethod = $request->input('payment_method');

        switch ($paymentMethod) {
            case 'paypal':
                $this->processPayPalPayment($request);
                break;
            case 'stripe':
                $this->processStripePayment($request);
                break;
            default:
                // Handle unsupported payment method
                break;
        }
    }

    private function processPayPalPayment(Request $request)
    {
        // Code for processing PayPal payment
    }

    private function processStripePayment(Request $request)
    {
        // Code for processing Stripe payment
    }
}

In the above code, adding a new payment method would require modifying the PaymentController by adding another case to the switch statement. This violates the OCP because we are modifying the existing code instead of extending it.

To adhere to the OCP, we can use a strategy pattern to decouple the payment processing logic from the controller and make it open for extension. Here's an updated version:



// PaymentController.php

class PaymentController
{
    private $paymentProcessor;

    public function __construct(PaymentProcessorInterface $paymentProcessor)
    {
        $this->paymentProcessor = $paymentProcessor;
    }

    public function processPayment(Request $request)
    {
        $this->paymentProcessor->processPayment($request);
    }
}



// PaymentProcessorInterface.php

interface PaymentProcessorInterface
{
    public function processPayment(Request $request);
}



// PayPalPaymentProcessor.php

class PayPalPaymentProcessor implements PaymentProcessorInterface
{
    public function processPayment(Request $request)
    {
        // Code for processing PayPal payment
    }
}



// StripePaymentProcessor.php

class StripePaymentProcessor implements PaymentProcessorInterface
{
    public function processPayment(Request $request)
    {
        // Code for processing Stripe payment
    }
}

Now, to dynamically select the payment processor based on user input, you can leverage Laravel's container and configuration capabilities. Here's an example:



// config/payments.php

return [
    'default' => 'stripe',
    'processors' => [
        'paypal' => PayPalPaymentProcessor::class,
        'stripe' => StripePaymentProcessor::class,
    ],
];



// PaymentServiceProvider.php

use Illuminate\Support\Facades\App;
use Illuminate\Support\ServiceProvider;

class PaymentServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->bind(PaymentProcessorInterface::class, function ($app) {
            $config = $app['config']->get('payments');
            $defaultProcessor = $config['default'];
            $processors = $config['processors'];

            $selectedProcessor = $request->input('payment_method', $defaultProcessor);
            $processorClass = $processors[$selectedProcessor];

            return $app->make($processorClass);
        });
    }
}

Liskov Substitution Principle

The Liskov Substitution Principle (LSP) states that objects of a superclass should be replaceable with objects of its subclasses without affecting the correctness of the program. In simpler terms, it means that subclasses should be able to be used interchangeably with the base class without causing any unexpected behavior.

Let's consider a real-world example where we have a base class called Vehicle and two subclasses called Car and Bicycle. Each of them has a method called startEngine(), which represents starting the engine of the vehicle.

Here's an example that violates the Liskov Substitution Principle:



class Vehicle {
    public function startEngine() {
        // Default implementation for starting the engine
        echo "Engine started!";
    }
}



class Car extends Vehicle {
    public function startEngine() {
        // Implementation specific to starting a car's engine
        echo "Car engine started!";
    }
}



class Bicycle extends Vehicle {
    public function startEngine() {
        // Bicycles don't have engines, so this violates LSP
        throw new Exception("Bicycles don't have engines!");
    }
}

In the above code, the Bicycle class violates the Liskov Substitution Principle because it throws an exception when trying to start the engine. This behavior is unexpected and breaks the principle.

Here's an example that follows the Liskov Substitution Principle:



class Vehicle {
    // Common implementation for all vehicles
    public function startEngine() {
        // Default implementation for starting the engine
        echo "Engine started!";
    }
}



class Car extends Vehicle {
    public function startEngine() {
        // Implementation specific to starting a car's engine
        echo "Car engine started!";
    }
}



class Bicycle extends Vehicle {
    // Bicycles don't have engines, so we don't override the startEngine() method
}

In the above code, the Bicycle class follows the Liskov Substitution Principle by not overriding the startEngine() method. Since bicycles don't have engines, the default implementation from the base class is used, which is acceptable and doesn't introduce unexpected behavior.

By following LSP, you ensure that your code is more maintainable, extensible, and less prone to bugs, as you can safely use objects of subclasses wherever objects of the base class are expected.

Interface Segregation Principle

The Interface Segregation Principle (ISP) states that clients should not be forced to depend on interfaces they do not use. In simpler terms, it means that a class should not be forced to implement methods that it doesn't need.

Let's consider a real-world example of an online store application built with Laravel.

Violating the Interface Segregation Principle:



interface PaymentGatewayInterface {
    public function processPayment($amount);
    public function refundPayment($transactionId);
    public function voidPayment($transactionId);
}



class PaymentGateway implements PaymentGatewayInterface {
    public function processPayment($amount) {
        // Process payment logic
    }

    public function refundPayment($transactionId) {
        // Refund payment logic
    }

    public function voidPayment($transactionId) {
        // Void payment logic
    }
}



class EcommerceService {
    private $paymentGateway;

    public function __construct(PaymentGatewayInterface $paymentGateway) {
        $this->paymentGateway = $paymentGateway;
    }

    public function processOrder($order) {
        // Process order logic

        $this->paymentGateway->processPayment($order->totalAmount);
    }

    public function refundOrder($order) {
        // Refund order logic

        $this->paymentGateway->refundPayment($order->transactionId);
    }

    public function voidOrder($order) {
        // Void order logic

        $this->paymentGateway->voidPayment($order->transactionId);
    }
}

In this example, the PaymentGatewayInterface defines three methods: processPayment(), refundPayment(), and voidPayment(). However, in the EcommerceService class, we only need to use the processPayment() method to handle payment-related operations. The refundPayment() and voidPayment() methods are not relevant to the EcommerceService, but we're still forced to depend on them because the interface enforces their implementation.

Here's a modified version that follows the ISP:



interface PaymentProcessorInterface {
    public function processPayment($amount);
}



interface RefundableInterface {
    public function refundPayment($transactionId);
}



interface VoidableInterface {
    public function voidPayment($transactionId);
}



class PaymentGateway implements PaymentProcessorInterface, RefundableInterface, VoidableInterface {
    public function processPayment($amount) {
        // Process payment logic
    }

    public function refundPayment($transactionId) {
        // Refund payment logic
    }

    public function voidPayment($transactionId) {
        // Void payment logic
    }
}



class EcommerceService {
    private $paymentProcessor;

    public function __construct(PaymentProcessorInterface $paymentProcessor) {
        $this->paymentProcessor = $paymentProcessor;
    }

    public function processOrder($order) {
        // Process order logic

        $this->paymentProcessor->processPayment($order->totalAmount);
    }
}

In this updated example, the PaymentProcessorInterface defines only the processPayment() method, which is the only method needed by the EcommerceService. The RefundableInterface and VoidableInterface are created for other classes that require those specific functionalities. By separating the interfaces, we adhere to the ISP by allowing clients to depend only on the interfaces they actually need.

This adherence to the ISP improves the codebase's maintainability, reduces unnecessary dependencies, and makes it easier for entry-level developers to understand and work with the code.

Dependency Inversion Principle

The Dependency Inversion Principle (DIP) states that high-level modules should not depend on low-level modules, but both should depend on abstractions. In other words, instead of depending on specific implementations, modules should rely on interfaces or abstract classes.

Code Sample Violating DIP in Laravel using the Storage Facade:



class UserController extends Controller
{
    public function store(Request $request)
    {
        $avatar = $request->file('avatar');

        // Violation: The UserController depends directly on the Storage facade.
        // This makes it tightly coupled to the Laravel's file storage implementation.
        $path = Storage::disk('local')->put('avatars', $avatar);

        // ...
    }
}

The UserController class relies on the Storage facade and calls its disk and put methods directly. By depending on the Storage facade directly, the UserController is tightly coupled to the specific file storage system implemented by Laravel, making it harder to switch to a different storage mechanism without modifying the UserController code.

Code Sample Following DIP in Laravel using the Storage Service:



interface FileStorage
{
    public function storeFile($directory, $file);
}



class LocalFileStorage implements FileStorage
{
    public function storeFile($directory, $file)
    {
        return Storage::disk('local')->put($directory, $file);
    }
}



class S3FileStorage implements FileStorage
{
    public function storeFile($directory, $file)
    {
        return Storage::disk('s3')->put($directory, $file);
    }
}



class UserController extends Controller
{
    private $fileStorage;

    public function __construct(FileStorage $fileStorage)
    {
        $this->fileStorage = $fileStorage;
    }

    public function store(Request $request)
    {
        $avatar = $request->file('avatar');

        // The UserController depends on the FileStorage abstraction, which can be
        // implemented using different storage systems.
        $path = $this->fileStorage->storeFile('avatars', $avatar);

        // ...
    }
}

The UserController class now depends on the FileStorage interface instead of directly relying on the Storage facade or a specific implementation. This interface serves as an abstraction that defines the contract for file storage operations.

The S3FileStorage class implements the FileStorage interface and provides the concrete implementation for storing files in AWS S3. By injecting the FileStorage interface into the UserController constructor, the controller is decoupled from the specific storage mechanism and depends only on the abstraction.
This adherence to the Dependency Inversion Principle allows for easier interchangeability of storage implementations. You can easily introduce new implementations of the FileStorage interface (e.g., a LocalFileStorage class) without modifying the UserController code. The choice of storage mechanism can be determined at runtime or through configuration (.env file), providing flexibility and maintainability.

Conclusion:

The SOLID principles are guidelines for writing clean and maintainable code. While they offer numerous benefits, they should not be seen as rigid rules that must always be followed without exception. It's crucial to strike a balance between applying the SOLID principles and considering other factors such as project complexity.

Thank you for reading.

How I structure my CSS

Nad Lambino — Fri, 14 Jul 2023 06:42:33 +0000

When doing CSS, I always recommend doing it with mobile-first approach. This way, we can ensure that we cover each breakpoint for better responsiveness.

// default or mobile devices (up to 719px)
.heading {
  font-size: 14px;
  padding: 10px;
}

// tablet devices (720px up to 991px)
@media screen and (min-width: 720px) and (max-width: 991px) {
  .heading {
    font-size: 18px;
    padding: 20px;
  }
}

// small screen desktop devices (992px up to 1023px)
@media screen and (min-width: 992px) and (max-width: 1023px) {
  .heading {
    font-size: 18px;
    padding: 30px;
  }
}

// large screen desktop devices (1024px up to 1920px or more)
@media screen and (min-width: 1024px) {
  .heading {
    font-size: 18px;
    padding: 40px;
  }
}

With this approach, we can be sure that all of the devices' screen sizes were covered. Also, we do not have to put the !important keyword because we know that none of our styles are overlapping, unless if it was overwritten from another CSS file.

However, there is still one issue that may occur from this. As we can see, we defined our .heading class multiple times. If we have a small CSS file, this isn't going to be a problem. But once our CSS file started to contain too many styles for our application, it will be harder for us to track from which of this declaration is for mobile, tablets, small desktops, and large desktops. We have to scroll and scroll just to find the right declaration where we want to do some changes or additions. This could slow us down and sometimes causes frustration.

To resolve this issue, we can improve this approach with the help of SCSS. One of the features of SCSS, is that we are allowed to nest our styles.

.heading {
  // default or mobile devices (up to 719px)
  font-size: 14px;
  padding: 10px;

  // tablet devices (720px up to 991px)
  @media screen and (min-width: 720px) and (max-width: 991px) {
    font-size: 18px;
    padding: 20px;
  }

  // small screen desktop devices (992px up to 1023px)
  @media screen and (min-width: 992px) and (max-width: 1023px) {
    font-size: 18px;
    padding: 30px;
  }

  // large screen desktop devices (1024px up to 1920px or more)
  @media screen and (min-width: 1024px) {
    font-size: 18px;
    padding: 40px;
  }
}

Now, all of our styles for the .heading class for different screen sizes were defined under a single declaration. It is now more predictable, readable, and scalable.

Implementation with Tailwind using the `@apply` directive

One of the misuses of tailwind is directly using tailwind classes into html or template files. This makes our html code messy and crowded with bunch of classes. The more it goes like this, the harder it is to read and maintain our codebase. One solution is to use the @apply directive provided by tailwind. With this, we can apply tailwind classes in a single class, and use that class in our html elements.

Here’s an example on how to use it and keep the mobile-first pattern implemented.

.heading {
  // default or mobile devices
  @apply text-sm p-[10px];

  // medium size screen
  @apply md:text-base md:p-[20px];

  // large size screen
  @apply lg:text-lg lg:p-[30px];

  // extra large size screen
  @apply xl:text-xl xl:p-[40px];
}

And that's it for today. I hope you learned something from what we've discussed. Thank you for your support :)

Forem: Nad Lambino

Handling File Uploads in Laravel, Automatically.

Table of Contents

Installation

Usage

Customizing the Rules and Messages

Customizing the file name and upload path

Uploading Files with Custom Options for the Storage

Manually processing file uploads

Temporarily Disable the File Upload Process

Caveat

Uploading files on model update

Uploading files that are NOT from the request

Relation methods

Lifecycle and Events

Queueing

DI Container: What is it and how to create one

Database Normalization: Simplifying your tables

Database normalization

SOLID Principle with Laravel

SOLID Principle with Laravel

Single Responsibility Principle

Open-Closed Principle

Liskov Substitution Principle

Interface Segregation Principle

Dependency Inversion Principle

Conclusion:

How I structure my CSS

Implementation with Tailwind using the @apply directive

Implementation with Tailwind using the `@apply` directive