PHP (Laravel) Setup

🚀

Upgrading to v2.0?

Please see our upgrade path documentation.

🚧

Any issues?

Integrations can be tricky! Contact support if you have any questions/issues.

Overview

If you're a developer, it takes a few small steps to send your API logs to ReadMe so your team can get deep insights into your API's usage with ReadMe Metrics. Here's an overview of how the integration works:

  • You add the ReadMe middleware to your Laravel application.
  • The middleware sends to ReadMe the response object that your Laravel application generates each time a user makes a request to your API. The entire response is sent, unless you blacklist or whitelist keys.
  • ReadMe populates Metrics with this information, such as which endpoint is being called, response code, and error messages. It also identifies the customer who called your API, using whichever keys in the middleware you call out as containing relevant customer info.

Steps

ℹ️

Note these steps assume you are working in PHP and the Laravel web framework

  1. From the directory of your company's API codebase, run the following command in your command line to install the readme/metrics package from Packagist:
composer require readme/metrics
  1. Install the configuration file for readme/metrics, named readme.php, into your application with the following command:
php artisan vendor:publish --provider="ReadMe\ServiceProvider"
  1. Locate the "kernel" file for your API routing layer, this will typically be app/Http/Kernel.php, and search for a api group under $middlewareGroups. Install the \Readme\Middleware Service Provider into that array. It should look something like the following:
/**
 * The application's route middleware groups.
 *
 * @var array
 */
protected $middlewareGroups = [
    'web' => [
        // Any web middleware you may have set up.
    ],

    'api' => [
        \ReadMe\Middleware::class,
        // Any other API middleware you may have set up.
    ],
];
  1. Configure the middleware in the newly created configuration file from step 2: config/readme.php:
    • Change YOUR README API KEY to API_KEY. If you're currently logged into these docs, you can see your ReadMe API key in the preceding sentence; otherwise, you can find it at https://dash.readme.io/project/YOUR PROJECT/api-key.
  2. Modify the constructGroup function in the newly created app/Handler/ReadMe.php handler to return data specific to your API. See Identfying the API Caller for detailed instructions.

Identifying the API Caller

There are three pieces of data you can use to identify the user making the API call. (If your Laravel request object doesn't have all this information, we recommend adding it via additional middleware prior to this.) We recommend supplying all three to get the most insights about your API.

<?php
namespace App\Handler;

use Illuminate\Http\Request;

class ReadMe implements \ReadMe\Handler
{
    public static function constructGroup(Request $request): array
    {
        $user = $request->user();
        if (!$user) {
            return [
                'api_key' => session()->getId()
            ];
        }

        return [
            'api_key' => $user->id,
            'label' => $user->name,
            'email' => $user->email
        ];
    }
}
FieldUsage
api_keyRequired API Key used to make the request.
labelThis will be used to identify the user on ReadMe, since it's much easier to remember a name than a unique identifier.
emailEmail of the person that is making the call.

Configuration Options

There are a few configurable options in config/readme.php that let you change how logs are sent to ReadMe.

OptionTypeDescription
development_modeboolWhen disabled, development_mode will make all API requests asynchronously as well as silencing all possible errors in transit. This defaults to true, and you should change it to false before deploying your integration to production.
blacklistArray of stringsAn array of keys from your API requests and responses that you wish to blacklist from sending to ReadMe. If this option is present, it will be favored over the whitelist option below.
whitelistArray of stringsAn array of keys from your API requests and responses that you only wish to send to ReadMe.
base_log_urlstringThis is the base URL for your ReadMe project. Normally this would be https://projectName.readme.io or https://docs.yourdomain.com, however if this value is not supplied, a request to the ReadMe API will be made once a day to retrieve it. This data is cached into $COMPOSER_HOME/cache.

⚠️

blacklist and whitelist do not support support dot-notation so only top-level keys can be specified.

Sample Applications

FAQ

How can I upgrade to v2.0?

  1. Copy config/readme.php to config\readme.php.backup.
  2. Update the SDK:
composer update readme/metrics
  1. Re-run the config publishing step from our installation instructions:
php artisan vendor:publish --provider="ReadMe\ServiceProvider"

This will install the new config and the new handler class.

  1. Open up config\readme.php.backup and copy your api_key, development_mode, blacklist, and whitelist configs over to config\readme.php.
  2. Open up app\Handler\Readme.php and copy the contents of the old group function from config\readme.php.backup into the constructGroup function.