Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@matthewtanner91
matthewtanner91 committed Mar 25, 2024
1 parent 641ca6c commit 5a77021
Showing 1 changed file with 377 additions and 2 deletions.
379 changes: 377 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,381 @@
# Moesif Symfony SDK

This is prerelease.
Official SDK for PHP Symfony 5.x to automatically capture API traffic and send to the Moesif API Analytics platform.

Readme Coming soon.
[Source Code on GitHub](https://github.com/Moesif/moesif-symfony1.4)

## How to install

Via Composer

```bash
$ composer require moesif/moesif-symfony
```

or add `moesif/moesif-symfony` to your composer.json file accordingly.

## How to enable the Plugin

In your project's `config/packages` directory, add a `moesif.yaml` file that will hold your configuration options. Within the file, at a minimum you'll need to add your `moesif_application_id`. Here is an example of the files contents:

``` yaml
moesif:
moesif_application_id: 'YOUR_MOESIF_APPLICATION_ID'
debug: false
options:
max_queue_size: 50
max_batch_size: 25

```

Your Moesif Application Id can be found in the [_Moesif Portal_](https://www.moesif.com/).
After signing up for a Moesif account, your Moesif Application Id will be displayed during the onboarding steps.

You can always find your Moesif Application Id at any time by logging
into the [_Moesif Portal_](https://www.moesif.com/), click on the bottom-left menu,
and then clicking _Installation_.

## YAML Configuration Options

### __`applicationId`__

Type: `String`
Required, a string that identifies your application.

### __`debug`__

Type: `Boolean`
Optional, If true, will print debug messages into the debug and error logs.

### __`options`__

Type: `Object`
Optional, if set, contains various options to configure the SDK beyond the defaults.

Here are the options that can be set within this object:

#### __`max_queue_size`__

Type: Int
If set, will override the default max queue size before data is sent over to Moesif. The default is `15`.

#### __`max_batch_size`__

Type: Int
If set, will override the default max batch size that is sent over to Moesif. The default is `10`.

## Subscriber Configuration Options

Certain functionalities can be overridden and customized within the plugin. To override these functions, within your projects `/src/EventSubscriber` directory, you must add a `CustomMoesifSubscriber.php` file.

In your `services.yaml` file you will also need to add the following:
``` yaml
services:

# Existing services config
...

App\EventSubscriber\CustomMoesifSubscriber:
class: App\EventSubscriber\CustomMoesifSubscriber # Ensure this matches the namespace and class name of your custom subscriber
tags:
- { name: moesif.event_subscriber }
```
Within the `CustomMoesifSubscriber.php` file, you will need to override the following methods:

### __`identifyUserId`__

Type: `($request, $response) => String`
Optional, a function that takes a $request and $response and return a string for userId. This enables Moesif to attribute API requests to individual unique users so you can understand who calling your API. This can be used simultaneously with `identifyCompanyId` to track both individual customers and also the companies they are a part of.

### __`identifyCompanyId`__

Type: `($request, $response) => String`
Optional, a function that takes a $request and $response and return a string for companyId. If your business is B2B, this enables Moesif to attribute API requests to specific companies or organizations so you can understand which accounts are calling your API. This can be used simultaneously with `identifyUserId` to track both individual customers and the companies their a part of.

### __`identifySessionToken`__

Type: `($request, $response) => String`
Optional, a function that takes a $request and $response and return a string for session token/auth token. Moesif automatically sessionizes by processing your API data, but you can override this via identifySessionId if you're not happy with the results.

### __`maskRequestHeaders`__

Type: `$headers => $headers`
Optional, a function that takes a $headers, which is an associative array, and
returns an associative array with your sensitive headers removed/masked.

### __`maskRequestBody`__

Type: `$body => $body`
Optional, a function that takes a $body, which is an associative array representation of JSON, and
returns an associative array with any information removed.

### __`maskResponseHeaders`__

Type: `$headers => $headers`
Optional, same as above, but for Responses.

### __`maskResponseBody`__

Type: `$body => $body`
Optional, same as above, but for Responses.

### __`getMetadata`__

Type: `($request, $response) => Associative Array`
Optional, a function that takes a $request and $response and returns $metdata which is an associative array representation of JSON.

### __`skip`__

Type: `($request, $response) => String`
Optional, a function that takes a $request and $response and returns true if this API call should be not be sent to Moesif.

Here is an example of what the `CustomMoesifSubscriber.php` file may look like:

``` php
<?php
namespace App\EventSubscriber;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Moesif\MoesifBundle\Interfaces\EventSubscriberInterface as MoesifEventSubscriberInterface;
class CustomMoesifSubscriber implements EventSubscriberInterface {
// Implement all abstract methods, but focus on the ones you want to override
public function identifyUserId(Request $request, Response $response): ?string {
// Your custom logic to identify the user
// For example, extract user ID from JWT token
return "1234abcd";
}
public function identifyCompanyId(Request $request, Response $response): ?string {
// Your custom logic to identify the company
// For example, extract company ID from request headers
return "5678efgh";
}
public function identifySessionToken(Request $request, Response $response): ?string
{
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(string $body): ?string
{
return $body;
}
public function maskResponseBody(string $body): ?string
{
return $body;
}
}
```

## Update a Single User

Create or update a user profile in Moesif.
The metadata field can be any customer demographic or other info you want to store.
Only the `user_id` field is required.
For details, visit the [PHP API Reference](https://www.moesif.com/docs/api?php#update-a-user).

```php
<?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" => "[email protected]",
"first_name" => "John",
"last_name" => "Doe",
"title" => "Software Engineer",
"sales_info" => array(
"stage" => "Customer",
"lifetime_value" => 24000,
"account_owner" => "[email protected]"
)
);
$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

Similar to updateUser, but used to update a list of users in one batch.
Only the `user_id` field is required.
For details, visit the [PHP API Reference](https://www.moesif.com/docs/api?php#update-users-in-batch).

```php
<?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" => "[email protected]",
"first_name" => "John",
"last_name" => "Doe",
"title" => "Software Engineer",
"sales_info" => array(
"stage" => "Customer",
"lifetime_value" => 24000,
"account_owner" => "[email protected]"
)
);
$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

Create or update a company profile in Moesif.
The metadata field can be any company demographic or other info you want to store.
Only the `company_id` field is required.
For details, visit the [PHP API Reference](https://www.moesif.com/docs/api?php#update-a-company).

```php
<?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

Similar to updateCompany, but used to update a list of companies in one batch.
Only the `company_id` field is required.
For details, visit the [PHP API Reference](https://www.moesif.com/docs/api?php#update-companies-in-batch).

```php
<?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);
```

## Other integrations

To view more documentation on integration options, please visit __[the Integration Options Documentation](https://www.moesif.com/docs/getting-started/integration-options/).__

For Symfony 1.X please see: https://github.com/Moesif/moesif-symfony1.4

0 comments on commit 5a77021

Please sign in to comment.