moesif / moesif-symfony
Bundle for Moesif Symphony integration
Requires
- php: >=7.2.5
- symfony/framework-bundle: ^5.0
This package is auto-updated.
Last update: 2024-11-04 13:48:16 UTC
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:
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:
- Select the account icon to bring up the settings menu.
- Select Installation or API Keys.
- 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:
-
In your project's
config/packages
directory, add amoesif.yaml
file. This file holds your configuration options. -
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:
Configuration Options
The following sections describe the available configuration options that you can define in moesif.yaml
.
applicationId
(Required)
A string that identifies your application..
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: