# Installation & Set Up

### Server requirements

* PHP >= 8.1

### Install

You can install Inspector using composer:

```bash
composer require inspector-apm/inspector-php
```

### Create an Inspector instance

Be sure to include the composer autoload in your application. The first step is to create an instance of the **`Configuration`** class using the Ingestion Key.

```php
<?php

use Inspector\Inspector;

require __DIR__ . '/../vendor/autoload.php';

$inspector = Inspector::create('YOUR_INGESTION_KEY');
```

{% hint style="info" %}
&#x20;Get a new Ingestion Key by signing up for Inspector (<https://app.inspector.dev/register>) and creating a new application.
{% endhint %}

### Transactions

All start with a `transaction`. A Transaction represents an execution cycle and it can contains one or hundreds of segments (database queries, internal functions, etc.).

You need to start a new Transaction as soon as possible in your application execution cycle to better represent the time your script takes to fulfill an HTTP request.

Typically the transaction should be started in the entry point of your application e.g. **`index.php`**

```php
$pathInfo = explode('?', $_SERVER["REQUEST_URI"]);
$path = array_shift($pathInfo);


/*
 * A transaction should start as soon as possible, 
 * typically in the "index.php" file of your application.
 */
$inspector->startTransaction($path)
    ->markAsRequest();


// Continue with the script...
```

### Set the Transaction result

When your application return a response back to the client you can setup the result of the transaction using the HTTP code:

```php
$inspector->transaction()->setResult(200);
```

### Add Context

Each transaction can be enriched with additional information to have a more complete picture of the process execution context.

You can use the `addCotext` method to attach new tabs to the current Transaction:

```php
$inspector->transaction()?->addContext('label', ['foo' => 'bar']);
```

Contextual information will be reported as additional tabs in the Transaction view. This code example creates a new tab "Label" in the Transaction details as showed in the image below:

<figure><img src="/files/-MUVVqCY1H7-N13XiubW" alt=""><figcaption></figcaption></figure>

The context is designed to help developers easily collect custom data during an execution cycle.

### Make Inspector available in your application globally

If you want to use the current Inspector instance inside your code to add contexual information or new segments, you need a way to make the Inspector instance available everywhere in your application.&#x20;

Use an IoC container like [PHP-DI](https://php-di.org/) is a common way to distribute internal services inside an application. If your application has one, or implement other similar strategies, you could put the Inspector instance in the registry:

```php
$container->set('inspector', $inspector);
```

in order to use it later inside your application (e.g. add segments):

```php
class UserController extends BaseController
{
    /**
     * Example of how to get the Inspector instance from a container.
     */
    public function action()
    {
        // Get the instance from the container.
        $inspector = $container->get('inspector');
    
        // Add a new segment to monitor an action.
        return $inspector->addSegment(function () {
            
            return $this->someService->action();
        
        }, 'someService', 'action');
    }
}
```

### Register callbacks

Using the `beforeFlush()` static method you can register a list of callbacks that will be executed just before data are sent out of your application.

This method provides a simple hook to interact with your monitoring data at the end of the transaction execution.

```php
Inspector::beforeFlush(function (\Inspector\Inspector $inspector) {
    // Do something
});
```

You can also register multiple callbacks that will be executed in the same order:

```php
// First
Inspector::beforeFlush(function (\Inspector\Inspector $inspector) {
    // Do something
});

// Second
Inspector::beforeFlush(function (\Inspector\Inspector $inspector) {
    // Do something
});

// Last
Inspector::beforeFlush(function (\Inspector\Inspector $inspector) {
    // Do something
});
```

By explicitly returning `FALSE` from a callback, the current transaction will not be sent to the remote platform, regardless of the value returned by other callbacks:

```php
Inspector::beforeFlush(function (\Inspector\Inspector $inspector) {
    if ($inspector->transaction()->name === 'GET /api') {
        return false; // <- Do not send data to the remote platform.
    }
});
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.inspector.dev/guides/raw-php/installation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.