DEV Community: Anwar

Mantis - new file log driver

Anwar — Thu, 26 Dec 2024 18:22:35 +0000

Mantis is a type-safe web framework written in V that emphasizes explicit, magic-free code.

In this post, we'll explore the new file-based logging system and see how it integrates seamlessly with other Mantis features.

File logging

To log on a file, you just need to configure your http App by specifying the available File log channel.

module main

import khalyomede.mantis.http { create_app, App, Response }
import khalyomede.mantis.http.route
import khalyomede.mantis.logging { Log }
import khalyomede.mantis.logging.channel { File }

fn main() {
  app := create_app(
    log: {
      channel: File{
        path: "logs/mantis.log"
      }
    }
    routes: [
      route.get(path: "/", callback: fn (app App) !Response {
        app.log.debug("new user on the home page")!

        return app.response.html(content: "hello world")
      })
    ]
  )

  app.serve() or { panic(err) }
}

Coupled with error handling

Error handling and logging work together to help you track and debug issues in production. Here's how to configure both:

module main

import khalyomede.mantis.http { create_app, App, Response, ErrorHandler } 
import khalyomede.mantis.html { h1, div, p }
import khalyomede.mantis.http.route
import khalyomede.mantis.logging { Log }
import khalyomede.mantis.logging.channel { File }

fn main() {
  app := create_app(
    log: {
      channel: File{
        path: "logs/mantis.log"
      }
    }
    error_handler: ErrorHandler{ 
      report: fn (app App, err IError) {
        app.log.log(.error, err.msg()) or {} // <-----
      }
      render: fn (app App, err IError) Response {
        return app.response.html(
          content: h1({}, ['Oops! Something went wrong'])
          status: .server_error
        )
      }
    }
    routes: [
      route.get(name: "index", path: "/", callback: fn (app App) Response {
        return app.response.html(content: div({}, ["Home page"]))
      })
    ]
  )

  app.serve() or { panic(err) }
}

Standalone logging

Logging can be used outside an HTTP App. Read the documentation to learn more about it.

To go further

Learn more about logging, including dynamic severity by reading the documentation.

Let me know on Github issues or on Twitter if you find anything or want to contribute with any ideas.

Happy logging!

Mantis, a web framework written in V

Anwar — Sat, 21 Dec 2024 11:52:47 +0000

Tired of runtime errors in production? Meet Mantis: a type-safe web framework that helps you catch bugs at compile time, built with the simplicity of V.

Summary

What is V?
Who is Mantis for?
A tour of Mantis
Quick start
A note on type safety
Why another framework?
Veb
Conclusion

What is V?

V is a new general-purpose, type-safe functional programming language.

Its syntax draws inspiration from the simplicity of Go.

V emphasizes simplicity and explicitness at its core, making it straightforward to write and understand.

You can learn V's basics in about an hour by reading the documentation, allowing you to quickly start building your first hello world app.

Like Go, Deno, and Rust, V produces executables that run on Linux, Mac, and Windows.

What I love most about V is its first-class support for Result and Option types (abstract data types that we'll explore later).

With V, the lightning-fast compiler guides you to write safer code. When your app compiles, you can be confident it won't encounter runtime errors in production.

For development, V offers both an interpreter and watch mode, combining the convenience of scripting languages with the type safety and performance of compiled languages. It even includes built-in channel-compatible concurrency - truly the best of both worlds.

Who is Mantis for?

Mantis is a server-side rendered web framework for building web apps and APIs. It's ideal for:

Teams seeking type safety without complexity
Developers familiar with Go/Rust who want a simpler alternative for web apps
Projects requiring long-term maintainable applications
Developers tired of catching bugs in production

A tour of Mantis

Mantis offers a fresh approach to building APIs and web apps.

The framework prioritizes expressive, explicit code to create maintainable codebases.

It provides sensible defaults for common patterns like session handling and i18n.

Here's a simple hello world app:

module main

import khalyomede.mantis.http { create_app, App, Response }
import khalyomede.mantis.http.route

fn main() {
  app := create_app(
    routes: [
      route.get(name: "index", path: "/", callback: fn (app App) !Response {
        return app.response.html(content: "hello world")
      })
    ]
  )

  app.serve() or { panic(err) }
}

All of the features are documented on the official documentation so make sure to give it a check.

Quick start

Get started with your first Mantis web app by following our Quick Start guide!

A note on type safety

V offers first-party support for Result/Option types.

These types are data representation of an outcome that can fail or succeed (Result), or an outcome that can be found or not (Option, often called Maybe in other programming language).

For example, here is how this patterns is used when getting route parameters:

module main

import khalyomede.mantis.http { create_app, App, Response }
import khalyomede.mantis.http.route

fn main() {
  app := create_app(
    routes: [
      route.get(
        name: "post.show"
        path: "/post/{id}"
        callback: fn (app App) !Response {
          id := app.route_parameter("id") or {
            return app.response.html(content: "Post not found")
          }

          return app.response.html(content: "Showing post ${id}")
        }
      )
    ]
  )

  app.serve() or { panic(err) }
}

Why another framework?

My background includes building web apps with Laravel (PHP) and Javascript.

Throughout my career, I encountered the limitations of Object Oriented Programming and discovered the elegance of Functional Programming. This led me to appreciate concepts like exhaustive pattern matching, Abstract Data Types, and explicit code that prevents uncaught exceptions.

I began searching for tools that could catch bugs at compile time rather than in production. After exploring many modern programming languages, I found my match in V's simplicity and reliability.

Mantis combines the productivity I enjoyed with other frameworks with V's advantages.

I hope this project helps others discover V's benefits and build more reliable applications, bringing back the joy of simple programming.

Mantis aims to help you focus on business needs by providing good defaults while maintaining long-term code maintainability.

We intentionally avoid complex patterns, staying light on opinions. You won't find Repositories or ORMs here (though we plan to add a database-specific query builder - see our roadmap), keeping the framework simple yet effective.

Veb

Veb is V's official web framework, offering different features from Mantis:

Compile-time type-checked HTML pages
Built-in support for controllers
An integrated ORM with database migrations
Static file handling
HTTP middlewares
More mature features and security than Mantis currently offers

Consider reviewing Veb's documentation to determine which framework better suits your needs.

Conclusion

I hope this introduction has piqued your interest in this fresh approach. While some may question it, others might find it intriguing, and hopefully, some will give it a try.

Feel free to explore more at khalyomede.github.io/mantis and share your thoughts in the comments!

Join us on the V Discord where I'll be happy to answer your questions!

Your ideas, suggestions, and bug reports are welcome in our issue tracker - every contribution helps!

Happy coding!

Make a web app installable in a breeze

Anwar — Mon, 13 Nov 2023 22:48:47 +0000

Welcome to this tutorial on making your web app installable in a few simple steps.

Summary

What is a progressive web app?
Defining a web app manifest
Registering a service worker
Show an install button
Conclusion

What is a progressive web app?

For a web app to be considered installable, a Progressive Web App (PWA), it must adhere to several criteria:

It must define a manifest describing how the app behaves and interacts with the UI.
It should register a Service Worker to enable offline browsing.
It needs to have a responsive design suitable for small devices.

Other secondary criteria exist, but we'll focus on the essential information here.

Defining a web manifest

Start by adding a "manifest.json" file to your project's root:

{
  "name": "Dev.to",
  "short_name": "DEV",
  "start_url": "/",
  "display": "standalone",
  "icons": [
    {
      "src": "images/touch/homescreen48.png",
      "sizes": "48x48",
      "type": "image/png"
    }
}

The "start_url" determines the URL shown when launching the app.
The "display" specifies how the browser renders the UI when launching the app.

Refer to the manifest MDN documentation for a comprehensive list of configuration options..

Include the manifest file in your HTML:

<!DOCTYPE html>
<html>
  <head>
    <!-- ... !-->
    <link rel="manifest" href="manifest.json" />
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

Registering a service worker

Service Workers introduce powerful caching patterns for fine-grained control over how the browser handles requests. Let's implement the simple Network First pattern using Workbox.js.

This pattern tells the browser:

If you encounter a resource, wether it be an image, an HTML document, or anything, if the connectivity is on, grab the content of the resource from the server and store it in the cache.

If the network is off, and the resource is present in the cache, grab it from there, else behave like usual.

You can learn more on all the various caching strategies on the Workbox.js documentation about caching strategies.

Install the library:

npm install workbox-core workbox-routing workbox-strategies

Create a "service-worker.js" file:

const { clientsClaim } = require("workbox-core");
const { registerRoute } = require("workbox-routing");
const { NetworkFirst } = require("workbox-strategies");

clientsClaim();

registerRoute(
    /.*/u,
    new NetworkFirst({
        cacheName: "nf-v1",
    })
);

Update the "app.js" entry point to start the service worker:

if (navigator.serviceWorker instanceof ServiceWorkerContainer) {
    navigator.serviceWorker.register("/service-worker.js", { scope: "/" });
}

Include the script in your HTML:

<!DOCTYPE html>
<html>
  <head>
    <!-- ... !-->
    <link rel="manifest" href="manifest.json" />
  </head>
  <body>
    <!-- ... -->
    <script type="text/javascript" src="app.js"></script>
  </body>
</html>

Show an install button

To make your web app more discoverable, register it on Store.app. This platform can increase your app's visibility, and they provide a convenient install modal.

An app store for web apps

Anwar ・ Oct 22 '23

#productivity #web

Install the NPM package:

npm install @storedotapp/pwa-install-dialog

Import the code in your main entry javascript file:

require("@storedotapp/pwa-install-dialog");

if (navigator.serviceWorker instanceof ServiceWorkerContainer) {
    navigator.serviceWorker.register("/service-worker.js", { scope: "/" });
}

Add a button to your HTML for users to install the app:

<!DOCTYPE html>
<html>
  <head>
    <!-- ... !-->
    <link rel="manifest" href="manifest.json" />
  </head>
  <body>
    <button id="install-button">Install the app</button>    

    <pwa-install-dialog id="install-dialog" app="fitness-app" theme="dark"></pwa-install-dialog>

    <script type="text/javascript" src="app.js"></script>
  </body>
</html>

require("@storedotapp/pwa-install-dialog");

if (navigator.serviceWorker instanceof ServiceWorkerContainer) {
    navigator.serviceWorker.register("/service-worker.js", { scope: "/" });
}

document.addEventListener("DOMContentLoaded", () => {
  const button = document.getElementById("install-button");

  if (button instanceof HTMLButtonElement) {
    button.addEventListener("click", () => {
      const dialog = document.getElementById("install-dialog");

      if (dialog instanceof HTMLElement) {
        dialog.show();
      }
    });
  }
});

Conclusion

In just a few lines of code, we've transformed a website or web app into an installable web app. The evolution of the web into a platform with capabilities rivaling native apps is truly fascinating.

Installable web apps are shaping the future for a seamless, unified experience across all devices, offering lightweight, capable, and rich applications.

One limitation with the actual setup is that our app will still display the "install the app" button even if the app is installed (e.g. displayed as a standalone app).

Let us improve it by hiding the button if the app is already installed.

Create an "app.css" file with the following code:

@media all and (display-mode: standalone) {
  #install-button {
    display: none;
  }
}

Now, only users who haven't installed your app will see the install button.

You can see this in action as I implemented it on Predzo.

I hope this tutorial has helped you understand PWAs better and demonstrated how easy it is to create an outstanding offline-ready installable web experience.

Happy web building!

Cover image by Roberto Nickson from Pexels.

An app store for web apps

Anwar — Sun, 22 Oct 2023 20:32:50 +0000

Welcome to this article. Today, I'm excited to share my latest discovery with you: store.app. In a world increasingly dependent on web applications, this platform is a game-changer.

Summary

An app store for web apps
What is an installable web app?
The impact on the web ecosystem
Conclusions

An app store for web apps

store.app is a project backed by PWA Labs lead by Morgan Bender and its team.

The concept is simple to understand: it acts as a hub for content creator to publish their web apps, and for web users to find them.

Web apps are categorized by labels (AI, Games, Crypto, ...). You can filter only on installable web apps as well (more on this later).

Developers can register on the platform and start publishing their web apps in a few minutes. The whole process is smooth and satisfying (I personally published Predzo, a collaborative shopping list app).

Store.app will then proceed with an automated scan of the published website to extract various meta data like the icon and images and other basic information. It will also perform a Google Lighthouse scoring test to be displayed for users that search for your app. If you web app is installable, it will also display a badge beside the name of your app.

What is an installable web app?

A few years ago, web browsers started to support the PWA standard. Progressive Web Apps become more and more supported, and the web gets new capabilities, closing the gap between native apps and web apps.

New APIs come to the light, like the Geolocation API, Notification API, Bluetooth API, and many more.

When we talk about progressive web apps, the main things that come to our mind are:

It feels like a native app (thanks to the web manifest, you can instruct a web app to be displayed without the web browser UI)
It is resilient to connectivity fluctuations like a native app (thanks to the service worker that can cache whole responses and render the cached response in case of network interruption)
It can take advantage of the physical device features like a native app (you can take a look at what PWA can do today to have a glimpse of what is possible)
It adapts its UI to the device viewport, like a native app

What it means is that with a few configuration, you can turn virtually any web apps into installable apps, which helps creating a true seamless and uniform experience across devices.

The impact on the web ecosystem

The web evolved from being a simple platform to display information on a web browser to becoming the first entrypoint to finding content online.

Think about the last time you installed an app on your smartphone. Was it last month? Maybe last year?

And when was the last time you used a web browser to find content online? Probably a few minutes ago if you read these lines.

The point is that the web is the dominant hub for finding and interacting with the world. And big actors have understood this which explains the effort put to push installable web apps as a first-class citizen of the web.

In this picture, store.app plays a unique role by orchestrating the efforts into a single source of information. It become easier to find the next great app that will help you get more productive, have more fun, or discover new opportunities.

The impact will also go beyond the web frontier, as it will tighten the gap between websites and users by increasing the engagement: imagine getting native notifications from dev.to, just after you browsed it and registered.

Installable web apps also offer killers features that more and more users will find convenient:

They take way less space on the device (for example, the web Twitter app is 0,30 MB, the native Android app is more than 30 MB)
They do not require manual updates (the server automatically serves the most up-to-date version of the app), which reduces frictions and also helps consuming less space in the device
They get installed in a few seconds, which also reduce the bounce rate and increase the engagement opportunities

Conclusions

I always was a web enthousiast, since as much as I can remember. When I started studying computer science 10 years ago, I immediately knew I would become a web developer.

The instant feedback loop and the ease of use was amazing and I knew this was the future of digital interactions.

I'm thrilled to have bet on the right horse with the advent of Progressive Web Apps (PWAs). It's evident that all signs point to a future of seamless web experiences.

I always wanted to create a web app store (I even still have the project idea on my Google keep!), and once I found store.app, it was a relief to know other people also care about the same goal I have, and also great to know there is now a solid team toward this effort of bringing the best of the web.

Store.app is a promising venture that holds the potential to reshape the web ecosystem. Its dedication to making web apps more accessible and user-friendly is commendable. I encourage you to explore this platform and join us in making the web a better place.

Last one for fun, take a look at what installable web apps look like on an Ubuntu!

In the order of display (on the left):

Google chrome (desktop app)
Firefox (desktop app)
Folder (desktop app)
VSCode (desktop app)
Twitter (PWA)
Youtube (PWA)
Predzo (PWA)
Google Keep (PWA)
Draw.io (PWA)
Whatsapp (PWA)
Store.app (PWA)

I look forward to hearing your thoughts on this exciting future. Happy web browsing 🛰️

Should you use an enum column or a table to store allowed values in SQL?

Anwar — Tue, 10 Oct 2023 21:44:59 +0000

Hello and welcome to this article when I would like to discuss in reaction to a great video released by Aaron (Youtube, Twitter) on Database enums for PlanetScale.

Summary

The use case: invoicing statuses
First problem: editing the name of a status
Second problem: ordering
Third problem: adding "meta data" is harder
The solution: reference tables
Conclusions

The use case: invoicing statuses

To setup the stage, let us say you create a platform to put in relation developers and customers. You want to allow developers to generate invoices from their account.

Our "invoices" table contains a "status" column. The equivalent SQL code for this column would be the following:



CREATE TABLE invoices (
  ...
  status ENUM('draft', 'generated', 'sent', 'paid', 'cancelled')
);

First problem: editing the name of a status

Let us imagine the naming of "cancelled" is not clear enough, and must be changed for "aborted" to really understand the invoice payment is abandonned.

Let us also imagine you already have a bunch of invoices that are tagged as "cancelled" in your table.

id	developer_id	number	status
1	1	000001	cancelled
2	1	000002	paid
3	1	000003	sent

At this point, you cannot "simply" change the name of the enum, because SQL uses it as an identifier (much like a foreign key) and because of it you are not allowed to alter a value that is already bound to a record in the table.

The best you could do is to:

Add a new value "aborted"
Run a query to move all "cancelled" status to "aborted"
Delete the enum value "cancelled"

Which is a little bit cumbersome for "just" a naming change.

Second problem: ordering

As highlighted by Aaron on the video I mentioned in the introduction of this article, ordering by the status of the invoice will not use a text-based sorting algorithm.

At the creation step, MySQL has associated each values to an integer (starting from 1).

value	index
draft	1
generated	2
sent	3
paid	4
cancelled	5

If we would have added the enum values in a different orders, the indexing would be different, which creates an unpredictible outcome when we sort the invoices by their statuses (to some extent).

Third problem: adding "meta data" is harder

Since by design each enums items represents both the value and the identifier, it is harder to add more data around them.

To show this limitation, let us first agree on the possible values an invoices can take before being considered "completed".

In practice this means we cannot go from "paid" to "cancelled", they are final statuses.

With an enum value, we cannot really add this information easily. We would either have to add a "final_status" boolean column alongside the "status" enum, which would be a computed virtual column. Again, this seems cumbersome.

The solution: reference tables

Let us recap all the issues we encountered with enums:

The name is not easily editable if it has been bound to an existing record
Ordering is less predictible/not obvious
Adding meta data requires more attention

To solve this issues, one could think of modelizing allowed values by using a reference table instead.

References tables have the same advantage have enums, meaning you cannot create an invoice with an invoice_status_id that is not part of the reference table: you have the same safety level as enums (as long as you carefully use a foreign key).

If you need to order over the invoice_status_id, it is obvious and clear what will be the expected order. You can even go further and create an order column in the invoice_statuses table if you want to allow back office users to change the order of each allowed values independently.

If you do that, it also shows how easy it is to add "meta data" around your values. As you can see in the diagram, we added the concept of "is_final" pretty easily. Not virtual column needed, just a boolean column that represent if the value is final or not (and no data redundancy, good for Database normalization).

Lastly, if you want to change the name of a status, it is just one step (versus 3 steps if you would have an enum column).

Conclusions

In this article we have seen that enums columns are useful for light/simple need of having a list of allowed values that will not vary in the future.

However, as a future-proof solution, they seem to be rapidly limited and cause a lot of issues when we need something more flexible and evolutive.

As a solution, references tables are a good way to keep all the safety of enums, with a lot of advantages when it comes to add more descriptive / meta data around the values. It is also more easy to edit names and there is a clear separation between the identifier and the name.

References tables are personally my go-to tool when it comes to add references values.

One could say this adds more tables and "complexifies" the modelization, but to me the number of tables is not affecting the performance of queries by a significant factor.

For purists, one last case in favor of references table would be if you allow developers to manually change the status of an invoice (warning: changing the status of an invoice manually is not advised, do not try this at home!).

With an enum column, the name is also the identifier.



<select name="status">
  <option x-for="status in statuses" :value="status">{{ status }}</option>
</select>

The drawback, because the name and the identifier are one, is that if you want to display "Aborted" instead of "Cancelled", you will have to store the change as a data in the application layer, which is another cumbersome step to do. Also think of the translations that you now have to manage...

If you have a clear separation between the identifier and the name, you could easily change the name on the table, and your front code is still the same as below no matter what.



<select name="status">
  <option x-for="status in statuses" :value="status.id">{{ status.name }}</option>
</select>

Now, since status.name comes from your API endpoint, you can do the naming change without changing the status.id, which gives you more flexibility and reduce the maintenance front-side.

I hope this article gave you another point of view when it comes to modelize a list of allowed values in your database. Make the good choice, and happy database modelization!

Cover image by Lukas from Pexels.

Database or Business first approach for problem solving?

Anwar — Tue, 26 Sep 2023 20:29:17 +0000

Hello and welcome to this post which is a little bit more of a water cooler according to what I usually post here.

Today I would like to react and discuss with you about an interesting post I found on X made by Andrew Sherman.

The question
Feedback on the answers
What I thought during my early days as an engineer
What I think today
A solution to a business problem
Predzo: my personal playground
Conclusion

The question

Scrolling on X, I found Andrew asking the following question to his followers.

When you start working on a backend, do you prefer business logic first or database modeling first?

The audience is tech, and after I scrolled over a dozen of answers, I made a small summary over the 58 comments I passed through.

16 were for the "Business logic" first approach
42 were for the "Database modeling" first approach

Feedback on the answers

I can pull two category of answers:

The people that strongly believe one way or another
The more nuanced people, that are unsure of which approach is the best

The last category is a minority. I am not surprised that overall people are quite sure of themselves about this question, because they might already have some experiences implementing it in their work place or on a personal project.

What I thought during my early days as an engineer

I work on the tech field since 2013 and I had many tech opportunities including working for several companies.

If you would have asked me this question back in the time, I would have answered to go "Database first" as it is the most obvious choice for me.

When you think about what comes first when building a feature or a project from scratch, the data storage layer is our first thought. Choosing a good storage medium can have a big impact on how the feature will be conceived.

While this is a natural way of solving a problem, by laying down a database schema and identifying the culprit and opportunities, I think this is reducing our range of action.

What I think today

Before working on my current company, I always had a tech-first approach, and most of the solution I built was decided by engineers. While it was working pretty well, I could defintely see the limits of this approach.

Because of this, we could totally miss the point and put a lot of efforts on something that the end user would probably not find as useful as we would as tech engineers.

The first time I changed the way I solved problem was a little bit after I was hired in for my current position. I discovered the concept of a "product team".

This team was dedicated to understand the user need, and translate it in stories/features. We, as a tech team, would then work closely with the product team to deliver values to the end user.

Suddenly, everything made sense for me. I finally could put words on the feeling I had back then when I felt something was wrong with the way we would solve problems: we missed to put the user at the center of the solution.

A solution to a business problem

For the first time since I started my career, I have the feeling to really contribute and make my company progress to deliver a higher value to our customer.

Isn't it what we strive for a engineers? Finding solutions to real world problems encountered by real humans like us?

When you put the business as a first-class citizen in your way of solving problems, the path gets so much clearer. You instinctively evacuate any superfluous thought or overkill solutions to just focus on how to solve the business problem.

This is why if I should give my point of view now, I would go for the business approach first.

Predzo: my personal playground

2 years ago, as I was usually responsible for doing the groceries in my family, I always would struggle to gather the list of each of my family members.

Some would give me their list in the form of WhatsApp messages, cluttered between other unrelated messages, some would send me last minutes SMS for their articles they forgot to add on WhatsApp, some would copy/paste their Google keep list. In the end, it was a nightmare to not forget something and keep track of what was already in my cart.

To solve this problem, I first tried to lay down the need (my need so to speak). I needed an app that :

could manage grocery lists
could help keep track of what is checked/in my cart
could allow to share grocery lists and ease the collaboration
could be usuable on any devices (responsive)

I started to wonder in Google and made a list of potential apps I could use. Unfortunately, I could not find one that would fit all my criterias.

I decided to take advantage of this opportunity to bullet-proof the business approach.

Instead of starting with a database schema, I started to sketch the UI. I made all the pages with Bootstrap 5 and static HTML to draw the user journey.

Only at this moment, I could start iterate until I was satisfied with the user story, that would hopefully check all the criterias I laid above.

It took me a month working on my spare time the night and on week-ends, and when I was statisfied, I started to split all the user journey into tasks on Trello.

Each tasks would consists of:

The data persistance layer
The UI
The business rules

2 years later, Predzo is on production, and I can confidently say starting with the business empowered me and helped me focus on the essential and move at a good pace, instead of polluting me with technical, overengineered solutions.

Conclusion

My general thought about working as a web developer is that when you start switching your point of view about how you approach problems, it feels like you climb above the cloud: everything gets clearer.

Of course this clarity also came after I have experienced and made mistakes. I defintely think I would not understand why the business approach is the real long-term sucessful way of solving issues if I would not had experienced the other way first.

Bottom of the line, my mindset now is that we are engineers, puting technical solution at the service of users. The tech is just the tool.

This does not mean we should stop having tech conversation. It just means we can think about which tech solution to use once the user story is clear. Assuming for the user what the need will be is a sign the need is not clear and it is worth spending more time understanding it rather than pushing a solution nobody will find useful.

I hope this kind of post will make you re-think or challenge the way you approach your new problems in the future. I would also like to know what do you think about this subject. Let me know in the comments down below.

See you later and happy business problem solving!

Cover image by fauxels on Pexels.

Reinforce the type safety of your PHP arrays

Anwar — Sun, 13 Aug 2023 20:28:08 +0000

Welcome to this post where I will show you how to bring more type safety to your arrays in PHP.

Summary

What is the problem?
Typing our items
Using objects as type safe array
Conclusion

What is the problem?

In my experience it is very rare to have list of multiple type of data within an array. Most of the time, we want to have a list of something.

use App\Services\User;

$cards = (new User())->getSavedCreditCards();

print_r($cards);

[
  [
    "id" => "YTZERT37RR3TR7",
    "type" => "amex",
    "lastFour" => "0826",
    "expiry" => [
      "month" => "04",
      "year" => "2024",
    ],
  ],
  [
    "id" => "83E38Y38YF8FYF3",
    "type" => "visa",
    "lastFour" => "1162",
    "expiry" => [
      "month" => "02",
      "year" => "2023"
    ],
  ],
]

Let us imagine the UserService takes data from our configured payment service provider of choice, and this is actually the raw response that is returned on the UserService::getSavedCreditCards().

There is several problem having to deal with this kind of response:

You are exposed to "undefined array key..." errors
Your IDE cannot help you know what is the key name (if you will have to go on the source code to find the array shape, if you are lucky and it is not burried inside the PSP vendor code)
It is not guaranteed the array will only contain a list of stored cards

Typing our items

In this example objects would help convey more information in the code and bring type safety.

Let us start with a basic object representing a credit card.

readonly class Card
{
  public function __construct(
    public string $id,
    public CardType $type,
    public string $lastFour,
    public CardExpiry $expiry,
  ) {}
}

readonly class CardExpiry
{
  public function __construct(
    public string $month,
    public string $year,
  ) {}
}

enum CardType: string
{
  case AmericanExpress = "amex";
  case Visa = "visa";
  case MasterCard = "mastercard";
}

Now we could stop there and create an array of Card.

$cards = [
  new Card(
    id: "YTZERT37RR3TR7",
    type: CardType::AmericanExpress,
    lastFour: "0826",
    expiry: new CardExpiry(
      month: "04",
      year: "2024",
    ),
  ),
  new Card(
    id: "83E38Y38YF8FYF3",
    type: CardType::Visa,
    lastFour: "1162",
    expiry: new CardExpiry(
      month: "02",
      year: "2023",
    ),
  ),
];

At this point, nothing prevents us from adding something else than a Card in this array. It is time to introduce "array objects".

Using objects as type safe array

Let us start with a class that holds a list of Card.

class Cards
{
  private array $cards;

  public function __construct()
  {
    $this->cards = [];
  }
}

To be able to push values to an object as if it was an array, let us implement the ArrayAccess interface.

class Cards implements ArrayAccess
{
  private array $cards;

  public function __construct()
  {
    $this->cards = [];
  }

  // Array access methods
  public function offsetExists(mixed $offset): bool
  {
    return isset($this->cards[$offset]);
  }

  public function offsetGet($offset): ?Card
  {
    return $this->cards[$offset] ?? null;
  }

  public function offsetSet(mixed $offset, mixed $value): void
  {
    if (!$value instanceof Card) {
      throw new InvalidArgumentException("Expected parameter 2 to be a Card.");
    }

    $this->cards[$offset] = $value;
  }

  public function offsetUnset($offset): void 
  {
    if (isset($this->cards[$offset])) {
      unset($this->cards[$offset]);
    }
  }
}

Now we can safely push Card into the array.

$cards = new Cards();

$cards[] = new Card(
  id: "YTZERT37RR3TR7",
  type: CardType::AmericanExpress,
  lastFour: "0826",
  expiry: new CardExpiry(
    month: "04",
    year: "2024",
  ),
);

$cards[] = 1; // Uncaught InvalidArgumentException: Expected parameter 2 to be a Card.

To be able to loop through the array, we need to implement another built-in interface.

class Cards implements ArrayAccess, IteratorAggregate
{
  private array $cards;

  public function __construct()
  {
    $this->cards = [];
  }

  // Iterator aggregate methods
  public function getIterator(): ArrayIterator
  {
    return new ArrayIterator($this->cards);
  }

  // Array access methods
  public function offsetExists(mixed $offset): bool
  {
    return isset($this->cards[$offset]);
  }

  public function offsetGet($offset): ?Card
  {
    return $this->cards[$offset] ?? null;
  }

  public function offsetSet(mixed $offset, mixed $value): void
  {
    if (!$value instanceof Card) {
      throw new InvalidArgumentException("Expected parameter 2 to be a Card.");
    }

    $this->cards[$offset] = $value;
  }

  public function offsetUnset($offset): void 
  {
    if (isset($this->cards[$offset])) {
      unset($this->cards[$offset]);
    }
  }
}

And now we can loop through our cards.

$cards = new Cards();

$cards[] = new Card(
  id: "YTZERT37RR3TR7",
  type: CardType::AmericanExpress,
  lastFour: "0826",
  expiry: new CardExpiry(
    month: "04",
    year: "2024",
  ),
);

foreach ($cards as $card) {
  echo $card->expiry->month;  // "04"
}

Conclusion

This "array object" is the equivalent of a "Set" in other language: it ensures the list have a consistent type across all its items.

One downside is that this check is done at runtime (unless you keep reading). The PHP interpreter will not natively understand your $cards array is a list of Card. Your IDE will still consider $card as a mixed. The last trick is to use the assert() function to give an extra help to your IDE.

foreach ($cards as $card) {
  assert($card instanceof Card);

  echo $card->expiry->month;  // "04", IDE autocompletion works
}

Static analysis tools would prevent you from assigning an int to the lis of Card, with some extra PHPDoc blocks.

/**
 * @implements ArrayAccess<int, Card>
 * @implements IteratorAggregate<int, Card>
 */
class Cards implements ArrayAccess, IteratorAggregate
{
  // ...
}

$cards = new Cards();

$cards[] = 1; // PHPStan will prevent you from doing this now

You can try what PHPStan tells you online with this pre-filled example.

Now you can ensure type consistency across your lists, which gives an extra layer of safety, and can be a great ally when working in teams.

At some point I hope this article will be deprecated in favor of generics within PHP. A proposal already thrown the basis for something like this.

$cards = array<Card>();

$cards[] = new Card(...);
$cards[] = 1; // Both PHPstan and PHP would throw

In the mean time, I hope you will leave with some ideas to make your code base more robust. Thank you for reading!

Happy type hardening 🛡️

Cover image by Pixabay.

My routine to update my PHP packages

Anwar — Thu, 20 Apr 2023 21:10:00 +0000

Welcome to this new article where I will show you and explain how I update my PHP package on a Laravel app weekly.

Summary

Why upgrading periodically
My versioning policy
The setup
Conclusion

Why upgrading periodically

Two main reasons come to my mind.

First, to keep my app free of any possible bugs. Since I will rely on a dozens of packages, and I choose the packages that are most likely to be maintained over time, it may happen the maintainer found a performance or feature issue and has fixed it already.

Second, this helps me do major versions upgrade easily since I would have done most of the migration path (upgrading to the latest minor version), which may have already introduced deprecations to follow to ease a major version upgrade.

My versioning policy

When I work on an app that is "closed source" (like Predzo), I lock every packages to their exact version.

By that I mean instead of installing a package like this

composer require google/recaptcha

I will force Composer to install an exact version

composer require google/recaptcha:1.3.0

I had some situations when a package would introduce a breaking change as a minor/fix update (even had one time occuring on a Laravel minor change). Since then, I got used to just lock the exact version in order to be in peace when installing the same dependencies on my production server.

I also do the same for NPM packages

npm install --save-dev --save-exact @sentry/browser@7.48.0

I know this will not prevent dependencies of my direct dependencies from being updated on another version (since my direct dependencies do not freeze their own dependencies to the exact versions), but at least it helps mitigate this issue on direct dependencies.

Also, since I work in a "continuous deploy" manner, features that I finish will never last more than a day or two before being pushed on production. This limits the risks of having too much differences.

The setup

I rely on a Github Action to run the command composer outdated --strict --direct on a CI. This means whenever I complete a ticket and I am ready to push it, if the dependencies are not up-to-date, my merge request will not pass the tests.

Composer

{
  "scripts": {
    "check-updates": "composer outdated --strict --direct"
  }
}

composer run check-updates

The --strict option will make the command to return a non-zero code to the console if at least one dependency is outdated.

The --direct option instructs Composer to only check on direct dependencies (the ones in composer.json). Without this option, it would also check on dependencies of my direct dependencies.

NPM

{
  "scripts": {
    "check-updates": "npm outdated"
  }
}

npm run check-updates

Out of the box, npm outdated returns a non-zero code by default if at least one dependency is outdated. It also only scans direct dependencies by default.

When some dependencies are outdated, this is my routine:

I open the repository on Github
I read the changelog
I copy the latest version from the command output

So for example if jawira/case-converter, league/flysystem-aws-s3-v3 and laravel/cashier are outdated, I will run this command:

composer require jawira/case-converter:3.5.1 league/flysystem-aws-s3-v3:3.13.0 laravel/cashier:14.11.0

Finally, I run my tests to ensure nothing have been broken in the process of upgrading dependencies.

This whole process ensures everytime I will work on features, if dependencies are not up-to-date, I will also take the opportunity to update my dependencies.

Conclusion

As you can imagine, I never run composer update. I always check the changelog of my dependencies, and install the exact version. This has multiple benefits:

I force myself to actually read the changelogs, most of the times there is precious information on deprecations upgrade guides or new interesting undocumented features
I do not accidentally upgrade a dependency that could potentially introduce a breaking change
There is a satisfying feeling when composer outdated returns 0 outdated dependencies
I stay up-to-date weekly (or sometimes several times per weeks if I have the occasion to work on Predzo more often)

One drawback to this is it relies on a strong code coverage and tested code base as you want to be sure nothing breaks when upgrading so often. I would not advice to do this on a project with a little test coverage.

Another one is I noticed upgrading major versions takes a bit more time (I did 2 majors upgrade on Predzo, from Laravel 8 to 9 and from Laravel 9 to 10). This is because I have to run a complete command including all the dependencies and their latest version at a single time. If I do not do it, Composer will tell me my version is too strict to upgrade packages.

However this is mitigated as I do not have too much to figure out since I normally upgrade packages to the latest minor versions possible so the gap is not that big most of the time.

So far, after 2 years working on my app and experimenting with this setup, I am pretty happy with it and I can confidently say I feel safer with this process in the sense I know my dependencies are the closest possible between my local and production environment.

To finish, I have done a poll on Twitter (follow me) and noticed most of the time people will choose to upgrade their dependencies only when a major version is released. I think it is a pity when we know how hard maintainers work to keep their packages performant and bug free. Starting to upgrade more often could lead in potentially safer and more secure products.

I hope this article gave you an interesting point of view regarding package upgrades! Let me know in the comment section what do you think about it.

Happy package upgrades!

Cover photo by Yulianto Poitier from Pexels.

Rely on Laravel's Authorization as much as possible

Anwar — Thu, 13 Apr 2023 21:58:00 +0000

Hi and welcome to this article where I will show you the benefit of Laravel's Authorization features and why it is important to stick to it as much as possible for everything related to access control.

Summary

Authorization preview
Example: adding another authorization layer
The mistake: mixing authorization layers
Conclusion

Authorization preview

Laravel offer an elegant way to perform access control verification within your app.

Let us say you build a tech news platform where your users can contribute by posting articles. Your users can create and edit blog posts.

The route to edit a blog post is GET /post/{post}/edit and the route to save the changes is PUT /post/{post}.

Now let us imagine a malicious user have found the id of the blog post of another user, and want to edit it on behalf of the author. You want to prevent this from happening and here is how you can do it with Laravel's policies.

Route::middleware("can:edit,post")->group(function() {
  Route::get("post/{post}/edit", [PostController::class, "edit"]);
  Route::put("post/{post}", [PostController::class, "update"]);
});

As you can see, we instructed Laravel to protect our routes by checking if the user can edit posts (can:edit,post). Here can is a pre-registered middleware. You can view it on your route kernel file at "app/Http/Kernel.php":

namespace App\Http;

use Illuminate\Foundation\Http\Kernel as HttpKernel;

class Kernel extends HttpKernel
{
  protected $middlewareAliases = [
    // ...
    "can" => \Illuminate\Auth\Middleware\Authorize::class,
    // ...
  ];
}

This middleware assumes you either registered a Policy (which attach to an Eloquent model) or a Gate (which can be attached to anything).

Most of the time I write authorization around models, so I like to use Policies as much as possible. Here is the policy that would prevent other person than the author from editing a blog post:

namespace App\Policies;

use App\Models\Post;
use App\Models\User;
use Illuminate\Auth\Access\Response;

class PostPolicy
{
  public function update(User $user, Post $post): Response
  {
    if ($post->author->is($user)) {
      return $this->allow();
    }

    return $this->deny("Only the author can edit this post.");
  }
}

Finally, policies require you to register them to tell Laravel how it should link them automatically when using the Route middleware syntax.

On your file at "app/Providers/AuthServiceProvider.php":

namespace App\Providers;

use App\Models\Post;
use App\Policies\PostPolicy;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;

class AuthServiceProvider extends ServiceProvider
{
  protected $policies = [
    Post::class => PostPolicy::class,
  ];
}

Example: adding another authorization layer

Now let us imagine your tech news platform have a back office. You can get various statistics about how your app performs, you can view the blog post count, and other anaylitcs.

You only allow your team mates to browse this back office so you decide to use a permission system like spatie/laravel-permission.

For the moment you use two roles, "admin" and "manager". Admins can view all the back office and change the color of the website, but manager can only views pages without ability to change anything.

You protect these routes using the provided "role" middleware of this package:

Route::middleware("permission:view admin")->group(function() {
  Route::get("admin", [AdminController::class, "index"]);
]);

Route::middleware("permission:update settings")->group(function() {
  Route::get("admin/settings", [AdminSettingsController::class, "edit"]);
  Route::put("admin/settings", [AdminSettingsController::class, "update"]);
});

And on your layout, you only want to display the admin button for admins and managers:

<ul id="menu">
  @if(user()->hasPermissionTo("view admin"))
    <li>
      <a href="{{ route("admin.index") }}">Admin</a>
    </li>
  @endif
</ul>

The mistake: mixing authorization layers

For the moment our system is fine. Now we imagine admins have the ability to suspend accounts. You have added a flag on your user model for this:

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
  public function up(): void
  {
    Schema::table('users', function (Blueprint $table) {
      $table->boolean("suspended")->default(false);
    });
  }

  public function down(): void
  {
    Schema::table('users', function (Blueprint $table) {
      $table->dropColumn("suspended");
    });
  }
};

Naturally, you will create a Policy to handle it:

namespace App\Policies;

use App\Models\User;
use Illuminate\Auth\Access\Response;

class UserPolicy
{
  public function before(User $user): Response
  {
    if ($$user->suspended) {
      return $this->deny("Your account has been suspended");
    }

    return null;
  }
}

Now we hit a roadblock: our authorization logic is now spread across two systems, permissions and policies. Let us fix this by keeping the UserPolicy and ditching any mention to permissions outside this policy:

namespace App\Policies;

use App\Models\User;
use Illuminate\Auth\Access\Response;

class UserPolicy
{
  public function before(User $user): ?Response
  {
    if ($$user->suspended) {
      return $this->deny("Your account has been suspended");
    }

    return null;
  }

  public function viewAdmin(User $user): Response
  {
    if ($user->hasPermissionTo("view admin")) {
        return $this->allow();
    }

    return $this->deny("You do not have the permission to view this page.");
  }

  public function editSettings(User $user): Response
  {
    if ($user->hasPermissionTo("edit settings")) {
        return $this->allow();
    }

    return $this->deny("You do not have the permission to edit settings.");
  }
}

Then, let us change the routes to rely on Laravel's authorization system instead:

- Route::middleware("permission:view admin")->group(function() {
+ Route::middleware("can:viewAdmin")->group(function() {
    Route::get("admin", [AdminController::class, "index"]);
  ]);

- Route::middleware("permission:update settings")->group(function() {
+ Route::middleware("can:editSettings")->group(function() {
    Route::get("admin/settings", [AdminSettingsController::class, "edit"]);
    Route::put("admin/settings", [AdminSettingsController::class, "update"]);
  });

And finally, let us update the layout to use @can instead of @if()

  <ul id="menu">
-   @if(user()->hasPermissionTo("view admin"))
+   @can("viewAdmin")
      <li>
        <a href="{{ route("admin.index") }}">Admin</a>
      </li>
-   @endif
+   @endcan
  </ul>

Conclusion

By sticking to the built-in capabilities of Laravel, you ensure your app is easy to maintain and to evolve in the future.

If tomorrow you want to replace "spatie/laravel-permission" by another system (or building your own), the only part of the code you will change is the ÙserPolicy.

In the first part of this article I voluntarily open a nasty security breach by assuming users could discover the blog post edit route. In reality, you want to make this hard and I advice to expose UUIDs or any hard to predict identifier in your URLs instead of /post/34/edit. I have created a package to help you do the least possible while securing your route. Check it out.

khalyomede / laravel-eloquent-uuid-slug

Use auto generated UUID slugs to identify and retrieve your Eloquent models.

Laravel Eloquent UUID slug

Summary

About

By default, when getting a model from a controller using Route Model Binding, Laravel will try to find a model using the parameter in your route, and associate it to the default identifier of the related table (most of the time, this is the "id" key).

// routes/web.php

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

// --> What you see
Route::get("/cart/{cart}", function(Cart $cart) {
  // $cart ready to be used
});

// --> What happens behind the scene
Route::get("/cart/{cart}", function(string $identifier) {
  $cart = Cart::findOrFail($identifier);

  // $cart ready to be used
});

This means if you…

View on GitHub

I hope this article helped you clarify the goal of Laravel Authorization and will help you make your app more robust. Please let me know your thoughts in the comments!

Happy access control!

Cover image by Peter Olexa.

Demystifying tests in Laravel

Anwar — Sat, 10 Dec 2022 15:39:42 +0000

Hi and welcome for another article 👋

This one will be a rapid-fire oriented post so that you can both see how easy it is to test your Laravel app, and you can refer to it whenever you want to remember how to test something.

Everytime you want to create a test, and the test class do not exist yet, just run this command.

php artisan make:test LoginTest

And you run your tests using this command.

php artisan test

Without further do, let's get into it!

Folder architecture suggestion
1. Assert a route returns response without errors
1. Assert a user is logged
2. Assert an authenticated user can perform actions
3. Assert a model has been saved after form submission
4. Assert a file has been uploaded
5. Creating a fake model with relationships
6. Assert that a session flash message is visible
7. Assert a validation error message is returned
8. Assert an authorization
9. Assert a command ended without errors
11. Assert a json content is sent
Conclusion

Folder architecture suggestion

If you have a lot of tests, naming can be challenging. To not think of it, and if your test file is focused on a controller, model, ... you can just name the file the same as the entity you test.

your-app/
├── app/
│   ├── Http/
│   │   └── Controllers/
│   │       ├── LoginController.php
│   │       └── PostController.php
│   ├── Models/
│   │   ├── Post.php
│   │   └── User.php
│   ├── Rules/
│   │   └── BarCodeValid.php
│   └── Helpers/
│       └── Color.php
└── tests/
    ├── Feature/
    │   ├── Http/
    │   │   └── Controllers/
    │   │       ├── LoginControllerTest.php
    │   │       └── PostControllerTest.php
    │   ├── Models/
    │   │   ├── PostTest.php
    │   │   └── UserTest.php
    │   └── Rules/
    │       └── BarCodeValidTest.php
    └── Unit/
        └── Helpers/
            └── ColorTest.php

1. Assert a route returns response without errors

namespace Tests\Feature;

use Illuminate\Foundation\Testing\WithFaker;
use Tests\TestCase;

class ContactUsControllerTest extends TestCase
{
  use WithFaker;

  public function testContactUsPageRendersWell()
  {
    $this
      ->get(route("contact-us.index"))
      ->assertOk();
  }
}

1. Assert a user is logged

namespace Tests\Feature;

use Illuminate\Foundation\Testing\WithFaker;
use Tests\TestCase;

class LoginControllerTest extends TestCase
{
  use WithFaker;

  public function testUserIsLoggedAfterFormIsSubmitted()
  {
    $password = $this->faker->password();
    $user = User::factory()->create();

    $this->post(route("login"), [
        "email" => $user->email,
        "password" => $password,
      ])
      ->assertValid()
      ->assertRedirect(route("dashboard"));

    $this->assertAuthenticated();
    // or
    $this->assertAuthenticatedAs($user);
  }
}

2. Assert an authenticated user can perform actions

namespace Tests\Feature;

use Illuminate\Foundation\Testing\WithFaker;
use Tests\TestCase;

class PostControllerTest extends TestCase
{
  use WithFaker;

  public function testAuthenticatedUserCanCreateBlogPost()
  {
    $user = User::factory()->create();

    $this->actingAs($user)
      ->post(route("post.store"), [
        "title" => $this->faker->sentence(),
        "content" => $this->faker->text(),
      ])
      ->assertValid();
  }
}

3. Assert a model has been saved after form submission

namespace Tests\Feature;

use App\Models\Item;
use Illuminate\Foundation\Testing\WithFaker;
use Tests\TestCase;

class ItemControllerTest extends TestCase
{
  use WithFaker;

  public function testItemSavedAfterUserSubmitsForm()
  {
    $user = User::factory()->create();
    $name = $this->faker->name();

    $this->assertDatabaseMissing(Item::class, [
      "name" => $name,
    ]);

    $this->actingAs($user)
      ->post(route("item.store"), [
        "name" => $name,
      ])
      ->assertValid();

    $this->assertDatabaseHas(Item::class, [
      "name" => $name,
    ]);
  }
}

4. Assert a file has been uploaded

namespace Tests\Feature;

use App\Models\User;
use Illuminate\Http\UploadedFile;
use Tests\TestCase;

class SettingControllerTest extends TestCase
{
  public function testUserCanUploadItsProfilePicture()
  {
    $user = User::factory()->create();

    $file = UploadedFile::fake()->file("avatar.jpg");

    $this->assertDatabaseMissing(User::class, [
      "user_id" => $user->id,
      "profile_picture" => $file->hashName(),
    ]);

    $this->actingAs($user)
      ->post(route("setting.update"), [
        "profile_picture" => $file,
      ])
      ->assertValid();

    $this->assertDatabaseHas(User::class, [
      "user_id" => $user->id,
      "profile_picture" => $file->hashName(),
    ]);
  }
}

5. Creating a fake model with relationships

namespace Tests\Feature;

use App\Models\Comment;
use App\Models\Post;
use App\Models\User;
use Tests\TestCase;

class PostControllerTest extends TestCase
{
  public function testAuthorCanEditPost()
  {
    $user = User::factory()->create();

    // Creates a post with 5 comments, each comments has 25 likes
    $post = Post::factory()
      ->for($user, "author")
      ->has(
        Comment::factory()
          ->has(Like::factory()->count(25))
          ->count(5)
      )
      ->create();
  }
}

6. Assert that a session flash message is visible

namespace Tests\Feature;

use App\Models\Post;
use App\Models\User;
use Illuminate\Foundation\Testing\WithFaker;
use Tests\TestCase;

class PostControllerTest extends TestCase
{
  use WithFaker;

  public function testAuthorCanEditItsPost()
  {
    $user = User::factory()->create();
    $post = Post::factory()->for($user, "author")->create();

    $this->actingAs($user)
      ->post(route("post.update", $post), [
        "title" => $this->faker->name(),
      ])
      ->assertValid()
      ->assertSessionHas("success", "Post updated.");
  }
}

7. Assert a validation error message is returned

namespace Tests\Feature;

use App\Models\Comment;
use App\Models\Post;
use App\Models\User;
use Illuminate\Foundation\Testing\WithFaker;
use Tests\TestCase;

class PostControllerTest extends TestCase
{
  use WithFaker;

  public function testAuthorSeeErrorIfEditingPostWithSameNameAsOneOfItsOtherPost()
  {
    $user = User::factory()->create();
    $post = Post::factory()->for($user, "author")->create();
    $name = $this->faker->name();

    Post::factory()
      ->for($user, "author")
      ->create([
        "title" => $name,
      ]);

    $this->actingAs($user)
      ->post(route("post.update", $post), [
        "title" => $name,
      ])
      ->assertInvalid([
        "title" => "The title has already been taken.",
      ]);
  }
}

8. Assert an authorization

namespace Tests\Feature;

use App\Models\Post;
use App\Models\User;
use Illuminate\Foundation\Testing\WithFaker;
use Tests\TestCase;

class PostControllerTest extends TestCase
{
  use WithFaker;

  public function testUserCannotSeePostHeOrSheDidNotCreate()
  {
    $user = User::factory()->create();
    $otherUser = User::factory()->create();
    $post = Post::factory()->for($otherUser, "author")->create();

    $this->actingAs($user)
      ->get(route("post.show", $post))
      ->assertForbidden();
  }
}

9. Assert a command ended without errors

namespace Tests\Feature;

use App\Models\User;
use Carbon\Carbon;
use Tests\TestCase;

class NotifyFreePlanEndsTest extends TestCase
{
  public function testUserCannotSeePostHeOrSheDidNotCreate()
  {
    $user = User::factory()
      ->count(15)
      ->create([
        "plan" => "free",
        "subscribed_at" => Carbon::now()->subDays(15),
      ]);

    $this->artisan("notify:free-plan-ends")
      ->assertSuccessful()
      ->expectsOutputToContain("15 users notified.");
  }
}

11. Assert a json content is sent

namespace Tests\Feature;

use App\Models\User;
use Illuminate\Foundation\Testing\WithFaker;
use Tests\TestCase;

class TaskControllerTest extends TestCase
{
  use WithFaker;

  public function testAuthenticatedUserCanCreateTask()
  {
    $user = User::factory()->create();
    $name = $this->faker->name();
    $dueAt = $this->faker->date();

    $this->actingAs($user)
      ->post(route("task.store", [
        "name" => $name,
        "due_at" => $dueAt,
      ])
      ->assertJson([
        "name" => $name,
        "dueAt" => $dueAt,
      ]);
  }
}

Conclusion

I hope this post gave you the motivation to start testing if you did not get used to it yet! When you feel ready, head on the Laravel Test documentation, this is a gold mine and you will find other awesome assertions.

Please also share your snippets in the comments section if you also have some quick and easy ways to test things in Laravel 🙏

Happy testing 🧪

Integrate third-party services within Laravel

Anwar — Wed, 09 Nov 2022 20:50:11 +0000

Hello everyone and welcome to this new article on Laravel.

Today I want to show you an interesting way to deal with any third-party services or external API you need to integrate in your Laravel projects.

Use case: get the user IP info
Creating the contract
Implement IpInfo as a Geolocator
Tell Laravel what is our current Geolocator
Use the Geolocator on your controller
Swapping the Geolocator
Conclusion

Use case: get the user IP info

We will start from a freshly installed Laravel project which allows user to register and authenticate to their dashboard.

On my case I will say I used Laravel Breeze to implement such feature, but it can be anything else you want (including your custom authentication logic).

The need is, everytime one user has authenticated, we want to know from where and store this information.

After a while, you found IPInfo to have all the requirement you need and a generous free plan.

Creating the contract

Laravel provides a pattern to easily "swap" between different services. For the moment it sounds opaque, so let's follow along to find out how it will help us in the long term.

We will create an interface that will describe all the feature we seek in IPInfo.

I generally try to find a verb that defines my service, so let's call this interface a "Geolocator".

Create a new "app/Contracts" folder, and create a new "Geolocator.php" file in it.



namespace App\Contracts;

use App\DataTransferObjects\Geolocation;

interface Geolocator
{
  public function locate(string $ip): Geolocation;
}

Let's break it down:

We define a "locate" method in the "Geolocator" interface
This method must take a string representing the IP we want to scan
This method must return a "Geolocation" object

The reason we force the method to return our own representation of the geolocation of the IP is for any future implementation to stick with this constraint so we do not have to change anything in our code when we swap with a new implementation.

And that is the force of this pattern: easy service swapping with a minimum of code change.

For information, here is what the "Geolocation" data transfer object look like in "app/DataTransferObjects/Geolocation.php".



namespace App\DataTransferObjects;

class Geolocation
{
  private $ip;
  private $city;
  private $country;
  private $timezone;
  private $internetProvider;

  public function __construct($ip, $city, $country, $timezone, $internetProvider)
  {
    $this->ip = $ip;
    $this->city = $city;
    $this->country = $country;
    $this->timezone = $timezone;
    $this->internetProvider = $internetProvider;
  }

  public function ip()
  {
    return $this->ip;
  }

  public function city()
  {
    return $this->city;
  }

  public function country()
  {
    return $this->country;
  }

  public function timezone()
  {
    return $this->timezone;
  }

  public function internetProvider()
  {
    return $this->internetProvider;
  }
}

Implement IpInfo as a Geolocator

Let us create a new implementation of Geolocator.

First, let us install the package (IPInfo Github page):



composer require ipinfo/ipinfo

Next, we will create a config file to store our secure token (available once you create an account on the official website). Let us create a file "config/ipinfo.php" with this content.



return [
  "access_token" => env("IPINFO_ACCESS_TOKEN"),
];

And let us add the dot env variable on our file ".env".



...

IPINFO_ACCESS_TOKEN=your-secure-token-here

I like to store implementations on a "Services" folder. Create a folder "app/Services/Geolocator", and add a new "IpInfo.php" file within it:



namespace App\Services\Geolocator;

use App\Contracts\Geolocator;
use App\DataTransferObjects\Geolocation;
use ipinfo\ipinfo\IPinfo as BaseIpInfo;

class IpInfo implements Geolocator
{
  public function locate(string $ip): Geolocation
  {
    $ipInfo = new BaseIpInfo(config("ipinfo.access_token"));

    $details = $ipInfo->getDetails($ip);

    return new Geolocation($ip, $details->city, $details->country, $details->timezone, $details->org);
  }
}

Tell Laravel what is our current Geolocator

Let us wrap up and instruct Laravel to "bind" our Geolocator to our current implementation. This is done on the "AppServiceProvider" file available by default on "app/Providers/AppServiceProvider.php".



namespace App\Providers;

use App\Contracts\Geolocator;
use App\Services\Geolocator\Ipinfo;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
  public function register()
  {
    $this->app->bind(Geolocator::class, IpInfo::class);
  }

  public function boot()
  {
    // ...
  }
}

Use the Geolocator on your controller

Let us now find the user geolocation right after logged on the app.

Using Laravel Breeze, this is done on the "AuthenticatedSessionController" controller, so let us head into this file and intercept the moment just before redirecting to the dashboard.



namespace App\Http\Controllers\Auth;

use App\Contracts\Geolocator;
use App\Http\Controllers\Controller;
use App\Http\Requests\Auth\LoginRequest;
use App\Providers\RouteServiceProvider;
use Illuminate\Http\Request;
use Illuminate\View\View;

class AuthenticatedSessionController extends Controller
{
    public function create(Request $request)
    {
        // ...
    }

    public function store(LoginRequest $request, Geolocator $geolocator)
    {
        $request->authenticate();
        $request->session()->regenerate();

        $ip = $request->ip();

        // Here is where we get the geolocation       
        $geolocation = $geolocator->locate($ip);
        $contry = $geolocation->country();

        // Save the country on a separate table linked to the user for example...

        return redirect()->intended(RouteServiceProvider::HOME);
    }

    public function destroy(Request $request)
    {
        // ...
    }
}

If you notice, I did not add "IpInfo" class on the method parameter, but the contract. And yet, Laravel was able to give me an instance of the IpInfo class.

This is the power of Laravel: the ability to inject dependencies and resolve them on controller parameters (more on this on the conclusion).

Swapping the geolocator

Let us imagine some months have passed, and your app is a big success!

You want to find a cheaper geolocation service, and you found IP API to suit your needs.

Thanks to our system, swapping them will just require you to do 2 things:

To create an implementation of IP API as a "Geolocator"
To ask Laravel to load IP API as your current Geolocator

Let us create the "IpApi.php" file under "app/Services/Geolocator" folder.



namespace App\Services\Geolocator;

use App\Contracts\Geolocator;
use App\DTOs\Geolocation;

class IpApi implements Geolocator
{
  public function locate(string $ip): Geolocation
  {
    $response = file_get_contents("https://ipapi.co/$ip/json/");
    $location = json_decode($response, true);

    return new Geolocation($ip, $location["city"], $location["country"], $location["timezone"], $location["org"]);
  }
}

Let us change our current implementation in "app/Providers/AppServiceProviders.php".



  namespace App\Providers;

  use App\Contracts\Geolocator;
- use App\Services\Geolocator\IpInfo;
+ use App\Services\Geolocator\IpApi;
  use Illuminate\Support\ServiceProvider;

  class AppServiceProvider extends ServiceProvider
  {
    public function register()
    {
-     $this->app->bind(Geolocator::class, IpInfo::class);
+     $this->app->bind(Geolocator::class, IpApi::class);
    }

    public function boot()
    {
      // ...
    }
  }

Your controller code does not need to be touched at this point, which is the reason why this pattern is so powerful.

Conclusion

Let us sum up what we have done.

We defined a new concept: Geolocator
We have 2 available Geolocator: IpInfo and IpApi
At this point we currently use IpApi

All the added value resides in the ability to flexibly swap from one implementation to another, without having to do heavy refactors on our controller (or anywhere else the Geolocator is needed).

If the concept of contracts and binding (or service container) is still fuzzy for you, I highly recommand this video from Laracast (it is actually when things clicked for me, and I hope this will help you too).

Limit

One limit with the current implementation is it is not "scalable": if your app is really becoming a success, you are forcing your user to wait a few seconds before we get the response of our Geolocator, and a few milliseconds to save this info in database before actually redirecting the user to its dashboard.

In this case the preferable way would be to use Queue jobs. If you want to know more about it, I've covered it in this article

Laravel commands and queue jobs: when to use them?

Anwar ・ May 26 '22

#php #laravel #tutorial

Tests

Not only this pattern helps having a future-proof code base, but it actually also helps with testing!

Since our Geolocator is a bound (e.g. resolvable) dependency, we can ask Laravel to mock it within our tests.

Here is how to test that our ip is well saved in our "geolocations" table.



namespace Tests\Feature\Http\Controllers;

use App\Models\User;
use Illuminate\Foundation\Testing\WithFaker;
use Illuminate\Support\Facades\Hash;
use Tests\TestCase;

class AuthenticatedSessionControllerTest extends TestCase
{
  use WithFaker;

  public function testCountryIsStoredWhenUserAuthenticates()
  {
    $ip = $this->faker->ip();
    $country = $this->faker->country();
    $city = $this->faker->city();
    $timezone = $this->faker->timezone();
    $internetProvider = $this->faker->name();
    $email = $this->faker->email();
    $password = $this->faker->password();

    $this->mock(Geolocator::class)
      ->shouldReceive("locate")
      ->andReturn(new Geolocation($ip, $city, $country, $timezone, $internetProvider));

    $user = User::factory()
      ->create(["email" => $email, "password" => Hash::make($password)]);

    $this->assertDatabaseCount("geolocations", 0);

    $this->post(route("login"), [
        "email" => $email,
        "password" => $password,
      ])
      ->assertValid()
      ->assertRedirect(route("dashboard"));

    $this->assertDatabaseHas("geolocations", [
      "user_id" => $user->id,
      "country" => $country,
    ]);
  }
}

Bonus

By the way, here is a most succint way to write our Geolocation data transfer object using all the latest PHP 8.1 goodies:



namespace App\DataTransferObjects;

class Geolocation
{
  public function __construct(
    public readonly string $ip,
    public readonly string $city,
    public readonly string $country,
    public readonly string $timezone,
    public readonly string $internetProvider,
  ) {}
}

And when PHP 8.2 will be out, it will become even elegant.



namespace App\DataTransferObjects;

readonly class Geolocation
{
  public function __construct(
    public string $ip,
    public string $city,
    public string $country,
    public string $timezone,
    public string $internetProvider,
  ) {}
}

Cool huh?

Before leaving

That is all I have for today, I hope you will leave with some new ideas when implementing your next external service!

Happy third-party implementation 🛰️

You should not interrupt Laravel's exception handling

Anwar — Sat, 29 Oct 2022 13:34:00 +0000

Hi and welcome back for another article. I will give you my knowledge on my experience dealing with code that interrupt Laravel's default error handling, and how to mitigate issues that can occur when doing so.

Context
Configuring the error handler
Why try-catch alone is an issue
Solution #1: using report()
Solution #2: using rescue()
Conclusion

Context

Let us say your user is logged in its back-office, and can manage users. Your back-office user is allowed to create some users.

namespace App\Http\Controllers;

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

class UserController
{
  public function create()
  {
    return view("user.create");
  }

  public function store(Request $request)
  {
    User::create(["name" => $request->string("name")]);

    return redirect()->route("user.index")->withSuccess("User stored.");
  }
}

At some point, your database went down, and back-office users came to you and reported that they saw an "Oops - something went wrong" page.

You decide to make a custom validation error just so that users stay on the same page, and you still log the error to fix it later on.

  namespace App\Http\Controllers;

  use App\Models\User;
+ use Exception;
  use Illuminate\Http\Request;
+ use Illuminate\Support\Facades\Log;

  class UserController
  {
    public function create()
    {
      return view("user.create");
    }

    public function store(Request $request)
    {
+     try {
        User::create(["name" => $request->string("name")]);
+     } catch (Exception $exception) {
+       Log::error($exception->getMessage());
+
+       return redirect()->back()->withErrors("Unable to store the user.");
+     }

      return redirect()->route("user.index")->withSuccess("User stored.");
    }
  }

Configuring the error handler

Let us imagine your error are not only logged on log file (by default), but also sent on Sentry to help debugging easily.

By the way, here is how an error renders on Sentry.

Here is how you have configured the file app/Exception/Handler.php to do so.

namespace App\Exceptions;

use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Illuminate\Support\Facades\App;
use Throwable;

class Handler extends ExceptionHandler
{
  /**
   * A list of the exception types that are not reported.>
   */
  protected $dontReport = [
    //
  ];

  protected $dontFlash = [
    'current_password',
    'password',
    'password_confirmation',
  ];

  public function register(): void
  {
    $this->reportable(function (Throwable $e) {
      /**
       * @see https://docs.sentry.io/platforms/php/guides/laravel/#install
       */
      if (!App::environment('local') && $this->shouldReport($e) && app()->bound('sentry')) {
        app('sentry')->captureException($e);
      }
    });
  }
}

Why try-catch alone is an issue

Now that our error handler is modified, Laravel will automatically handle exception this way:

Run through all error handlers (log, Sentry)
Render the default error page ("Oops - something went wrong")

But since our code use try-catch, the exception is no longer thrown, plus we instruct Laravel to only send it on the file log.

This is where things are broken: you no longer benefit from Laravel's default error handling configuration, and the next time you want to figure out why the error was not reported to Sentry, you'll have an hard time remembering every place you interrupted Laravel's error handling.

Solution #1: using `report()`

This is the easiest, low effort solution to mitigate this issue.

Using report() is designed to help you pass the exception instance through Laravel's error handling, but without rendering any response.

In our case it's perfect because we decided to bring our custom rendering when such error occurs, so let's implement it.

  namespace App\Http\Controllers;

  use App\Models\User;
  use Exception;
  use Illuminate\Http\Request;
- use Illuminate\Support\Facades\Log;

  class UserController
  {
    public function create()
    {
      return view("user.create");
    }

    public function store(Request $request)
    {
      try {
        User::create(["name" => $request->string("name")]);
      } catch (Exception $exception) {
-       Log::error($exception->getMessage());
+       report($exception);

        return redirect()->back()->withErrors("Unable to store the user.");
      }

      return redirect()->route("user.index")->withSuccess("User stored.");
    }
  }

Next time an error is catched, it will be sent to the report error handler of Laravel, and the validation error will be return in the create user page, which preserves logging both on the log file and on Sentry.

Solution #2: using `rescue()`

This one is my favorite because the code becomes more readable.

Rescue will catch any exception that occurs, send it on the default exception handling mecanism, and allow you to return a custom value in this case.

namespace App\Http\Controllers;

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

class UserController
{
  public function create()
  {
    return view("user.create");
  }

  public function store(Request $request)
  {
    $stored = rescue(function () use ($request) {
      User::create(["name" => $request->string("name")]);

      return true;
    }, false);

    if (!$stored)
      return redirect()->back()->withErrors("Unable to store the user.");
    }

    return redirect()->route("user.index")->withSuccess("User stored.");
  }
}

As you can see, in first parameter, if the callback resolved successfully, rescue will return its value (true in this case), and if any exception was catched, it will return the second parameter value (false).

For the ones that like one liners, here is a condensed version.

namespace App\Http\Controllers;

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

class UserController
{
  public function create()
  {
    return view("user.create");
  }

  public function store(Request $request)
  {
    return rescue(function () use ($request) {
      User::create(["name" => $request->string("name")]);

      return redirect()->route("user.index")->withSuccess("User stored.");
    }, function () {
      return redirect()->back()->withErrors("Unable to store the user.");
    });
  }
}

One important note is that rescue() will catch any exception that occurs, so if you have the need to send a specific message for a given exception, rescue() will not be suited and you should probably opt for using the 1st solution.

namespace App\Http\Controllers;

use App\Models\User;
use Exception;
use Illuminate\Database\QueryException;
use Illuminate\Http\Request;

class UserController
{
  public function create()
  {
    return view("user.create");
  }

  public function store(Request $request)
  {
    try {
      User::create(["name" => $request->string("name")]);
    } catch (QueryException $exception) {
      report($exception);

      return redirect()->back()->withErrors("Unable to store the user because the storage system did not respond.");
    } catch (Exception $exception) {
      report($exception);

      return redirect()->back()->withErrors("Unable to store the user.");
    }

    return redirect()->route("user.index")->withSuccess("User stored.");
  }
}

Conclusion

I hope this post was useful for you and that it will help you write more solid code given this could potentially help you being more aware of errors, mostly if your error handling mecanism use different logging solutions.

There is probably a few scenarios where neither report() nor rescue() would answer the need, so let me know if you have some example on the comment section!

That is all I have for today, I hope you will leave with new perspectives in mind after reading this article.

Happy error handling 🐞