DEV Community: Jack Miras

Tinker in Lumen: Your Ultimate Debugging Companion

Jack Miras — Mon, 06 Nov 2023 15:32:03 +0000

When working with Lumen applications, every developer anticipates that the framework will have fewer native features when compared with Laravel. Different from its counterpart, which is intended to build full-featured applications, Lumen is intended for building smaller, faster microservices and lightweight APIs.

One thing not present in Lumen that I find hard to work without is a REPL. Even though the framework has fewer features than Laravel, it still offers database, cache, events, ques, and so on, but believe it or not, Lumen doesn't offer a REPL out of the box.

Fortunately for us, the process of making a REPL available to a Lumen application is not complex, and we can achieve it with a few steps.

Content

What is a REPL?
Require dependency
Define service provider
Run the tinker command

What is a REPL?

Before we start, let's explore what a REPL is. The acronym stands for Read-Eval-Print Loop and allows developers to enter commands or code snippets, which are then read, evaluated, and have their results printed back to the developer. This loop continues, making it an excellent tool for quickly experimenting with code, testing small pieces of code, and learning new programming languages or libraries.

Tinker is a REPL built over psysh which is a general-purpose REPL for PHP. Since a Laravel application is not plain PHP and has states, databases, caches, events, and many more complex resources specific to the framework, it's not possible to interact with the application the way one would expect just using psysh.

And that's where Tinker comes into play, since it's a psysh integration that implements all the specifics necessary for a developer to interact with Laravel in a REPL manner, no matter the resource or feature of the framework being accessed in the REPL.

If you are new to Lumen, you might wonder: Since Tinker is a Laravel REPL, why are we looking into it for a Lumen application since they are entirely different frameworks? Well, you are right; as the Lumen documentation states, they are in fact two different frameworks with intentional incompatibilities with libraries. However, Lumen was born out of Laravel, and it shares some of its foundations with its older sibling, which in some cases means we can use Laravel dependencies in Lumen, and Tinker is one of them.

Require dependency

Now that we have an understanding of a REPL and Tinker's foundations, let's, as a first step, add Tinker as a dependency to our project. Below is the command you have to run to add Tinker as a development dependency to Lumen.

composer require --dev laravel/tinker

Define service provider

The Tinker dependency was added to the project; the next step is to register Tinker's service provider at bootstrap/app.php. In Lumen, you typically register service providers in the bootstrap/app.php file to enable various functionalities within your application.

A service provider is a way to bind classes into the service container, configure services, and perform other setup tasks. Registering Tinker's service provider in the bootstrap/app.php file is necessary to integrate the Tinker REPL into your Lumen application. By registering its service provider, you're telling Lumen to make Tinker's REPL available to you when you run the php artisan tinker command.

$app->register(Laravel\Tinker\TinkerServiceProvider::class);

Run the tinker command

Once the service provider is registered and Lumen has made Tinker's REPL available, you can run php artisan tinker and interact with any Lumen component you need.

Now your Lumen application has a REPL configured for it.

Happy coding!

Python – AWS Secrets Manager: Remote env vars

Jack Miras — Thu, 18 May 2023 14:33:43 +0000

Environment variables play a crucial role in configuring and customizing software applications. They allow developers to store sensitive information securely and adjust the behavior of their code without modifying the underlying source files. In Python, retrieving environment variables is typically a straightforward process.

However, when dealing with remote environments or secrets management, the process can become more complex. This article presents a way to retrieve environment variables, with a particular focus on integrating with AWS Secrets Manager.

Content

Code to be discussed
The env function
The get_env function
The remote_environment_variable function
Usage examples

Code to be discussed

The code provided down below consists of three main functions: env, get_env, and remote_environment_variable, read carefully each function's implementation, try to understand its purpose and its role in retrieving environment variables.

import json
import os
from base64 import b64decode

from botocore.exceptions import (ClientError, NoCredentialsError,
                                 ParamValidationError)

from configs import aws
from configs.logging import logger

"""
Retrieves the value of an env variable from a remote source or a .env file.

:type key: str
:type default_value: str
:return: str
"""


def env(key: str, default_value: str = ""):
    value = get_env(key, default_value)

    if value.lower() == "true":
        return True
    if value.lower() == "false":
        return False

    return value


"""
Retrieves env variable from .env and AWS Secrets Manager, giving precedence to
remote value. If both sources exist, the remote value is returned; otherwise,
.env value or default_value is used.

:type key: str
:type default_value: str
:return: str
"""


def get_env(key: str, default_value: str = "") -> str:
    local_value = str(os.getenv(key, default_value))
    remote_value = str(remote_environment_variable(key))
    return remote_value if remote_value else local_value


"""
Retrieves env variable from AWS Secrets Manager.

:type key: str
:return: str
"""


def remote_environment_variable(key: str) -> str:
    secret_id = os.getenv("AWS_SECRETS_MANAGER_SECRET_ID")

    if not secret_id:
        return ""

    try:
        response = aws.secrets_manager.get_secret_value(SecretId=secret_id)
    except (ClientError, NoCredentialsError, ParamValidationError) as error:
        if isinstance(error, (NoCredentialsError, ParamValidationError)):
            logger.debug("AWS Secrets Manager: %s", error)
        else:
            message = f"{error.response['Error']['Code']} to secret"
            logger.error(f"{message} {secret_id}: {error}")

        return ""

    if "SecretString" in response:
        secret_dictionary = json.loads(response["SecretString"])
    else:
        secret_dictionary = json.loads(b64decode(response["SecretBinary"]))

    return secret_dictionary.get(key)

Now, that the code has been read, let's explore the code in detail.

The env function

This function is designed to retrieve the value of an environment variable from a remote source or a .env file. It provides a practical interface for accessing environment variables, with additional handling for boolean values. By utilizing the get_env function internally, it ensures consistent retrieval of variables from the appropriate source.

def env(key: str, default_value: str = "") -> str:
    value = get_env(key, default_value)

    if value.lower() == "true":
        return True
    if value.lower() == "false":
        return False

    return value

The env function takes two parameters: key, which represents the name of the environment variable to retrieve, and an optional default_value that is used if the variable is not found.

Within the function, it calls the get_env function, passing the key and default_value parameters. The return value is assigned to the value variable.

To provide additional flexibility, the function checks if the retrieved value is either “true” or “false”. If the value is “true” (case-insensitive), it returns a boolean True. If the value is “false” (case-insensitive), it returns a boolean False. This allows for more practical handling of boolean environment variables.

If the value is not a boolean, the function returns the original value as a string.

Overall, the env function simplifies the retrieval of environment variables by utilizing the get_env function internally and providing a consistent and flexible interface for accessing and interpreting their values.

The get_env function

This function serves as a central piece in retrieving environment variables. It handles the logic to fetch variables from either a local .env file or AWS Secrets Manager. It gives precedence to remote values when available, and falls back to local values or default values if necessary.

def get_env(key: str, default_value: str = "") -> str:
    local_value = str(os.getenv(key, default_value))
    remote_value = str(remote_environment_variable(key))
    return remote_value if remote_value else local_value

The get_env function is responsible for retrieving the environment variable from either the local .env file or AWS Secrets Manager.

Within the function, it first attempts to retrieve the value from the local environment using os.getenv(key, default_value). The os.getenv() function retrieves the value of the environment variable with the provided key. The retrieved value, whether from the environment or the default value, is then converted to a string using the str() function and stored in the local_value variable.

Next, the function calls the remote_environment_variable(key) function, which retrieves the value from AWS Secrets Manager. The result is stored in the remote_value variable, also converted to a string representation.

Finally, the function returns the remote_value if it exists (i.e., is not an empty string) or falls back to the local_value if the remote value is not available. This ensures that the function gives precedence to the remote value when both sources exist.

In summary, the get_env function provides a unified approach to retrieve environment variables, combining values from a local .env file and AWS Secrets Manager. It prioritizes remote values when available, offering flexibility and consistency in handling environment variable retrieval.

The remote_environment_variable function

This function is responsible for retrieving environment variables from AWS Secrets Manager. It uses the AWS_SECRETS_MANAGER_SECRET_ID environment variable to identify the secret in AWS Secrets Manager and fetches the corresponding value.

def remote_environment_variable(key: str) -> str:
    secret_id = os.getenv("AWS_SECRETS_MANAGER_SECRET_ID")

    if not secret_id:
        return ""

    try:
        response = aws.secrets_manager.get_secret_value(SecretId=secret_id)
    except (ClientError, NoCredentialsError, ParamValidationError) as error:
        if isinstance(error, (NoCredentialsError, ParamValidationError)):
            logger.debug("AWS Secrets Manager: %s", error)
        else:
            message = f"{error.response['Error']['Code']} to secret"
            logger.error(f"{message} {secret_id}: {error}")

        return ""

    if "SecretString" in response:
        secret_dictionary = json.loads(response["SecretString"])
    else:
        secret_dictionary = json.loads(b64decode(response["SecretBinary"]))

    return secret_dictionary.get(key)

The remote_environment_variable function retrieves the value of an environment variable from AWS Secrets Manager. It takes one parameter, key, which represents the name of the environment variable to retrieve.

First, the function retrieves the value of the AWS_SECRETS_MANAGER_SECRET_ID environment variable using os.getenv(). This value represents the ID of the secret in AWS Secrets Manager that contains all the desired environment variables stored as a JSON.

If the secret_id is not found or empty, indicating that the required environment variable is not available, the function returns an empty string.

Next, the function attempts to fetch the secret value using the aws.secrets_manager.get_secret_value() method, passing the SecretId parameter with the retrieved secret_id. Any potential exceptions, such as ClientError, NoCredentialsError, or ParamValidationError, are caught and handled within the except block.

If the retrieval is successful, the function checks if the response contains a “SecretString” key. If present, it assumes the secret value is in string format and parses it using json.loads(), storing the resulting dictionary in the secret_dictionary variable. Otherwise, if the response contains a “SecretBinary” key, it assumes the secret value is in base64-encoded binary format and decodes it using b64decode() before parsing it as a dictionary.

Finally, the function attempts to retrieve the value associated with the provided key from the secret_dictionary using the get() method. If the key is found in the dictionary, the corresponding value is returned. If not found, None is returned.

In summary, the remote_environment_variable function provides a way to retrieve environment variables from AWS Secrets Manager by utilizing the AWS_SECRETS_MANAGER_SECRET_ID environment variable to identify the secret. It handles potential errors and exceptions during the retrieval process, ensuring robustness and reliable access to sensitive configuration values.

Usage examples

This function demonstrates the usage of the env function in different scenarios.

from example_module import env

def example_function():
    # Example 1
    database_url = env('DATABASE_URL')
    print(f"The database URL is: {database_url}")

    # Example 2
    api_key = env('API_KEY', default_value='DEFAULT_API_KEY')
    print(f"The API key is: {api_key}")

    # Example 3
    debug_mode = env('DEBUG_MODE')
    if debug_mode:
        print("Debug mode is enabled.")
    else:
        print("Debug mode is disabled.")

In the first example it's possible to see a basic environment variable retrieval, it retrieves the value of the 'DATABASE_URL' environment variable and prints it. In the second example, retrieves the value of the 'API_KEY' environment variable with a default value and prints it. The third and last example handles boolean environment variables, it retrieves the value of the 'DEBUG_MODE' environment variable as a boolean and prints the debug mode status accordingly.

Final thoughts

Using this approach combined with the appropriated AWS EC2 ↔ AWS IAM configuration, it’s possible to centralize all environment variables into AWS Secrets Manager, eliminating the need to deal with an .env file during the deployment.

Therefore, this solution presents two upsides to the application lifecycle; 1) simplification of the deployment due to the elimination of the .env file outside the local environment; 2) better security since you can establish IAM access polices in a way that just specific members of the team can add and modify the Secrets Manager entries.

I'm Jack Miras, a Brazilian engineer who works mostly with infrastructure and backend development, for more of my stuff click here.

Happy coding!

Python – A guide to AWS integration

Jack Miras — Thu, 18 May 2023 14:12:37 +0000

When working with the Amazon Web Services (AWS) platform, it's essential to understand how to interact with various services using the AWS SDK for Python (Boto3). In this guide, we'll explore three key components: Why to keep this code in an isolated module, AWS Session, S3 Client, and Secrets Manager Client. We'll discuss their functionalities and demonstrate how to use them.

Content

Keep the code in an isolated module
AWS Session
S3 Client
Secrets Manager Client
Final thoughts

Keep the code in an isolated module

When working with AWS services and Boto3, it's typically beneficial to keep the code in an isolated Python module. Here are some advantages of adopting this practice:

Modularity: Isolating the AWS-related code into a separate module promotes modularity and separation of concerns. It allows you to organize your codebase better and makes it easier to maintain and understand.
Reusability: By keeping the code in a dedicated module, you can reuse it across multiple projects or components within a larger application. This saves time and effort by avoiding code duplication.
Encapsulation: Isolating the AWS code into a module provides encapsulation, ensuring that the AWS-related configurations and credentials are kept separate from the rest of the application code. This helps maintain a clean and secure codebase.
Testability: An isolated module can be easily unit tested to verify its functionality independently of the rest of the application. This promotes better testing practices and improves overall code quality.
Scalability: When your application grows and requires interaction with more AWS services, having an isolated module allows you to easily extend and add new functionality without affecting other parts of the codebase.

By following the practice of isolating AWS-related code into an independent module, you can reap these benefits and create more robust and maintainable applications on the AWS platform.

AWS Session

The AWS Session is a crucial element that manages the state and configuration for interacting with AWS services. It encapsulates information such as credentials, regions, and profiles. To create an AWS Session using Boto3, we start by defining the session arguments, which include the region name, AWS access key ID, and AWS secret access key. These values can be retrieved from environment variables for security and flexibility. Then, we create the session using the provided arguments. Here's an example:

import os

import boto3

"""
---------------------------------------------------------------------------
AWS session
--------------------------------------------------------------------------

Client session that manages state about a particular configuration/account.
Sessions typically store credentials, AWS regions, and other configurations
related to a given profile.

"""

session_args = {}

region_name = os.getenv("AWS_DEFAULT_REGION")
aws_access_key_id = os.getenv("AWS_ACCESS_KEY_ID")
aws_secret_access_key = os.getenv("AWS_SECRET_ACCESS_KEY")

if not region_name and not aws_access_key_id and not aws_secret_access_key:
    session_args = {
        "region_name": region_name,
        "aws_access_key_id": aws_access_key_id,
        "aws_secret_access_key": aws_secret_access_key,
    }

session = boto3.Session(**session_args)

By establishing an AWS Session, we ensure that subsequent interactions with AWS services use the provided credentials and configurations.

S3 Client

The S3 Client is an essential component for working with Amazon Simple Storage Service (S3), which is a scalable object storage service offered by AWS. The S3 Client allows you to perform operations such as creating buckets, uploading files, listing objects, and more. To create an S3 Client, we can utilize the AWS Session we established earlier. Here's an example:

"""
---------------------------------------------------------------------------
S3 Client
--------------------------------------------------------------------------

Amazon Simple Storage Service (Amazon S3) is an object storage service.

"""

s3 = session.resource("s3")

Now, you can use the s3 object to interact with your S3 resources and perform various operations as needed.

Secrets Manager Client

AWS Secrets Manager is a service that helps you securely store and manage secrets such as database credentials, API keys, and other sensitive information. To work with Secrets Manager, we create a Secrets Manager Client using the AWS Session. This client allows us to retrieve and manage secrets throughout their lifecycles. Here's an example:

"""
---------------------------------------------------------------------------
Secrets Manager Client
--------------------------------------------------------------------------


AWS Secrets Manager is service to, retrieve, and rotate database credentials,
API keys, and other secrets throughout their lifecycles.

"""

secrets_manager = session.client("secretsmanager")

With the secrets_manager object, you can call various methods to retrieve secrets, create new secrets, update existing secrets, and more, depending on your requirements.

Final thoughts

Understanding the AWS Session, S3 Client, and Secrets Manager Client is essential for building powerful and secure applications on the AWS platform. In this guide, we explored the functionalities of these components and demonstrated how to create them using Boto3. By leveraging these tools, you can effectively interact with AWS services, manage object storage with S3, and securely handle secrets using Secrets Manager.

By harnessing the power of Boto3 and these AWS components, you can unlock the full potential of AWS services within your applications. Experiment with the provided code examples and explore the comprehensive Boto3 documentation to dive deeper into the capabilities of these components and build robust AWS integrations with ease.

I'm Jack Miras, a Brazilian engineer who works mostly with infrastructure and backend development, for more of my stuff click here.

Happy coding!

Python – Dynamically accessing object properties

Jack Miras — Thu, 04 May 2023 04:11:09 +0000

After coding Python for quite some time, today I needed to do something that should be pretty straightforward, but it took almost half an hour to figure it out, and the result wasn’t as expected.

Content

A simple problem
What about production?
Light at the end of the tunnel

A simple problem

The problem presented itself when it was necessary to dynamically set a log level to a database connection based on an environment variable. As ORM, the project uses peewee which allows us to leverage Python’s standard logging lib to intercept a peewee log stream and do some manipulation such as changing the log level of the stream.

According to the peewee’s doc, when in need to print all queries to the stderr, we just need to implement the following.

import logging

logger = logging.getLogger('peewee')
logger.addHandler(logging.StreamHandler())
logger.setLevel(logging.DEBUG)

What about production?

Once I read the code I thought “When deploying this to production another log level, such as ERROR, would be more appropriated to avoid showing unnecessary information from the database”.

It’s important to carefully set up your logs to keep the application security risks to a minimum, since a log level with too much information can expose the database’s structure and sensitive data.

Light at the end of the tunnel

The approach chosen to solve this was to add an environment variable to the .env file called DB_LOG_LEVEL, that way the application could vary between DEBUG and ERROR levels of log based on the environment.

Next, we need a way to apply some metaprogramming to dynamically call logging.DEBUG, since the log level the application is taking as the truth comes from env("DB_LOG_LEVEL").

For that, we can use the built-in getattr(…) function, that would return the value of the named attribute of an object, where the name must be a string. With knowledge of this function, let's see how our code would look like now.

import logging
from os import getenv

level = getenv("DB_LOG_LEVEL", "DEBUG")

logger = logging.getLogger("peewee")
logger.addHandler(logging.StreamHandler())
logger.setLevel(getattr(logging, level))

I also added a validation that checks if the value returned by the getenv(...) function matches the log levels present in the logging library, which presents the following implementation.

import logging
from os import getenv

"""
---------------------------------------------------------------------------
 Database logging
--------------------------------------------------------------------------

Database logging will define when and how log info will be shown while
interacting with the database. Accepted log levels are CRITICAL, ERROR,
WARNING, INFO, DEBUG and NOTSET.
"""


LOG_LEVELS = [
    "CRITICAL",
    "FATAL",
    "ERROR",
    "WARNING",
    "WARN",
    "INFO",
    "DEBUG",
    "NOTSET",
]

LOG_LEVEL = getenv("DB_LOG_LEVEL", "DEBUG")

if LOG_LEVEL not in LOG_LEVELS:
    raise Exception(f"DatabaseLogError: Log level '{LOG_LEVEL}' not defined")

logger = logging.getLogger("peewee")
logger.addHandler(logging.StreamHandler())
logger.setLevel(getattr(logging, LOG_LEVEL))
logging.DEBUG

Using metaprogramming to solve this problem, allows us to dynamically access a property of the object logging to pass a valid log level into the logger.setLevel(...) function.

I'm Jack Miras, a Brazilian engineer who works mostly with infrastructure and backend development, for more of my stuff click here.

Happy coding!

Laravel: Delete Actions Simplified

Jack Miras — Wed, 13 Jul 2022 00:52:51 +0000

In my last publishing, I've mentioned controller operations that are frequently duplicated and how we could leverage what we've learned so far to make those operations simpler to use. Now, I would like to discuss another controller operation that frequently gets duplicated as well, and that is the delete operation.

Content

Conventional way
Shortening it
The deleteOrFail function
Abstracting it
- Trait abstraction
- The model function
- The deleteOrThrow function
- Custom exception
- Using the abstraction
- Implementing it

Conventional way

Before we jump into the simplification, let’s take a look at how a delete operation looks like when conventionally implemented.

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class UsersController extends Controller
{
    public function destroy(Request $request): Response
    {
        $user = User::find($request->id);

        if ($user === null) {
            return response(
                "User with id {$request->id} not found",
                Response::HTTP_NOT_FOUND
            );
        }

        if ($user->delete() === false) {
            return response(
                "Couldn't delete the user with id {$request->id}",
                Response::HTTP_BAD_REQUEST
            );
        }

        return response(["id" => $request->id, "deleted" => true], Response::HTTP_OK);
    }
}

On the first line, we are querying a user by its ID and storing the result in the $user object.

Then, at the first conditional, we check if the $user is null; if it is, it means that no record with the given ID got found, and an error message with status 404 will be returned.

Thereafter, we have a second conditional where we call $user->delete() this function returns true or false to let us know if the data got successfully deleted. In the event it returns false, an error message with status 400 will be returned.

Finally, if the user got correctly deleted, we render a response with the user's id and a property deleted with the value true.

Shortening it

Why not use the findOrFail() helper function to shorten our code? When using this approach, it would remove at least five lines from the destroy action of our controller, as shown in the code example down below.

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class UsersController extends Controller
{
    public function destroy(Request $request): Response
    {
        $user = User::findOrFail($request->id);

        if ($user->delete() === false) {
            return response(
                "Couldn't delete the user with id {$request->id}",
                Response::HTTP_BAD_REQUEST
            );
        }

        return response(["id" => $request->id, "deleted" => true], Response::HTTP_OK);
    }
}

On the first line, we are querying a user by its ID using the findOrFail() function. This function has a special behavior where an exception gets thrown in case the data for the given ID doesn't get found.

To make the most of this change, we need to know how to automate the handling of the exception thrown by the findOrFail(). Otherwise, it would be necessary to use a try/catch block, and the number of lines would be just about the same.

As in the previous example, we have a conditional where we are calling $user->delete() into the user that we want to delete. In the event it returns false, an error message with status 400 will be returned.

Same as before, if the user was deleted, we render its id and the property deleted with the value true.

The deleteOrFail function

NOTE: This function will only be available if you are using Laravel on version 8.58.0 or newer.

Now that we’ve seen two different ways of implementing the delete action on Laravel, let’s see how we can implement this using the deleteOrFail() function.

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class Users extends Controller
{
    public function destroy(Request $request): Response
    {
        $user = User::findOrFail($request->id);

        if ($user->deleteOrFail() === false) {
            return response(
                "Couldn't delete the user with id {$request->id}",
                Response::HTTP_BAD_REQUEST
            );
        }

        return response(["id" => $request->id, "deleted" => true], Response::HTTP_OK);
    }
}

As before, we are querying a user by its ID using the findOrFail() function.

Next, we have a second conditional where we call $user->deleteOrFail() this function returns true or false to let us know if the data got successfully deleted. In the event it returns false, an error message with status 400 will be returned.

Once more, if the user got correctly deleted, we render its id and deleted as with the value true.

NOTE: Notice that the deleteOrFail() check if the model itself exists, open a database connection, then a transaction and call the delete() function, and the resultant usage is exactly the same as the one presented in the previous section.

This is a very odd implementation in the framework, since most of the *orFail() functions usually throw an exception. If that was the case, we could just automate the handling of the exception thrown by the deleteOrFail() function the same way we did in the last post in my series about exceptions.

If we had a standard *orFail() function, this function would be the simplest way of implementing a destroy action in a controller, completely removing the need for the approach that will be explained in the next section.

Abstracting it

Let’s see how we can abstract this implementation in such a way that we get high reusability with simple usage out of this abstraction.

Since this abstraction interacts with models, I wanted to avoid using inheritance because it would be a coupling too high for an abstraction as simple as this one.

Furthermore, I want to leave the inheritance in the models open for usage, whether by a team member's decision or by some specific use case.

For that reason, I’ve chosen to implement the abstraction as a Trait. Differently from C++, where we can use multiple inheritance, in PHP, a Trait is the mechanism to reduce limitations around single inheritance.

Besides that, I have a personal rule where I use Traits only when an implementation gets highly reused, since a good portion of my controllers end up having a destroy action. In my context, this is something highly reused.

Trait abstraction

<?php

namespace App\Helpers;

use Illuminate\Database\Eloquent\Model;
use App\Exceptions\ModelDeletionException;

trait DeleteOrThrow
{
    /**
     * Instantiate a new model instance from the model implementing this trait.
     *
     * @return Model
     */
    private static function model(): Model
    {
        return new (get_class());
    }

    /**
     * Find a model by id, remove the model into the database,
     * otherwise it throws an exception.
     *
     * @param  int  $id
     * @return Model
     *
     * @throws \App\Exceptions\ModelDeletionException
     */
    public static function deleteOrThrow(int $id): Model
    {
        $model = self::model()->findOrFail($id);

        if ($model->delete() === false) {
            throw new ModelDeletionException($id, get_class());
        }

        return $model;
    }
}

Our trait is composed of two functions: model() which is responsible for returning an instance of the model implementing the trait, and deleteOrThrow() which is responsible for deleting the model or throwing an exception in case delete fails.

Here we are simply implementing the behavior that I belive that would be the expected behavior for the new native deleteOrFail() function, in fact, I used to call the deleteOrThrow() function deleteOrFail() but I had to rename it to not conflict with the deleteOrFail() function implemented in Laravel 8.58.0.

The model function

/**
 * Instantiate the model implementing this trait by the model's class name.
 *
 * @return Model
 */
private static function model(): Model
{
    return new (get_class());
}

As mentioned, this function is responsible for returning an instance of the model implementing the trait, and since PHP allows us to use meta-programming to instantiate classes, let's take advantage of that and instantiate the model by its class name.

In this function, we have a single line with a return statement that instantiates a new object out of the get_class() function. To fully understand how this function works, let's assume that this trait was implemented by the User model. When evaluating the result of the function, we would get the string "App\Models\User".

When evaluated by the interpreter, this line would be the equivalent of return new ("App\Models\User");, but the get_class() gives us the dynamism of getting the right class name for each model implementing the trait.

The deleteOrThrow function

/**
 * Find a model by id, remove the model into the database,
 * otherwise it throws an exception.
 *
 * @param  int  $id
 * @return Model
 *
 * @throws \App\Exceptions\ModelDeletionException
 */
public static function deleteOrThrow(int $id): Model
{
    $model = self::model()->findOrFail($id);

    if ($model->delete() === false) {
        throw new ModelDeletionException($id, get_class());
    }

    return $model;
}

In the first line, the self:: call indicates that we want to interact with the trait itself, and then we are chaining the model() function to it, which means we are calling the function previously defined.

Subsequently, we have a conditional where we are calling $user->delete(), in case the function returns false, a custom exception gets thrown.

Finally, after a successful delete, we return the deleted model.

Custom exception

Here we are using the same technique explained in the Laravel custom exceptions post. If you didn’t read the post yet, take a moment to read it, so you can make sense out of this section.

<?php

namespace App\Exceptions;

use Illuminate\Support\Str;
use Illuminate\Http\Response;

class ModelDeletionException extends ApplicationException
{
    private int $id;
    private string $model;

    public function __construct(int $id, string $model)
    {
        $this->id = $id;
        $this->model = Str::afterLast($model, '\\');
    }

    public function status(): int
    {
        return Response::HTTP_BAD_REQUEST;
    }

    public function help(): string
    {
        return trans('exception.model_not_deleted.help');
    }

    public function error(): string
    {
        return trans('exception.model_not_deleted.error', [
            'id' => $this->id,
            'model' => $this->model,
        ]);
    }
}

At the class definition, we are extending the ApplicationException which is an abstract class used to enforce the implementation of the status(), help() and error() functions, and guaranteeing that Laravel will be able to handle this exception automatically.

Following the class definition, we have the constructor, where property promotion is being used to make the code cleaner. As parameters, we have $id, which contains the ID of the record we want to query from the database at our Trait, and $model where the full class name of the model can be found.

Inside the constructor, we are extracting the model name out of the full class name; the full name would be something like App\Models\User, and we want just the User part. This is getting done, so we can automate the error message into something that makes sense to the person interacting with our API in case it’s not possible to find the record for a given ID.

Next, we have the implementation of the status() function, where we are returning the 400 HTTP status.

Thereafter, we have the help() function, where we return a translated string that indicates a possible solution to the error. In case you are wondering, the translated string would be evaluated to Check your deleting parameter and try again.

Finally, we have the error() function, where the error that happened gets specified. As in the previous function, we are using a translated string, but differently from before, here we are using the replace parameters feature from trans().

This approach was chosen to give us a dynamic error message with context. Here, the translated string would be evaluated to something like User with id 1 not deleted.

With this structure, if the target model changes, the message emitted by the exception would change as well since the model name gets dynamically defined.

As a secondary example, imagine that now, you are interacting with a Sale model; in this case, the message would automatically change to Sale with id 2 not deleted.

Using the abstraction

Now that our abstraction has been defined, and we have guaranteed that the error handling is in place, we need to use our DeleteOrThrow Trait in the models that we want to have this simplified delete behavior.

To achieve that, we just have to put in our models the use DeleteOrThrow; exactly like the other Traits that normally Laravel brings in the models, you can see it with more details in the code example down below.

<?php

namespace App\Models;

use App\Helpers\DeleteOrThrow;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasFactory;
    use Notifiable;
    use HasApiTokens;
    use DeleteOrThrow;

    ...
}

Implementing it

As a final result, we end up with an API call that looks like User::deleteOrThrow($id) leaving us with a destroy action in our controllers that has a single line of implementation, and it is highly reusable.

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class Users extends Controller
{

    public function destroy(Request $request): Response
    {
        return response(User::deleteOrThrow($request->id));
    }
}

Happy coding!

Laravel: Update Actions Simplified

Jack Miras — Fri, 22 Apr 2022 12:05:30 +0000

When building APIs, we often come across CRUD operations. Even though these operations are one of the first things we learn when we start working with the backend, some of them can have significantly less code.

Besides that, this code frequently gets duplicated across controllers. Through my journey working with Laravel, I've noticed that this happens typically in update functions, and that's why I decided to share how to simplify this implementation.

Content

Conventional way
Shortening it
The updateOrFail function
Abstracting it
- Trait abstraction
- The model function
- The updateOrThrow function
- Custom exception
- Using the abstraction
- Implementing it

Conventional way

Before we jump into the simplification, let’s take a look at how an update operation looks like when conventionally implemented.

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class UsersController extends Controller
{
    public function update(Request $request): Response
    {
        $user = User::find($request->id);

        if ($user === null) {
            return response(
                "User with id {$request->id} not found",
                Response::HTTP_NOT_FOUND
            );
        }

        if ($user->update($request->all()) === false) {
            return response(
                "Couldn't update the user with id {$request->id}",
                Response::HTTP_BAD_REQUEST
            );
        }

        return response($user);
    }
}

On the first line, we are querying a user by its ID and storing the result in the $user object.

Then, at the first conditional, we check if the $user is null; if it is, it means that no record with the given ID got found, and an error message with status 404 will be returned.

Thereafter, we have a second conditional where we call $user->update() with the data that we want to update. This function returns true or false to let us know if the data was successfully updated. In the event it returns false, an error message with status 400 will be returned.

Finally, if the data is successfully updated, we render the updated user as a response.

Shortening it

Why not use the findOrFail() helper function to shorten our code? When using this approach, it would remove at least five lines from the update action of our controller, as shown in the code example down below.

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class UsersController extends Controller
{
    public function update(Request $request): Response
    {
        $user = User::findOrFail($request->id);

        if ($user->update($request->all()) === false) {
            return response(
                "Couldn't update the user with id {$request->id}",
                Response::HTTP_BAD_REQUEST
            );
        }

        return response($user);
    }
}

To make the most out of this change, we need to know how to automate the handling of the exception thrown by the findOrFail(). Otherwise, it would be necessary to use a try/catch block, and the number of lines would be mostly the same.

As in the previous example, we have a conditional where we are calling $user->update() with the data that we want to update. In the event it returns false, an error message with status 400 will be sent.

Finally, if the user was correctly updated, we render the updated user as a response.

The updateOrFail function

NOTE: This function will only be available if you are using Laravel on version 8.58.0 or newer.

Now that we’ve seen two different ways of implementing the update action on Laravel, let’s see how we can implement this using the updateOrFail() function.

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use App\Exceptions\ModelUpdatingException;

class Users extends Controller
{
    public function update(Request $request): Response
    {
        $user = User::findOrFail($request->id);

        if ($user->updateOrFail($request->all()) === false) {
            return response(
                "Couldn't update the user with id {$request->id}",
                Response::HTTP_BAD_REQUEST
            );
        }

        return response($user);
    }
}

On the first line, we are querying a user by its ID using the findOrFail() function.

Next, we have a second conditional where we call $user->updateOrFail() with the data that we want to update. This function returns true or false to let us know if the data was successfully updated. In the event it returns false, an error message with status 400 will be returned.

And again, if the user was correctly updated, we render the updated user as a response.

NOTE: Notice that the updateOrFail() function doesn't have any significant difference from the update() function, and the resultant usage is exactly the same as the one presented in the previous section.

This is a very odd implementation in the framework, since most of the *orFail() functions usually throw an exception. If that was the case, we could just automate the handling of the exception thrown by the updateOrFail() function the same way we did in the last post in my series about exceptions.

If we had a standard *orFail() function, this function would be the simplest way of implementing an update action in a controller, completely removing the need for the approach that will be explained in the next section.

Abstracting it

Let’s see how we can abstract this implementation in such a way that we get high reusability with simple usage out of this abstraction.

Since this abstraction interacts with models, I wanted to avoid using inheritance because it would be a coupling too high for an abstraction as simple as this one.

Furthermore, I want to leave the inheritance in the models open for usage, whether by a team member's decision or by some specific use case.

For that reason, I’ve chosen to implement the abstraction as a trait. Differently from C++, where we can use multiple inheritance, in PHP, a trait is the mechanism to reduce limitations around single inheritance.

Besides that, I have a personal rule where I use traits only when an implementation gets highly reused. Since most of my controllers end up having an update action, in my context, this is something highly reused.

Trait abstraction

<?php

namespace App\Helpers;

use Illuminate\Database\Eloquent\Model;
use App\Exceptions\ModelUpdatingException;

trait UpdateOrThrow
{
    /**
     * Instantiate the model implementing this trait by the model's class name.
     *
     * @return Model
     */
    private static function model(): Model
    {
        return new (get_class());
    }

    /**
     * Find a model by id, fill the model with an array of attributes, update
     * the model into the database, otherwise it throws an exception.
     *
     * @param  int  $id
     * @param  array  $attributes
     * @return Model
     *
     * @throws \App\Exceptions\ModelUpdatingException
     */
    public static function updateOrThrow(int $id, array $attributes): Model
    {
        $model = self::model()->findOrFail($id)->fill($attributes);

        if ($model->update() === false) {
            throw new ModelUpdatingException($id, get_class());
        }

        return $model;
    }
}

Our trait will be a compound of two functions: model() which is responsible for returning an instance of the model implementing the trait, and updateOrThrow() which is responsible for updating the model or throwing an exception in case the update fails.

Here we are simply implementing the behavior that I belive that would be the expected behavior for the new native updateOrFail() function, in fact, I used to call the updateOrThrow() function updateOrFail() but I had to rename it to not conflict with the updateOrFail() function implemented in Laravel 8.58.0.

The model function

/**
 * Instantiate the model implementing this trait by the model's class name.
 *
 * @return Model
 */
private static function model(): Model
{
    return new (get_class());
}

The updateOrThrow function

/**
 * Find a model by id, fill the model with an array of attributes, update
 * the model into the database, otherwise it throws an exception.
 *
 * @param  int  $id
 * @param  array  $attributes
 * @return Model
 *
 * @throws \App\Exceptions\ModelUpdatingException
 */
public static function updateOrThrow(int $id, array $attributes): Model
{
    $model = self::model()->findOrFail($id)->fill($attributes);

    if ($model->update() === false) {
        throw new ModelUpdatingException($id, get_class());
    }

    return $model;
}

Then we chain into the model() function call the findOrFail() function, passing the ID of the record we would like to retrieve from the database. Once the record gets found and a populated model gets returned, we chain the fill() function call, passing the data that we want to update.

Subsequently, we have a conditional where we call $user->update() this function returns true or false to let us know if the data got successfully updated. In case it returns false, a custom exception gets thrown.

Finally, after a successful update, we returned the updated model.

Custom exception

Here we are using the same technique explained in the Laravel custom exceptions post. If you didn’t read the post yet, take a moment to read it, so you can make sense out of this section.

<?php

namespace App\Exceptions;

use Illuminate\Support\Str;
use Illuminate\Http\Response;

class ModelUpdatingException extends ApplicationException
{
    public function __construct(private int $id, private string $model)
    {
        $this->model = Str::afterLast($model, '\\');
    }

    public function status(): int
    {
        return Response::HTTP_BAD_REQUEST;
    }

    public function help(): string
    {
        return trans('exception.model_not_updated.help');
    }

    public function error(): string
    {
        return trans('exception.model_not_updated.error', [
            'id' => $this->id,
            'model' => $this->model,
        ]);
    }
}

Following the class definition, we have the constructor, where property promotion is being used to make the code cleaner. As parameters, we have $id, which contains the ID of the record we want to query from the database at our trait, and $model where the full class name of the model can be found.

Next, we have the implementation of the status() function, where we are returning the 400 HTTP status.

This approach was chosen to give us a dynamic error message with context. Here, the translated string would be evaluated to something like User with id 1 not updated.

With this structure, if the target model changes, the message emitted by the exception would change as well since the model name gets dynamically defined.

As a secondary example, imagine that now, you are interacting with a Sale model; in this case, the message would automatically change to Sale with id 2 not updated.

Using the abstraction

Now that our abstraction has been defined, and we have guaranteed that the error handling is in place, we need to use our UpdateOrThrow trait in the models that we want to have this simplified update behavior.

To achieve that, we just have to put in our models the use UpdateOrThrow; exactly like the other traits that normally Laravel brings in the models, you can see it with more details in the code example down below.

<?php

namespace App\Models;

use App\Helpers\UpdateOrThrow;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasFactory;
    use Notifiable;
    use HasApiTokens;
    use UpdateOrThrow;

    ...
}

Implementing it

As a final result, we end up with an API call that looks like User::updateOrThrow($id, $params) leaving us with an update action in our controllers that has a single line of implementation, and is highly reusable.

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class Users extends Controller
{

    public function update(Request $request): Response
    {
        return response(User::updateOrThrow($request->id, $request->all()));
    }
}

Happy coding!

Laravel's exceptions: Part 3 – findOrFail exception automated

Jack Miras — Fri, 18 Feb 2022 12:33:40 +0000

When implementing something that requires querying the database to find a record by its ID, the first thing that comes to mind is the find() function from Eloquent.

Even though the function works, and you will be able to retrieve your data when it exists, a null object will be returned if the record is not found, and this null object usually brings unnecessary complexity.

As you know, Laravel is a full-featured framework, but one of the features that blew my mind once I got the hang of it, was the exception handling of the framework. It’s not random that some of Laravel’s helpers throw exceptions instead of returning null objects, such as the findOrFail() function.

These helpers that throw exceptions can be pretty handy when you learn how to automate the handling of their exceptions, making the code cleaner and shorter. But before we dive into those functions or Laravel’s exception handler, let’s take a look at ways that a find operation can be implemented.

Content

Ways to implement
- The find function
- The findOrFail function
Automating exceptions
Final implementation

Ways to implement

In the following two sections, we will see the most conventional ways of implementing a find operation. You will notice that the number of lines between the implementations is the same; although they are entirely different implementations and there are no real advantages between them, the choice of the approach is just a matter of preference.

The find function

Down below, we have a real use case where we are implementing a show action to the UsersController to find a user by its ID and render the record as a response to an endpoint.

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class UsersController extends Controller
{
    public function show(Request $request): Response
    {
        $user = User::find($request->id);

        if ($user === null) {
            return response("User with id {$request->id} not found", Response::HTTP_NOT_FOUND);
        }

        return response($user);
    }
}

First, we query a user by its ID using the find function and store its result in an $user object.

Next, because the record of a given ID may not be found in the database, we are checking if the $user is null; in case it is, we will return a message that would evaluate to User with id 1 not found.

Finally, if the ID passed into the query got found, the user object would be present, and we could just return it as a response to the API call.

The findOrFail function

With the same use case as before, let’s try a second approach and see how our code looks when using the findOrFail() function without automating its exception handling.

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Illuminate\Database\Eloquent\ModelNotFoundException;

class UsersController extends Controller
{
    public function show(Request $request): Response
    {
        try {
            $user = User::findOrFail($request->id);
        } catch (ModelNotFoundException $exception) {
            return response("User with id {$request->id} not found", Response::HTTP_NOT_FOUND);
        }

        return response($user);
    }
}

At the try{} block we are querying the user by its ID; when found, we will place the data at the $user, but unlike the previous approach, a ModelNotFoundException will be thrown in case the record doesn't exist.

Thereafter, the catch{} block gets used to intercept the exception thrown; once the exception gets intercepted, we build a response with a message that would be evaluated to User with id 1 not found.

Then, if the given ID gets found, the $user object would be present, and we would return it as a response to the endpoint.

Automating exceptions

It’s important to notice that the approach about to be explained can be used to automate the handling of various Laravel exceptions. By automating these exceptions, you will have cleaner code and a more structured way of handling the exceptions.

To automatically handle the exception thrown by the findOrFail() function, we will have to override the render() function in the app/Exceptions/Handler.php class, as shown in the example down below.

<?php

namespace App\Exceptions;

use Throwable;
use Illuminate\Support\Arr;
use Illuminate\Http\Response;
use Illuminate\Database\Eloquent\ModelNotFoundException;
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;

class Handler extends ExceptionHandler
{
    /**
     * Render an exception into an HTTP response.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Throwable  $e
     * @return \Symfony\Component\HttpFoundation\Response
     *
     * @throws \Throwable
     */
    public function render($request, Throwable $e)
    {
        if ($e instanceof ModelNotFoundException) {
            $replacement = [
                'id' => collect($e->getIds())->first(),
                'model' => Arr::last(explode('\\', $e->getModel())),
            ];

            $error = new Error(
                help: trans('exception.model_not_found.help'),
                error: trans('exception.model_not_found.error', $replacement)
            );

            return response($error->toArray(), Response::HTTP_NOT_FOUND);
        }

        return parent::render($request, $e);
    }
}

We start by declaring a conditional that checks if the $e being received in the render() parameter is an instance of the ModelNotFoundException thrown by the findOrFail() used in the previous examples.

Then, we create a $replacement array, an associative with the keys id and model, whose values are getting extracted from the intercepted exception. This replacement array gets used as a replacement parameter in a trans() function that gets called in the constructor of the error object.

Subsequently, we are creating an $error object. In case you don’t know what this Error class is about, please take a moment to read the previous post in this series, where I discuss custom exceptions. The error class takes two mandatory parameters: $help which shows a possible solution to the error, and $error where the error that happened gets specified.

Note that we are using named parameters and the trans() helper to specify the messages we want to pass into the $help and $error parameters from the error object.

Lastly, with the error object instantiated, we can build the response object to be rendered to the API call. To achieve that, we are using the response() function passing $error->toArray() as the first parameter, and Response::HTTP_BAD_REQUEST as the second one, which is the constant of the HTTP status 400.

Final implementation

As a final result, we have a show action that can be implemented with one single line, without the need for checking for a null object nor try/catch blocks to handle the exception getting thrown.

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class UsersController extends Controller
{
    public function shows(Request $request): Response
    {
        return response(User::findOrFail($request->id));
    }
}

Now our findOrFail exception automation is done.

Happy coding!

Laravel's exceptions: Part 2 – Custom exceptions

Jack Miras — Thu, 10 Feb 2022 02:00:33 +0000

After working with Laravel for a while and learning about its way of handling exceptions, I found myself creating my own exceptions, either to simplify some if/else statements or to terminate function calls or even features.

These custom exceptions are helpful, especially when combined with the throw_if and throw_unless functions, which provide a cleaner way of throwing conditional exceptions.

Content

Understanding custom exception
Structuring custom exceptions
- Making exceptions simple and extensible
- Standardizing errors
Creating the JsonEncodeException

Understanding custom exceptions

Laravel can handle custom exceptions automatically when the exception is created in a certain way. First, the exception has to extend the Exception class, and then, in case you want to render something to the end user, you have to override the render() function.

If you need to create an exception that will extend a class that isn’t the Exception class, Laravel won’t be able to automatically handle the exception, and as a result, you will have to use a try/catch block.

Check the following code example to better understand how a custom exception can be defined.

<?php

namespace App\Exceptions;

use Exception;
use Illuminate\Http\Response;

abstract class MyCustomException extends Exception
{

    public function render(Request $request): Response
    {
        $status = 400;
        $error = "Something is wrong";
        $help = "Contact the sales team to verify";

        return response(["error" => $error, "help" => $help], $status);
    }
}

The result, from the exception above, would be a response with HTTP status 400 and a JSON in the following format:

{
    "error": "Something is wrong",
    "help": "Contact the sales team to verify"
}

To test this example and validate the rendered JSON, you can use plain PHP to throw the exception just like this throw new MyCustomException();

Structuring custom exceptions

Even though the creation of custom exceptions is pretty straightforward, it’s possible to design a more robust architecture around exceptions. The design that will be presented in this post has two premises.

1) Making exceptions simple and extensible.
2) Standardize the way error responses are shown.

For them to be simpler and more extensible, we need to define a structure from which every custom exception can derive.

As for standardizing them, it’s required to define how the error will be shown to the end user, and it is important to display your errors in a single, structured manner. Otherwise, front-end applications or other APIs integrating with yours won’t be able to trust your error responses, and these kinds of applications are just horrible to work with.

Making exceptions simple and extensible

So, how can we implement custom exceptions in a way that we can enforce that every exception will comply with the appropriate status code, error, message, and other properties consistently on a basis that can be reused? For that, we can define an abstraction that all custom exceptions will implement, as the code below shows.

<?php

namespace App\Exceptions;

use Exception;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

abstract class ApplicationException extends Exception
{
    abstract public function status(): int;

    abstract public function help(): string;

    abstract public function error(): string;

    public function render(Request $request): Response
    {
        $error = new Error($this->help(), $this->error());
        return response($error->toArray(), $this->status());
    }
}

Here, an abstract class gets defined to enforce that every exception will implement a status(), help() and error() functions.

In the render() function that we are overriding from the Exception class, we are using the result of the implementation of our help and error methods to create an error object.

The error object is responsible for standardizing the errors in the application; it doesn’t matter whether the error was from an exception or a business rule validation; if it is an error, it will be encapsulated into the error object.

Standardizing errors

To standardize errors, we will create the already mentioned and previously used error object. This object has two main characteristics.

1) Define the data properties that will be shown when rendering the error.
2) Be able to be automatically transformed into JSON by Laravel.

<?php

namespace App\Exceptions;

use JsonSerializable;
use Illuminate\Contracts\Support\Jsonable;
use Illuminate\Contracts\Support\Arrayable;

class Error implements Arrayable, Jsonable, JsonSerializable
{
    public function __construct(private string $help = '', private string $error = '')
    {
    }

    public function toArray(): array
    {
        return [
            'error' => $this->error,
            'help' => $this->help,
        ];
    }

    public function jsonSerialize(): array
    {
        return $this->toArray();
    }

    public function toJson($options = 0.0)
    {
        $jsonEncoded = json_encode($this->jsonSerialize(), $options);
        throw_unless($jsonEncoded, JsonEncodeException::class);
        return $jsonEncoded;
    }
}

Notice that the class declaration implements three interfaces; these interfaces are responsible for making the class capable of being converted into an array or a JSON.

Following the class declaration, we have the constructor where property promotion is getting used to keep the code cleaner; as parameters, we have $help which shows a possible solution to the error getting shown, and $error where the error that happened gets specified.

Next, we have the toArray() function, where the error object gets returned as an array.

Then we have the jsonSerialize() function, where the error object also returns as an array. Here we are applying DRY and just calling the toArray() inside the jsonSerialize() function; since they return the same result, there is no reason for us to repeat ourselves.

Finally, we have the toJson() function, where our object gets converted into a JSON string. Notice that we start by calling the json_encode(). To this function, we are passing as parameters the result from jsonSerializer() previously implemented and the $options from the function itself.

As a result, we should have the $jsonEncoded variable a JSON string matching the information present in our error object; however, in cases where json_encode() can’t transform the array passed as a parameter into JSON, it will return a boolean false.

For that reason, in the next line we’re using the throw_unless() helper to throw an exception in case $jsonEncoded is evaluated to false, and otherwise we return the JSON string in the subsequent line.
Now we just need to define the JsonEncodeException that we conditionally throw in the toJson() function.

Creating the JsonEncodeException

Considering that this exception is a custom exception written specially to handle the JSON conversion of our error object, it makes perfect sense to use our ApplicationException from the previous session.

<?php

namespace App\Exceptions;

use Illuminate\Http\Response;

class JsonEncodeException extends ApplicationException
{
    public function status(): int
    {
        return Response::HTTP_BAD_REQUEST;
    }

    public function help(): string
    {
        return trans('exception.json_not_encoded.help');
    }

    public function error(): string
    {
        return trans('exception.json_not_encoded.error');
    }
}

Notice that once we extend the ApplicationException class, we have the obligation to implement the status, help, and error functions. Inside these functions, we implemented the return of the values that make sense in the context of this exception.

In this specific example, we are returning HTTP status 400, and we are getting translated texts from Laravel’s translating scheme.

Keeping all your messages and texts in Laravel’s translation structure is always a good decision. Having to translate an app after a lot of written code is often more difficult and requires much more refactoring than starting the app with this pattern.

Now our custom exception structure and encapsulation of errors are done.

Happy coding!

Laravel's exceptions: Part 1 – What are exceptions?

Jack Miras — Thu, 10 Feb 2022 02:00:23 +0000

An exception is an event that occurs during the execution of a program that disrupts the normal flow of instructions. PHP uses exceptions to handle errors and other exceptional events.

As in many other languages, an exception can be thrown and caught. You can throw an exception using the throw keyword, which in PHP 8 became an expression that may be used in any expression context, while in previous versions it was a statement that had to be in its line.

To facilitate the catching of exceptions, the code should be surrounded by a try block that must have at least one matching catch or finally blocks. If an exception gets thrown and its current scope doesn’t have a catchable block, the exception will “bubble up” or be sent to a “higher scope”.

If the handling of an exception implements both the catch and finally blocks, be advised that all finally blocks encountered in the way of the exception event will be executed, even when the event has already passed through the catch block.

Finally, if an exception goes all the way to the global scope without finding a matching catchable block, your code will terminate with a fatal error unless the app has a global exception handler, like the one that Laravel has.

Content

Throwing exceptions
The try and catch blocks
The finally block

Throwing exceptions

Now that we understand the structure around exception events, let’s see a couple of examples of how we can throw and catch exceptions.

Let’s say we want to parse a PHP object to JSON; we would probably use the json_encode() function for that. This function will not always be able to transform the given object to JSON for various reasons, and when this happens, the function will return false to let us know that the transformation failed.

In some ways, we can say that if the transformation of the object fails, our code gets disrupted from the normal flow of instructions since we instructed the code to get us a JSON, and we got a boolean instead.

With that being said, let’s see in the example down below, how we can use an exception to trigger an event informing that something out of the normal flow has happened.

<?php

class Person
{
    private $props = [];

    public function __construct(
        private string $name = '',
        private string $lastName = ''
    ) {
        $this->props = [
            'name' => $this->name,
            'last_name' => $this->lastName,
        ];
    }

    public function toJson($options = 0.0)
    {
        $jsonEncoded = json_encode($this->props, $options);

        if ($jsonEncoded === false) {
            throw new JsonEncodeException();
        }

        return $jsonEncoded;
    }
}

The toJson() function is responsible for transforming his class into JSON; as mentioned before, we were going to use the json_encode() which is being called at the first line of the function and has its returned value stored at the $jsonEncoded object.

Next, we have a conditional that checks if the $jsonEncoded is false, and if it is, an exception will be thrown because the normal flow of our code got disrupted.

Then, if the flow of our code didn’t get disrupted, we would just return the $jsonEncoded object, which at this point is a JSON with the correspondent values of the props from our Person class.

The try and catch blocks

To catch the exception potentially thrown by the Person class, we have to use a try with a matching catch block, as the example down below shows.

try {
    $person = new Person('Jack', 'Miras');
    $personAsJson = $person->toJson();
} catch(JsonEncodeException $e) {
    echo "Exception has been caught";
}

On the first line of the try block, we are creating a person object, passing a name and a last name as parameters in its constructor.

Next, we call the toJson() function out of the $person object. If the object got correctly transformed into JSON, the $personAsJson object would receive a JSON string as a result. Otherwise, an exception would be thrown, and the catch block would be triggered.

Thereafter, if an exception gets thrown and the catch block gets triggered, it would first check if the exception being intercepted is an instance of the JsonEncodeException class. If that’s the case, the catch block would take this exception event, passing it to its handling block, which is printing a message telling that the exception has been caught.

The finally block

Another way of handling the exception potentially thrown by the Person class would be to use a finally block to match the try block defined, as the example below shows.

try {
    $person = new Person('Jack', 'Miras');
    $personAsJson = $person->toJson();
} finally {
    echo "Converting person to JSON failed";
}

As in the previous example, at the try block, we are creating a person object and calling the toJson() function out of it. If the object gets correctly transformed, the $personAsJson would receive a JSON string. Otherwise, an exception would be thrown.

Thereafter, if an exception gets thrown, the finally block will be triggered even though a catch block has already handled the exception event.

If that’s the case, the finally block would take in this exception event and print a message telling that the conversion of the person object into JSON failed.

Now that you have a more in-depth understanding of what exceptions are and what they are used for, it’s time for us to move on to the next post in this series.

Happy coding!

Xdebug in PhpStorm with Docker

Jack Miras — Fri, 17 Dec 2021 10:45:14 +0000

In my last post, I talked about how to configure Xdebug in VSCode with Docker. Now, I would like to share how we can build upon our previous Dockerfile in such a way that Xdebug can run directly from Docker and also connect it with PhpStorm.

By choosing this approach, we substantially reduce the amount of setup that each team member has to do on their machine to get the project up and running, which means that we can start writing code faster.

So, why is this so important? Recent research from JetBrains shows that 62% of PHP developers debug their code using var_dump(), die(), dd(), and dump(). From my perspective, there is nothing wrong with that. Even if you do it by choice and not because you lack knowledge.

I'm included in the 62% of developers who debug their code with auxiliary functions instead of using a full-featured debug solution such as Xdebug. I'm a heavy Neovim user, and I didn't adapt quite well to using Neovim with Xdebug; to me, it is just easier and faster to use my code snippets around the dd() function.

But occasionally, I catch myself in situations where it would be faster to jump into PhpStorm and just use Xdebug, especially when I'm working with other people who aren't familiar with Vim or Neovim.

Content

Xdebug config file
- Explaining xdebug.ini
PhpStorm

Xdebug config file

Before jumping into PhpStorm, first we have to clear up a few things about Xdebug to fully grasp the changes we’re going to make to the IDE. The information was first introduced on the topic of the command directive in a previous post. You will notice that at some point a xdebug.ini file gets copied from a local .docker folder into /etc/php8/conf.d/50_xdebug.ini at the container.

Even though the content of the file got shown, I intentionally didn't explain its content so that we could explore the debugging topic all at once, going all the way from configuring Xdebug to using it with an IDE.

Down below, we have the same Xdebug config file from the previous post, placed at .docker/xdebug.ini on the root of our Laravel project. Each line of code will be explained further, but in case you want to know every configuration that you can add in this file, check the Xdebug documentation.



zend_extension=xdebug.so
xdebug.mode=develop,coverage,debug,profile
xdebug.idekey=docker
xdebug.start_with_request=yes
xdebug.log=/dev/stdout
xdebug.log_level=0
xdebug.client_port=9003
xdebug.client_host=<YOUR_COMPUTER_IP>

Explaining xdebug.ini

zend_extension=xdebug.so

A Zend extension hooks into “lower-level” languages; a single extension can be both a PHP and a Zend extension; despite being very uncommon, it's possible, and Xdebug is a good example of it.

xdebug.mode=develop,coverage,debug,profile

This setting controls which Xdebug features get enabled; according to the documentation, the following values will get accepted:

- develop
Enables Development Helpers, including the overloaded var_dump().
- coverage
Enables Code Coverage Analysis to generate code coverage reports, mainly with PHPUnit.
- debug
Enables step-debugging. This can be used to step through your code while it is running, and analyze the values of variables.
- profile
Enables Profiling, with which you can analyze performance bottlenecks with tools like CacheGrind.

xdebug.idekey=docker

Controls which IDE key Xdebug should pass on to the debugging client or proxy. The IDE Key is only important for use with the DBGp Proxy Tool, although some IDEs are incorrectly picky as to what its value is. The default is based on the DBGP_IDEKEY environment setting. If it is not present, the default falls back to an empty string.

xdebug.start_with_request=yes

The functionality starts when the PHP request starts, and before any PHP code gets executed. For example, xdebug.mode=trace and xdebug.start_with_request=yes, start a function trace for the whole request.

xdebug.log=/dev/stdout

Configure Xdebug's log file, but in this case, we are redirecting the log content to the default stdout of our container.

In case you don't want to see these logs you can comment out this line of your .docker/xdebug.ini file by changing the line to ;xdebug.log=/dev/stdout.

xdebug.log_level=0

Configures which logging messages should be added to the log file. In this case, we are instructing Xdebug to log only errors in the configuration. If you want to see more information, you can use level 7 for log info or level 10 for log debug.

xdebug.client_port=9003

The port to which Xdebug tries to connect on the remote host. Port 9003 is the default for both Xdebug and the Command Line Debug Client. As many clients use this port number, it is best to leave this setting unchanged.

xdebug.client_host=<YOUR_COMPUTER_IP>

Configures the IP address or hostname to which Xdebug will attempt to connect when initiating a debugging connection. This address should be the address of the machine where your IDE or debugging client is listening for incoming debugging connections.

Down below, you can see how to get your IP address correctly in the main OS the developers use. In case you are using a different OS, the commands may serve as a base to try to extrapolate a solution for your use case.

macOS:



ipconfig getifaddr en0

Windows with WSL:



grep nameserver /etc/resolv.conf | cut -d ' ' -f2

Linux (Debian-based distros):



hostname -I | cut -d ' ' -f1

Once you have correctly found your IP address, you can place it into xdebug.client_host as mentioned before, and that will leave you with a directive looking similar to this: xdebug.client_host=192.168.0.158.

In summary, you've instructed Xdebug to start with a request and try to send the debug events to the host with the IP 192.168.0.158 on port 9003. Since the IP represents your computer, when configuring PhpStorm to connect to Xdebug, the configuration will be extremely similar to when connecting to localhost.

PhpStorm

As you may already know, PhpStorm is a proprietary, cross-platform IDE for PHP, built by the Czech Republic-based company JetBrains. PhpStorm provides an editor for PHP, HTML, and JavaScript with on-the-fly code analysis, error prevention, and automated refactorings for PHP and JavaScript code.

With that being said, you may be wondering: “What do we need to have PhpStorm with all the aspects of an IDE with full-featured debugging”?

For starters, we need to check if the IDE can properly connect with Docker:

Thereafter, we have to configure a PHP server. This can be done by going to Settings > PHP > Servers, then clicking on the plus sign, as the following screenshot shows:

Once you click the plus sign, a form will open, where the Name, Host, Port, and Absolute path of the server have to be filled in:

Notice that the Port matches the port from our previsouly built docker-compose.yml and the Absolute path on the server matches the workdir from our previously built Dockerfile.

Now, that the server has been created, we can move to the debug configuration. Let's start by clicking on the More Actions button in the main window, as the next screenshot shows:

Then, click on the Edit… option to open the Run/Debug Configurations window:

Subsequently, click into Add New Configuration > PHP Remote Debug as the screenshot down below shows:

Next, a form will open, and there, fill the Name with your Remote Debug configuration; next, check the Filter debug connection by IDE key option and then select the Server previously created; and finally, fill the IDE key (session id) with the same value that got used at the xdebug.idekey directive at our .docker/xdebug.ini. More details are in the illustration below:

As a result of the previous steps, the remote debug configuration got finished, and PhpStorm can now start listening for PHP debug connections. Click on the indicated button, as shown:

And then, as a final step, click the debug button. Once the debug is running, you can trigger a request through Postman or your tests, and PhpStorm will intercept the event and stop at the first breaking point found.

Now, Xdebug is finally configured in your PhpStorm, and you can enjoy a more robust debugging tool with the potential to speed up your entire workflow.

Happy coding!

Xdebug in VSCode with Docker

Jack Miras — Fri, 10 Dec 2021 04:08:09 +0000

In my last post, I talked about how to configure a development environment and how it extends a Dockerfile made for production.

Now, I would like to share how we can build upon our previous Dockerfile in such a way that Xdebug can run directly from Docker and also connect it with Visual Studio Code.

I'm included in the 62% of developers who debug their code with auxiliary functions instead of using a full-featured debug solution such as Xdebug. I'm a heavy Neovim user, and I didn't adapt quite well to using Neovim with Xdebug; it is just easier and faster to use my code snippets around the dd() function.

But occasionally, I catch myself in situations where it would be faster to jump into Visual Studio Code and just use Xdebug, especially when I'm working with other people who aren't familiar with Vim or Neovim.

Content

XDebug config file
- Explaining xdebug.ini
Visual Studio Code
- Explaining launch.json

Xdebug config file

Before jumping into VSCode, first we have to clear up a few things about Xdebug to fully grasp the changes we’re going to make to the IDE. The information was first introduced on the topic of the command directive in a previous post. You will notice that at some point a xdebug.ini file gets copied from a local .docker folder into /etc/php8/conf.d/50_xdebug.ini at the container.



zend_extension=xdebug.so
xdebug.mode=develop,coverage,debug,profile
xdebug.idekey=docker
xdebug.start_with_request=yes
xdebug.log=/dev/stdout
xdebug.log_level=0
xdebug.client_port=9003
xdebug.client_host=<YOUR_COMPUTER_IP>

Explaining xdebug.ini

zend_extension=xdebug.so

A Zend extension hooks into “lower-level” languages; a single extension can be both a PHP and a Zend extension; despite being very uncommon, it's possible, and Xdebug is a good example of it.

xdebug.mode=develop,coverage,debug,profile

This setting controls which Xdebug features get enabled; according to the documentation, the following values will get accepted:

- develop
    Enables Development Helpers, including the overloaded var_dump().
- coverage
    Enables Code Coverage Analysis to generate code coverage reports, mainly with PHPUnit.
- debug
    Enables step-debugging. This can be used to step through your code while it is running and analyze the values of variables.
- profile
    Enables Profiling, with which you can analyze performance bottlenecks with tools like CacheGrind.

xdebug.idekey=docker

xdebug.start_with_request=yes

The functionality starts when the PHP request starts and before any PHP code is executed. For example, xdebug.mode=trace and xdebug.start_with_request=yes, start a function trace for the whole request.

xdebug.log=/dev/stdout

Configure Xdebug's log file, but in this case, we are redirecting the log content to the default stdout of our container.

In case you don't want to see these logs you can comment out this line of your .docker/xdebug.ini file by changing the line to ;xdebug.log=/dev/stdout.

xdebug.log_level=0

xdebug.client_port=9003

xdebug.client_host=<YOUR_COMPUTER_IP>

macOS:



ipconfig getifaddr en0

Windows with WSL:



grep nameserver /etc/resolv.conf | cut -d ' ' -f2

Linux (Debian-based distros):



hostname -I | cut -d ' ' -f1

In summary, you've instructed Xdebug to start with a request and try to send the debug events to the host with the IP 192.168.0.158 on port 9003. Since the IP represents your computer, when configuring Visual Studio Code to connect to Xdebug, the configuration will be extremely similar to when connecting to localhost.

Visual Studio Code

As you may already know, Visual Studio Code, or, VSCode for short, is a source-code editor made by Microsoft for Windows, Linux, and macOS. Features include support for debugging, syntax highlighting, intelligent code completion, snippets, code refactoring, and embedded Git.

With that being said, you may be wondering: “What do we need to have VSCode with all the aspects of an IDE with full-featured debugging?”

For starters, we will need to install the PHP Debug official plugin:

Thereafter, a file called launch.json has to be generated; this file gets used by the debugger in any language, which means that a part of this process can be reused when configuring the debugger on VSCode for other languages.

You can generate the file by clicking in Run and Debug > Create a launch.json file > PHP, as the following screenshot shows:

Finally, the launch.json file will be created with a specification of version and a configurations array with three configurations: Listen for Xdebug, Launch currently open script and Launch Built-in web server, as the screenshot shows:

Now, to properly configure the launch.json file, you have to replace the configurations array by the following:



{

    "version": "0.2.0",

    "configurations": [

        {

            "name": "Listen for XDebug on Docker",

            "type": "php",

            "request": "launch",

            "port": 9003,

            "pathMappings": {

                "/var/www/html/": "${workspaceFolder}"

            }

        }

    ]

}

Explaining launch.json

name

Indicates the name given to a configuration object.

type

Indicates the underlying debugger is being used.

request

Indicates whether the configuration is intended to launch the program or attach to an already running instance.

port

Indicates the port on which to listen for Xdebug

pathMappings

Indicates a mapping of server paths to local paths.

When using /var/www/html/ as key, VSCode knows that the files at the container are under that path, and by using the ${workspaceFolder} as value, VSCode knows that locally the project files are under the current opened directory.

Lastly, as a final step, click on the Start Debugging button and set the breaking points wherever you need.

Now, Xdebug is finally configured in your VSCode, and you can enjoy a more robust debugging tool with the potential to speed up your entire workflow.

I encourage you to leave this launch.json file with its content in the project, so other team members can just clone the project, run the containers, and enjoy a full-featured debug solution running in a container environment.

Happy coding!

Moving large amounts of data on AWS

Jack Miras — Mon, 15 Nov 2021 01:55:02 +0000

Recently, my team got tasked with decoupling all the images from a monolith that was public and had to become privately accessible, but we were also asked to keep the images publicly accessible to be consumed by a frontend app.

Our frontend app has access to the monolithic API through an API gateway. The gateway is in the same VPC as the monolith that became private, and therefore it can reach him. In my team, there is a strategy to carefully reduce these major apps into microservices and headless frontends.

To achieve our goal, we decided to move over 50 GB of images from an EFS storage disk into an S3 bucket and update the image references in the monolith database. In that way, we would achieve the goal of having a private app with public images.

At first, my approach was to use AWS CLI by connecting to the server attached to the EFS through SSH and using AWS CLI to sync all the images into the S3 bucket by using the following command:

aws s3 sync /var/www/html/app/media s3://app-production-media

This approach works, and if you have been tasked with something similar, you will achieve your goal, but this approach isn't the fastest. It took us 2 hours to sync 7 GB of data into the S3 bucket; at that pace, we would've spent more than 14 hours before finishing the synchronization of the images if we didn't get a timeout error, which we did.

Keep in mind that the aws s3 command got executed on an AWS server in the AWS network, which is way faster than the internet connection at my office, so these 14 hours have a higher weight, given the circumstances.

So, how could we move these 50 GB of images in an acceptable amount of time? That's where AWS DataSync comes in; this AWS service is meant to move data between the commonly used AWS storage solutions such as EFS, FSx, S3, NFS, Object Storage and SMB.

You do it by creating a DataSync task that can run only once or be scheduled to run from time to time. My recommendation is that you take a full look at the AWS DataSync documentation, so you can have a full view of DataSync's features.

This article shows how to create a task that runs manually. If you have a different use case, this article will serve you only as a base, and you will have to check the AWS documentation to implement extra aspects in your DataSync task.

Provisioning DataSync task

At the AWS management console, click on the search bar, search for DataSync and click on the service indicated in the image down below.

DataSync home page

After clicking it, you will be redirected to the following page: Notice that here you have access to a brief explanation of what DataSync is, how it works, and its benefits and features. Even though this article is straightforward, my recommendation is that you read everything on the DataSync home page. After finishing the reading, you can proceed to the next step by clicking on the Tasks option on the left-side menu.

Task dashboard

Once you've accessed the Tasks dashboard, you will see an empty dashboard with a Create Task button on the top-right side of the page. Click on the button to be redirected to the page that will allow you to start filling in the information about the DataSync task you will be creating.

Source location

Here, you must configure the source location from which the data will be copied. As mentioned previously, we will be copying data from an EFS disk into an S3 bucket. Hence, our source location will be pointing to an EFS disk, and down below, you can check how to configure the source location.

Destination location

After configuring the source location, you will be asked to configure the destination location, which will be an S3 bucket. Make sure to create and configure your bucket in such a way that your application can later read the files. Down below, you can check how to configure the destination location.

Configure settings

Once the source and destination locations are configured, you've got to handle general configuration settings such as task name, execution configuration, data transfer configuration, schedule, tags, and logging. Down below, you can check in more detail how to handle these general configurations.

When configuring the Task Logging, you can use a previously created CloudWatch log group, or just hit the Autogenerate button.

Review settings

Now that you've configured the task, it is time to review the configurations you've filled in. Read the review page carefully; if anything seems out of order, go back to the step where you found the mistake and fix it. Thereafter, come back to the review page, and once everything is the way you want it to be, you can click on the Create button in the bottom-right corner of the page.

Task start

Finally, the task got created, and now it's time to start it and initialize the process of copying the files from EFS to S3. To accomplish that, you just need to click on Start > Start with default.

Task status

Now that the task has started running, you can just watch the Task status until it is concluded. In case you want to see more details about the data getting copied from the EFS to S3, you can click on the Running status under Task status.

Execution status

Once you are watching the execution status, you can check a wide variety of information, including performance and the amount of data transferred. You will notice that at first the execution status will be Launching, but it will change as the data sync process keeps going.

Now that your DataSync task is finally done, you will have all of your data in a S3 bucket in a matter of minutes, not 14 hours.

Happy coding!