README

by Moesif, the API analytics and API monetization platform.

Moesif's official SDK for PHP Symfony allows you to automatically capture API traffic and send to the Moesif API Analytics platform.

If you're new to Moesif, see our Getting Started resources to quickly get up and running.

Supported Symfony Versions

The SDK currently supports all Symfony 5.x versions.

Prerequisites

Before using this SDK, make sure you have the following:

• An active Moesif account
• A Moesif Application ID

Get Your Moesif Application ID

After you log into Moesif Portal, you can get your Moesif Application ID during the onboarding steps. You can always access the Application ID any time by following these steps from Moesif Portal after logging in:

1. Select the account icon to bring up the settings menu.
2. Select Installation or API Keys.
3. Copy your Moesif Application ID from the Collector Application ID field.

Install the SDK

Moesif Symfony SDK is available through Composer, the dependency manager for PHP. After you have Composer installed, execute the following command:

$ composer require moesif/moesif-symfony

Otherwise, manually add moesif/moesif-symfony to your composer.json file.

Enable the SDK

Follow these steps to enable the SDK:

1. In your project's config/packages directory, add a moesif.yaml file. This file holds your configuration options.

2. The configuration file requires you to at least specify your Moesif Application ID. The following shows an example:

   moesif:
     moesif_application_id: 'YOUR_MOESIF_APPLICATION_ID.'
     debug: false
     options:
       max_queue_size: 50
       max_batch_size: 25
     hooks_class: 'App\Configuration\MyMoesifHooks'

For more configuration options, see YAML Configuration Options.

Configure the SDK

See the available configuration options to learn how to configure the SDK for your use case.

Troubleshoot

For a general troubleshooting guide that can help you solve common problems, see Server Troubleshooting Guide.

Other troubleshooting supports:

• FAQ
• Moesif support email

Configuration Options

The following sections describe the available configuration options that you can define in moesif.yaml.

applicationId (Required)

debug

Set to true to print debug messages into the debug and error logs. This can help you troubleshoot integration issues.

options

If set, contains various options to configure the SDK beyond the defaults.

In this object, you can set the following options:

max_queue_size

If set, overrides the default max_queue_size before sending data to Moesif.

max_batch_size

If set, overrides the default max_batch_size that is sent over to Moesif.

hooks_class

If set, this must be your implementation of MoesifHooksInterface.

User Hook Class Options

You can override and customize certain functionalities within the plugin with hooks. For example, create a file MyMoesifHooks.php and implement the MoesifHooksInterface:

use Moesif\MoesifBundle\Interfaces\MoesifHooksInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class MyMoesifHooks implements MoesifHooksInterface {
   // your implementation of every method follows.
}

See the Example Implementation for an example.

Make sure to set the hooks_class configuration option to the path of your implementation file.

The methods you need to implement for MoesifHooksInterface are the following:

identifyUserId

Optional.

This function takes the $request and $response arguments and returns a string for a user ID. This enables Moesif to attribute API requests to individual unique users so you can understand who calls your API. You can use this simultaneously with identifyCompanyId to track both individual customers and also the companies they are part of.

identifyCompanyId

Optional.

This function takes the $request and $response arguments and returns a string for a company ID. If you have a B2B business, this method enables Moesif to attribute API requests to specific companies or organizations so you can understand which accounts call your API. You can use this simultaneously with identifyUserId to track both individual customers and the companies they are part of.

identifySessionToken

Optional.

A function that takes the $request and $response arguments and returns a string for session or auth token. Moesif automatically creates sessions by processing your API data, but you can override this through the identifySessionId method if you're not happy with the results.

maskRequestHeaders

Optional.

A function that takes the $headers argument for a request. The argument is an associative array. The method returns an associative array with your sensitive request headers removed or masked.

maskRequestBody

Optional.

A function that takes the $body argument for request body. The argument an associative array representation of JSON. The method returns an associative array with any request body information removed.

maskResponseHeaders

Optional.

Same as maskRequestHeaders, but for HTTP responses.

maskResponseBody

Optional.

Same as maskResponseBody, but for HTTP responses.

getMetadata

Optional.

A function that takes the $request and $response arguments and returns $metadata. $metadata is an associative array representation of JSON.

skip

Optional.

A function that takes the $request and $response arguments. Returns true if you want to skip the event. Skipping an event means Moesif doesn't log the event.

Example Implementation

The following example shows what the MyMoesifHooks.php file may look like with a MoesifHooksInterface implementation:

<?php

namespace App\Configuration;

use Moesif\MoesifBundle\Interfaces\MoesifHooksInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;


class MyMoesifHooks implements MoesifHooksInterface {

  public function __construct() {
  }

  public function identifyUserId(Request $request, Response $response): string|null
  {
    return 'nihao1';
  }

  public function identifyCompanyId(Request $request, Response $response): string|null
  {
    return $request->headers->get('X-Company-Id');
  }

  public function identifySessionToken(Request $request, Response $response): string|null
  {
    return null;
  }

  public function getMetadata(Request $request, Response $response): ?array
  {
      return null;
  }

  public function skip(Request $request, Response $response): bool
  {
      return false;
  }

  public function maskRequestHeaders(array $headers): array
  {
      return $headers;
  }

  public function maskResponseHeaders(array $headers): array
  {
      return $headers;
  }

  public function maskRequestBody($body)
  {
      // this can be a string or array object.
      // because prior to php 8, can not declare union type (such as string|array)
      return $body;
  }

  public function maskResponseBody($body)
  {
      // this can be a string or array object.
      // because prior to php 8, can not declare union type (such as string|array)
      return $body;
  }
}

Examples

The following examples demonstrate how to add and update customer information.

Update a Single User

The following example shows how you can create or update a user profile in Moesif using the updateUser function.

The metadata field can contain any customer demographic or other information you want to store.

Only the user_id field is required.

For more information, see the PHP API Reference about updating a singer user.

<?php
use Moesif\MoesifBundle\Service\MoesifApiService;

private $moesifApiService;

public function __construct(MoesifApiService $moesifApiService)
{
    $this->moesifApiService = $moesifApiService;
}

// metadata can be any custom object
$data->metadata = array(
    "email" => "john@acmeinc.com",
    "first_name" => "John",
    "last_name" => "Doe",
    "title" => "Software Engineer",
    "sales_info" => array(
        "stage" => "Customer",
        "lifetime_value" => 24000,
        "account_owner" => "mary@contoso.com"
    )
);

$userData = [
    'user_id' => $data['userId'],
    'user_email' => $data['userEmail'],
    'company_id' => $data['companyId'],
    'metadata' => $data['metadata'] ?? [], // Include metadata if provided
    // Add more fields as needed
];

$this->moesifApiService->updateUser($userData);

Update Users in Batch

You can use the updateUsersBatch function to update a list of users in one batch.

Only the user_id field is required.

For more information, see the PHP API Reference about updating users in batch.

<?php
use Moesif\MoesifBundle\Service\MoesifApiService;

private $moesifApiService;

public function __construct(MoesifApiService $moesifApiService)
{
    $this->moesifApiService = $moesifApiService;
}

// metadata can be any custom object
$data->metadata = array(
    "email" => "john@acmeinc.com",
    "first_name" => "John",
    "last_name" => "Doe",
    "title" => "Software Engineer",
    "sales_info" => array(
        "stage" => "Customer",
        "lifetime_value" => 24000,
        "account_owner" => "mary@contoso.com"
    )
);

$userDataA = [
    'user_id' => $data['userIdA'],
    'user_email' => $data['userEmailA'],
    'company_id' => $data['companyIdA'],
    'metadata' => $data['metadata'] ?? [], // Include metadata if provided
    // Add more fields as needed
];

$userDataB = [
    'user_id' => $data['userIdB'],
    'user_email' => $data['userEmailB'],
    'company_id' => $data['companyIdB'],
    'metadata' => $data['metadata'] ?? [], // Include metadata if provided
    // Add more fields as needed
];

$users = array($userDataA, $userDataB)
$this->moesifApiService->updateUsersBatch($user);

Update a Single Company

To create or update a company profile in Moesif, use the updateCompany function.

The metadata field can contain any company demographic or other information you want to store.

Only the company_id field is required.

For more information, see the PHP API Reference about updating a single company.

<?php
use Moesif\MoesifBundle\Service\MoesifApiService;

private $moesifApiService;

public function __construct(MoesifApiService $moesifApiService)
{
    $this->moesifApiService = $moesifApiService;
}

// metadata can be any custom object
$data->metadata = array(
    "org_name" => "Acme, Inc",
    "plan_name" => "Free",
    "deal_stage" => "Lead",
    "mrr" => 24000,
    "demographics" => array(
        "alexa_ranking" => 500000,
        "employee_count" => 47
    )
);

// Prepare company data for Moesif
$companyData = [
    'company_id' => $data['companyId'],
    'company_domain' => $data['companyDomain'],
    'metadata' => $data['metadata'] ?? [], // Include metadata if provided
    // Add more fields as needed
];

$this->moesifApiService->updateCompany($companyData);

Update Companies in Batch

To update a list of companies in one batch, use the updateCompaniesBatch function.

Only the company_id field is required.

For more information, see the PHP API Reference about updating companies in batch.

<?php
use Moesif\MoesifBundle\Service\MoesifApiService;

private $moesifApiService;

public function __construct(MoesifApiService $moesifApiService)
{
    $this->moesifApiService = $moesifApiService;
}

// metadata can be any custom object
$data->metadata = array(
    "org_name" => "Acme, Inc",
    "plan_name" => "Free",
    "deal_stage" => "Lead",
    "mrr" => 24000,
    "demographics" => array(
        "alexa_ranking" => 500000,
        "employee_count" => 47
    )
);

// Prepare company data for Moesif
$companyDataA = [
    'company_id' => $data['companyIdA'],
    'company_domain' => $data['companyDomainA'],
    'metadata' => $data['metadata'] ?? [], // Include metadata if provided
    // Add more fields as needed
];

$companyDataB = [
    'company_id' => $data['companyIdB'],
    'company_domain' => $data['companyDomainB'],
    'metadata' => $data['metadata'] ?? [], // Include metadata if provided
    // Add more fields as needed
];

$companies = array($companyDataA, $companyDataB)

$this->moesifApiService->updateCompaniesBatch($companies);

How to Get Help

If you face any issues using this SDK, try the troubheshooting guidelines. For further assistance, reach out to our support team.

Explore Other Integrations

Explore other integration options from Moesif:

• Server integration options documentation
• Client integration options documentation