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

2. Install the configuration file for readme/metrics, named readme.php, into your application with the following command:

php artisan vendor:publish --provider="ReadMe\ServiceProvider"

3. 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.
    ],
];

4. 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.com/project/YOUR PROJECT/api-key.
5. 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
        ];
    }
}

Configuration Options

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

⚠️

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

Sample Applications

• Laravel

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

3. 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.

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