Download the PHP package liveintent/laravel-common without Composer

🧰 Laravel Common

This package contains a collection of shared helpful utilities used across our Laravel projects.

What's Included

• authentication guards and user providers
• http request logging
• notification sending via normani
• common middleware
• common macro definitions
• generator stubs for quick code scaffolding
• other cool things

Installation

You can install the package via composer:

Adding authentication to your API

LiveIntent API's usually sit behind the API Gateway. This means that when a request gets to your Laravel API, the request should come with a special, trusted JWT bearer token that identifies the user issuing the request.

To allow your Laravel API to recognize the user from this LI Token, you'll need two things. First, you'll need an authentication guard which verifies that the token is trusted and valid. Second, you'll need a user provider which can turn the LI Token into a workable User object that your API can use.

Luckily, both of these are provided for you via the LaravelCommon package.

Adding the Token Guard

Before you can switch to the LI Token guard, you'll need to register it with your app. You can do this by adding the following line to your application's AuthServiceProvider:

Now that the guard is registered, you can instruct your app to use it by editing your config/auth.php file and switching our the default API driver for the li_token driver.

However, please note that the default 'users' provider WILL NOT WORK with the 'li_token' guard, and you will need to select one of the two below user providers.

Adding the User Provider

There are two user providers provided with the LaravelCommon package. Of course, you are free to define your own, but these two should cover most cases.

Transient User Provider

The Transient user provider is meant to be used when you need to authenticate users in your API, but you do not wish to save any user information in your own database. The Transient user provider will provide your app with a workable User object that will work will all of Laravel's authentication mechanisms, but it will not persist the User into your database.

To use this provider, you'll need to first register it with your app. You can do this by placing the following line in your app's AuthServiceProvider:

After registering the provider, you'll also need to define a new provider config for it in your config/auth.php file under the 'providers' section. Here you may also define which model should be used as the User model.

Finally, we can go back to our previously defined auth guard, and instruct it to use this new li_token user provider. Modify the 'provider' of the guard's config like so:

That's it! You should now be able to make authenticated requests to your application.

Persistent User Provider

The Persistent user provider is a better choice when your app not only needs to authenticate users, but also will be storing some information alongside those users. In this case, the Persistent user provider can retrieve the relevant User object from your database, or create a new one if none was found.

To use this provider, you'll need to first register it with your app. You can do this by placing the following line in your app's AuthServiceProvider:

After registering the provider, you'll also need to define a new provider config for it in your config/auth.php file under the 'providers' section. Here you may also define which model should be used as the User model.

Finally, we can go back to our previously defined auth guard, and instruct it to use this new li_token user provider. Modify the 'provider' of the guard's config like so:

That's it! You should now be able to make authenticated requests to your application.

Customizing the persistance method

If you require even more granular control over how users will be persisted in your application, you can define a persistFromTransient method on your User model which will be used in place of the default to persist your user to the database.

The example above makes use of the upsert facility of Laravel, but you are free to define the method however you feel makes sense.

Logging HTTP requests

Upgrading from previous implementation

The AssignRequestId middleware has now been deprecated and should be removed from your project. Please see the instructions below on how to upgrade.

Logging HTTP requests with context

In your app/Http/Kernel.php, update your$middleware to include LogWithRequestContext.

Note: This middleware must be the first one in the array

You must also make sure you add the tap key and value to stderr within your config/logging.php.

Note: If you are using any other type of logging mechanism, add the same tap key/value to that as well.

Logging HTTP request summary

If you wish to add a request summary log entry, then within your app service provider, register the http logger.

Health Checks

In your app service provider, register the health checks.

This will register an http health check at '/health' and a health check for any queue workers. Additional configuration for healthchecks is available, see the implementation.

Note that the health checks are registered in the boot method of your service provider, rather than the register method.

Testing

Authentication

The LaravelCommon package provides some helpers for interacting with authentication during HTTP testing, an addition to the helpers already provided by Laravel.

You may instruct your test to 'login in as' a user by using one of the methods provided by the ActsAsUsers trait.

In the example below, the endpoint we are testing requires that the user be admin.

These methods do not persist users in the database. If you need to act as a user that is persisted in your database, you are free to use the actingAs method provided by the Laravel framework itself.

Here all the available impersonation methods:

Development

To develop this package clone this repository and install dependencies via:

When developing a laravel package, it's often useful to be able to develop your package alongside a laravel app.

With composer you can symlink the package you are developing into the dependencies of your desired project by updating your project's composer.json file.

Testing

You can run the tests via:

Linting

The installed linter will auto-format your code to comply with our agreed php coding standard.

You can run it via: