Bitrix24 REST API PHP SDK

https://github.com/bitrix24/b24phpsdk
Admin
An official PHP library for the Bitrix24 REST API that provides modern, type-safe access to Bitrix24...
Tokens:983,613
Snippets:4,699
Trust Score:8.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and Inspect SDK with Composer

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/resources/skills/b24phpsdk-developer/references/product-integration.md

Install the SDK in the product application and inspect the installed version.

```bash
composer require bitrix24/b24phpsdk
composer show bitrix24/b24phpsdk
```

--------------------------------

### Run Webhook Example PHP File

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/README.md

Runs the webhook example PHP file from the shell to execute the SDK calls.

```shell
php -f webhook-example.php
```

--------------------------------

### Application installation state diagram

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/src/Application/Contracts/ApplicationInstallations/Docs/ApplicationInstallations.md

State diagram for application installation lifecycle. Shows transitions between New, Active, Blocked, NeedReinstall, and Deleted states, including the new NeedReinstall state for stale installations.

```mermaid
stateDiagram-v2
    [*] --> New: New installation started
    New --> Active : Installation completed successfully
    New --> Blocked : Installation aborted
    New --> NeedReinstall : Timed out waiting for ONAPPINSTALL
    NeedReinstall --> Deleted : Uninstall stale installation
    Active --> Blocked : Connection lost or\nforcibly deactivated
    Active --> Deleted : Application\n uninstalled
    Blocked --> Active : Reconnected or\nreactivated
    Blocked --> Deleted : Delete blocked installation 
    Deleted --> [*]: Installation can be removed\n from persistence storage
```

--------------------------------

### Local Application index.php Example

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/README.md

Example index.php file for a local application. It initializes the SDK from a placement request and application profile, then dumps the current user profile. Replace the INSERT_HERE_YOUR_DATA placeholders with your actual application credentials.

```php
declare(strict_types=1);

use Bitrix24\SDK\Core\Credentials\ApplicationProfile;
use Bitrix24\SDK\Services\ServiceBuilderFactory;
use Symfony\Component\HttpFoundation\Request;

require_once 'vendor/autoload.php';
?>
    <pre>
    Application is worked, auth tokens from bitrix24:
    <?= print_r($_REQUEST, true) ?>
</pre>
<?php

$appProfile = ApplicationProfile::initFromArray([
    'BITRIX24_PHP_SDK_APPLICATION_CLIENT_ID' => 'INSERT_HERE_YOUR_DATA',
    'BITRIX24_PHP_SDK_APPLICATION_CLIENT_SECRET' => 'INSERT_HERE_YOUR_DATA',
    'BITRIX24_PHP_SDK_APPLICATION_SCOPE' => 'INSERT_HERE_YOUR_DATA'
]);

$b24Service = ServiceBuilderFactory::createServiceBuilderFromPlacementRequest(Request::createFromGlobals(), $appProfile);

var_dump($b24Service->getMainScope()->main()->getCurrentUserProfile()->getUserProfile());
```

--------------------------------

### Install stable v1 version

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/README.md

Install the stable v1 version of the SDK, which requires PHP 8.2 or higher.

```bash
composer require bitrix24/b24phpsdk:"^1.0"
```

--------------------------------

### Self-documenting code example

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/src/Filters/docs/README.md

Illustrates how method signatures make the expected types clear, using between(int $min, int $max) as an example.

```php
// Signature explains everything:
public function between(int $min, int $max): AbstractFilterBuilder
```

--------------------------------

### Start Local PHP Development Server

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/README.md

Starts a local PHP development server on port 80. Requires sudo to bind to port 80.

```shell
sudo php -S 127.0.0.1:80
```

--------------------------------

### Install Bitrix24 PHP SDK with Composer

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/README.md

Installs the Bitrix24 PHP SDK package via Composer. Required before using the SDK in your project.

```shell
composer require bitrix24/b24phpsdk
```

--------------------------------

### ApplicationInstallation Methods

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/src/Application/Contracts/ApplicationInstallations/Docs/ApplicationInstallations.md

Methods to retrieve and modify application installation data, including getters, link/unlink operations, and status transitions.

```APIDOC
## ApplicationInstallation Methods

### Description
These methods allow retrieving and modifying application installation data, including IDs, timestamps, linked contacts, partners, external IDs, and statuses.

### Methods

#### getId()
- **Return Type**: `Uuid`
- **Description**: Returns unique application installation id.

#### getCreatedAt()
- **Return Type**: `CarbonImmutable`
- **Description**: Returns date and time application installation was created.

#### getUpdatedAt()
- **Return Type**: `CarbonImmutable`
- **Description**: Returns date and time of last application installation change.

#### getBitrix24AccountId()
- **Return Type**: `Uuid`
- **Description**: Returns Bitrix24 Account id related to this installation.

#### getContactPersonId()
- **Return Type**: `?Uuid`
- **Description**: Returns contact person id who installed the application on portal (optional).

#### linkContactPerson()
- **Return Type**: `void`
- **Description**: Link client contact person.

#### unlinkContactPerson()
- **Return Type**: `void`
- **Description**: Unlink client contact person.

#### getBitrix24PartnerContactPersonId()
- **Return Type**: `?Uuid`
- **Description**: Returns Bitrix24 partner contact person id (optional).

#### linkBitrix24PartnerContactPerson()
- **Return Type**: `void`
- **Description**: Link Bitrix24 partner contact person.

#### unlinkBitrix24PartnerContactPerson()
- **Return Type**: `void`
- **Description**: Unlink Bitrix24 partner contact person.

#### getBitrix24PartnerId()
- **Return Type**: `?Uuid`
- **Description**: Returns Bitrix24 Partner id related to this installation (optional).

#### linkBitrix24Partner()
- **Return Type**: `void`
- **Description**: Link Bitrix24 partner.

#### unlinkBitrix24Partner()
- **Return Type**: `void`
- **Description**: Unlink Bitrix24 partner.

#### getExternalId()
- **Return Type**: `?string`
- **Description**: Returns external id for application installation.

#### setExternalId()
- **Return Type**: `void`
- **Description**: Sets external id for application installation.
- **Throws**: `InvalidArgumentException`

#### getStatus()
- **Return Type**: `ApplicationInstallationStatus`
- **Description**: Returns application installation status.

#### applicationInstalled()
- **Return Type**: `void`
- **Description**: Finishes application installation.
- **Throws**: `InvalidArgumentException`

#### applicationUninstalled()
- **Return Type**: `void`
- **Description**: Marks application as uninstalled.
- **Throws**: `InvalidArgumentException`

#### markAsActive()
- **Return Type**: `void`
- **Description**: Changes status to active for blocked application installation accounts.
- **Throws**: `InvalidArgumentException`

#### markAsBlocked()
- **Return Type**: `void`
- **Description**: Changes status to blocked for application installation accounts in state new or active.
- **Throws**: `InvalidArgumentException`

#### getApplicationStatus()
- **Return Type**: `ApplicationStatus`
- **Description**: Returns current application status stored in persistence storage.

```

--------------------------------

### Install v3 version

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/README.md

Install the new v3 version, which requires PHP 8.4 or higher and includes breaking changes.

```bash
composer require bitrix24/b24phpsdk:"^3.7"
```

--------------------------------

### Install dependencies with composer update

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/CONTRIBUTING.md

Installs project dependencies. Assumes 'composer' is aliased to the location of composer.phar.

```shell
composer update
```

--------------------------------

### CRM Deal scope directory example

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/architecture.md

Real example of the directory layout for the CRM Deal scope. Shows the service files and result classes used for deal operations.

```text
CRM/Deal/
├── Service/
│   ├── Deal.php           ← crm.deal.* methods
│   ├── Batch.php          ← batch-mode deal operations
│   ├── DealCategory.php   ← crm.dealcategory.* methods
│   └── ...
└── Result/
    ├── DealItemResult.php
    ├── DealResult.php
    └── DealsResult.php
```

--------------------------------

### Install Composer dependencies for Deptrac

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/testing.md

Install Composer dependencies to resolve the missing Deptrac binary when lint-deptrac fails with vendor/bin/deptrac: not found.

```bash
make composer-install
```

--------------------------------

### Inspect SDK Source with ripgrep

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/resources/skills/b24phpsdk-developer/references/product-integration.md

Search the installed SDK source for the contact service API to verify available methods.

```bash
rg -n "function contact|class Contact" vendor/bitrix24/b24phpsdk/src/Services
```

--------------------------------

### Hello World: Read CRM Contacts

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/resources/skills/b24phpsdk-developer/references/product-integration.md

Complete example that reads CRM contacts via the SDK, outputs a JSON summary, and exits with an error if the webhook environment variable is missing.

```php
<?php

declare(strict_types=1);

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

use Bitrix24\SDK\Services\ServiceBuilderFactory;

$webhookUrl = getenv('BITRIX24_WEBHOOK');
if ($webhookUrl === false || $webhookUrl === '') {
    fwrite(STDERR, "BITRIX24_WEBHOOK is required\n");
    exit(1);
}

$contacts = ServiceBuilderFactory::createServiceBuilderFromWebhook($webhookUrl)
    ->getCRMScope()
    ->contact()
    ->list(['ID' => 'ASC'], [], ['ID', 'NAME', 'LAST_NAME'], 0)
    ->getContacts();

echo json_encode(
    [
        'count' => count($contacts),
        'items' => array_map(
            static fn ($contact): array => [
                'id' => (int)$contact->ID,
                'name' => trim(sprintf('%s %s', $contact->NAME ?? '', $contact->LAST_NAME ?? '')),
            ],
            $contacts,
        ),
    ],
    JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT,
) . PHP_EOL;
```

--------------------------------

### Integration test pattern with Factory::getServiceBuilder()

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/testing.md

Integration test pattern that uses Factory::getServiceBuilder() in setUp() and cleans up records in tearDown(). Use CustomBitrix24Assertions for domain-specific assertions.

```php
class MyServiceTest extends TestCase
{
    use CustomBitrix24Assertions;

    private MyService $service;

    #["Override"]
    public function setUp(): void
    {
        $this->service = Factory::getServiceBuilder()->getMyService();
    }

    #["Override"]
    public function tearDown(): void
    {
        // clean up entities created during the test
    }

    public function testAdd(): void
    {
        $result = $this->service->add(['TITLE' => 'Test']);
        $this->assertGreaterThan(0, $result->getId());
    }
}
```

--------------------------------

### Compile-time type checking example

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/src/Filters/docs/README.md

Demonstrates that passing an int to eq() compiles, while passing a string causes a TypeError at development time.

```php
$filter->id()->eq(100);      // ✅ Compiles
$filter->id()->eq('hundred'); // ❌ TypeError at development time
```

--------------------------------

### Unit test pattern with #[CoversClass] and #[DataProvider]

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/testing.md

Unit test pattern using #[CoversClass], #[DataProvider], and null stubs to avoid HTTP calls. Use #[Override] for setUp and prefer createMock() for call assertions, createStub() for return values.

```php
#[CoversClass(MyService::class)]
class MyServiceTest extends TestCase
{
    private MyService $service;

    #[\\Override]
    protected function setUp(): void
    {
        $this->service = new MyService(
            new NullCore(),   // no HTTP calls
            new NullBatch(),
            new NullLogger()
        );
    }

    #[Test]
    #[DataProvider('myDataProvider')]
    public function testSomeBehavior(string $input, string $expected): void
    {
        $this->assertEquals($expected, $this->service->process($input));
    }

    public static function myDataProvider(): Generator
    {
        yield 'case description' => ['input', 'expected'];
    }
}
```

--------------------------------

### Automatic type conversions example

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/src/Filters/docs/README.md

Shows automatic conversion of DateTime to 'Y-m-d' and boolean to 'Y' in filter conditions.

```php
// DateTime conversion
->changedDate()->eq(new DateTime('2025-01-01')) // ✅ → '2025-01-01'

// Boolean conversion
->favorite()->eq(true) // ✅ → 'Y'
```

--------------------------------

### Simple Filter Example

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/src/Filters/docs/README.md

Finds records where the status is NEW and the ID is within the specified list using AND logic.

```json
{
    "filter": [
        ["status", "=", "NEW"],
        ["id", "in", [3, 4, 5]]
    ]
}
```

--------------------------------

### TaskService class with add method

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/api-v3-dev.md

Example of a service class with an API operation. The add method takes a TaskBuilder and returns void. This is part of the development workflow for related entities.

```php
class TaskService
{
    public function add(TaskBuilder $taskBuilder): void
    {
        // Implementation
    }
}
```

--------------------------------

### Read user history and changes with userHistory()->list()

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/main-user-history.md

Use this PHP snippet to fetch a user's history entries and their associated changes. It requires a valid user ID and uses the generated UserHistorySelectBuilder to select fields. The example iterates over history items and retrieves changes for each, accessing the field and data properties. Note that the history 'field' property may be absent unless explicitly selected, and change data is mixed.

```php
use Bitrix24\SDK\Core\Contracts\SortOrder;
use Bitrix24\SDK\Services\Main\UserHistory\Service\UserHistorySelectBuilder;

$main = $serviceBuilder->getMainScope();
$userId = 7; // An existing user whose history you are permitted to read.

$history = $main->userHistory()->list(
    userId: $userId,
    select: (new UserHistorySelectBuilder())->dateInsert()->eventType()->field(),
    filter: [['id', '>', 0]],
    order: ['id' => SortOrder::Descending],
    pagination: ['limit' => 20, 'offset' => 0],
)->getUserHistoryItems();

foreach ($history as $entry) {
    // Generated select builders always include id.
    $changes = $main->userHistoryChange()->list((int)$entry->id)->getUserHistoryChanges();
    foreach ($changes as $change) {
        $fieldCode = $change->field;
        $payload = $change->data; // Preserved as returned; values need not be strings.
    }
}
```

--------------------------------

### Incremental read with UserHistoryTailCursor

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/main-user-history.md

Use this pattern to poll user history incrementally. Restore a saved checkpoint (zero starts from the beginning), process each page, and persist a new checkpoint only after successful processing. The cursor preserves numeric strings, integers, and null; an empty response may contain ['field' => 'id', 'value' => null] — do not convert that to zero or discard the last checkpoint. Request cursors reject null, invalid ID positions, and values exceeding PHP_INT_MAX, and the default order is ascending (use SortOrder::Descending explicitly if needed).

```php
use Bitrix24\SDK\Services\Main\UserHistory\Service\UserHistoryTailCursor;

// Restore a previously saved checkpoint here; zero starts from the beginning.
$checkpoint = new UserHistoryTailCursor(value: 0);
do {
    $page = $main->userHistory()->tail($userId, $checkpoint);
    foreach ($page->getUserHistoryItems() as $entry) {
        // Process each entry. Persist a new checkpoint only after processing succeeds.
    }

    $cursor = $page->getCursor();
    if ($cursor === null || $cursor['value'] === null) {
        break; // Retain the last checkpoint for the next poll.
    }

    $checkpoint = new UserHistoryTailCursor($cursor['value'], $cursor['field']);
    // Persist $checkpoint->toArray() here, using the validated integer request value.
} while ($page->hasMore());
```

--------------------------------

### Generic filter builder type safety issues

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/src/Filters/docs/README.md

Shows examples of semantically wrong filter conditions that compile but are incorrect, such as using a string for an ID or a numeric range for priority.

```php
// All of these compile but are semantically wrong:
$filter->id()->eq('not-a-number');           // ID should be int!
$filter->changedDate()->eq(12345);           // Date should be DateTime or string!
$filter->priority()->between('low', 'high'); // Priority should be numeric range!
```

--------------------------------

### Initialize SDK from Webhook and Call Methods

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/README.md

Creates a PHP file (e.g., webhook-example.php) that initializes the SDK from a webhook URL and calls methods. Replace 'INSERT_HERE_YOUR_WEBHOOK_URL' with your actual webhook URL.

```php
<?php

declare(strict_types=1);

use Bitrix24\SDK\Services\ServiceBuilderFactory;

require_once 'vendor/autoload.php';

// init bitrix24-php-sdk service from webhook
$b24Service = ServiceBuilderFactory::createServiceBuilderFromWebhook('INSERT_HERE_YOUR_WEBHOOK_URL');

// call some method
var_dump($b24Service->getMainScope()->main()->getApplicationInfo()->applicationInfo());
// call core for method in not implemented service
var_dump($b24Service->core->call('user.current'));
```

--------------------------------

### Initialize SDK from Webhook

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/resources/skills/b24phpsdk-developer/references/product-integration.md

Initialize the SDK using an incoming webhook for backend jobs, CLI tools, and simple server-side integrations scoped to one Bitrix24 portal.

```php
use Bitrix24\SDK\Services\ServiceBuilderFactory;

$serviceBuilder = ServiceBuilderFactory::createServiceBuilderFromWebhook($webhookUrl);
```

--------------------------------

### Run Hello World Script

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/resources/skills/b24phpsdk-developer/references/product-integration.md

Run the hello-world script with the webhook URL provided as an environment variable.

```bash
BITRIX24_WEBHOOK="https://example.bitrix24.com/rest/1/secret/" php hello-world.php
```

--------------------------------

### Verification commands

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/plans/2026-04-15-remove-cebe-php-openapi-design.md

Run the full verification suite after removing the cebe/php-openapi dependency to ensure no regressions.

```bash
make lint-allowed-licenses
make lint-cs-fixer
make lint-phpstan
make lint-rector
make lint-deptrac
make test-unit
```

--------------------------------

### Commit integration and release wiring

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/superpowers/plans/2026-04-19-im-disk-folder-get.md

Stages the integration test, PHPUnit configuration, Makefile, and changelog, then commits them with the message 'test: cover IM disk folder getter'.

```bash
git add tests/Integration/Services/IM/Disk/Service/DiskTest.php phpunit.xml.dist Makefile CHANGELOG.md
git commit -m "test: cover IM disk folder getter"
```

--------------------------------

### Consumer code: Initialize service builder and fetch deal

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/architecture.md

Shows how to initialize the service builder from a webhook and retrieve a deal by ID. The deal service is accessed via the CRM scope.

```php
// Consumer code
$serviceBuilder = (new ServiceBuilderFactory())->initFromWebhook($webhookUrl);
$deal = $serviceBuilder->getCRMScope()->deal();
$result = $deal->get(42);
```

--------------------------------

### Run targeted integration suite

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/superpowers/plans/2026-04-19-im-disk-folder-get.md

Runs the targeted IM Disk integration suite. Before wiring, it is expected to fail with 'No tests executed' or a missing testsuite/file error; after wiring and implementation, the new test should pass.

```bash
make test-integration-im-disk
```

--------------------------------

### Expose Local Server with ngrok

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/README.md

Exposes the local server to the public internet via ngrok. Remember the temporary public URL (e.g., https://****.ngrok-free.app) for later steps.

```shell
ngrok http 127.0.0.1
```

--------------------------------

### Run all linters with make lint-all

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/testing.md

Run all linters in sequence. This is the primary command for code quality checks in the project.

```bash
make lint-all
```

--------------------------------

### Run targeted unit tests

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/superpowers/plans/2026-04-19-im-disk-folder-get.md

Command to run the unit tests for the builder and disk service to verify they fail as expected.

```bash
docker compose run --rm php-cli vendor/bin/phpunit tests/Unit/Services/IM/IMServiceBuilderTest.php tests/Unit/Services/IM/Disk/Service/DiskTest.php --display-warnings
```

--------------------------------

### Use SDK Result Accessor for CRM Contact List

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/resources/skills/b24phpsdk-developer/references/result-handling.md

Use the SDK result wrapper and accessor to retrieve contacts from a CRM list call. The final integer argument is the start offset for pagination.

```php
$result = $serviceBuilder
    ->getCRMScope()
    ->contact()
    ->list(['ID' => 'ASC'], [], ['ID', 'NAME', 'LAST_NAME'], 0);

$contacts = $result->getContacts();
```

--------------------------------

### Construct SDK Services at Application Edge

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/resources/skills/b24phpsdk-developer/references/product-integration.md

Construct SDK services at the edge of the application and obtain the contact service.

```php
$serviceBuilder = ServiceBuilderFactory::createServiceBuilderFromWebhook($webhookUrl);
$contactService = $serviceBuilder->getCRMScope()->contact();
```

--------------------------------

### Load Webhook URL from Environment

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/resources/skills/b24phpsdk-developer/references/product-integration.md

Retrieve the webhook URL from the environment and fail if it is missing. Never commit real webhook URLs because they include credentials.

```php
$webhookUrl = getenv('BITRIX24_WEBHOOK');
if ($webhookUrl === false || $webhookUrl === '') {
    throw new RuntimeException('BITRIX24_WEBHOOK is required');
}
```

--------------------------------

### Run integration tests by scope

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/testing.md

Run integration test suites by Bitrix24 API scope. Each suite maps to a specific scope.

```bash
make test-integration-scope-crm
make test-integration-scope-lists
make test-integration-calendar-event
make test-integration-calendar-resource
make test-integration-im-open-lines-config
make test-integration-im-open-lines-crm-chat
make test-integration-im-open-lines-session
make test-integration-im-open-lines-operator
make test-integration-landing-page
make test-integration-landing-syspage
make test-integration-landing-repo
make test-integration-landing-demos
make test-integration-landing-role
make test-integration-sale-basket-property
make test-integration-sale-cashbox-handler
make test-integration-sale-cashbox
make test-integration-sale-delivery
make test-integration-sale-delivery-extra-service
make test-integration-sale-payment-item-basket
make test-integration-sale-payment-item-shipment
make test-integration-sale-property-relation
make test-integration-sale-delivery-request
make test-integration-sale-person-type
make test-integration-sale-person-type-status
make test-integration-sale-property
make test-integration-sale-property-group
make test-integration-sale-property-variant
make test-integration-sale-trade-platform
make test-integration-legacy-task
make test-integration-main-eventlog
```

--------------------------------

### Commit implementation

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/superpowers/plans/2026-04-19-im-disk-folder-get.md

Stages the new and modified files and commits them with the message 'feat: add IM disk folder getter'.

```bash
git add src/Services/IM/Disk/Result/FolderIdResult.php src/Services/IM/Disk/Service/Disk.php src/Services/IM/IMServiceBuilder.php
git add tests/Unit/Services/IM/IMServiceBuilderTest.php tests/Unit/Services/IM/Disk/Service/DiskTest.php
git commit -m "feat: add IM disk folder getter"
```

--------------------------------

### Verification commands

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/plans/2026-04-15-partner-repository-flusher-design.md

Commands to run for linting and unit tests after making the changes.

```bash
make lint-cs-fixer
make lint-rector
make lint-phpstan
make lint-deptrac
make test-unit
```

--------------------------------

### Run a single test class with docker-compose

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/testing.md

Run a single integration test class inside Docker.

```bash
docker-compose run --rm php-cli vendor/bin/phpunit tests/Integration/Services/CRM/Deal/Service/DealTest.php
```

--------------------------------

### Add test-integration-im-disk target to Makefile

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/superpowers/plans/2026-04-19-im-disk-folder-get.md

Adds a Makefile target test-integration-im-disk that runs the integration_tests_im_disk PHPUnit suite via Docker. Includes a help echo line and a .PHONY declaration.

```makefile
@echo "test-integration-im-disk - run IM Disk integration tests"

.PHONY: test-integration-im-disk
test-integration-im-disk:
	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_im_disk
```

--------------------------------

### Run integration tests

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/README.md

Commands to run integration tests for core and specific scopes (telephony, workflows, user). These tests require a test Bitrix24 account and the environment variables from the .env.local file.

```shell
make test-integration-core
make test-integration-scope-telephony
make test-integration-scope-workflows
make test-integration-scope-user
```

--------------------------------

### Register disk() in IMServiceBuilder

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/superpowers/plans/2026-04-19-im-disk-folder-get.md

Adds the disk() method to IMServiceBuilder to lazily instantiate and cache the Disk service.

```php
use Bitrix24\SDK\Services\IM\Disk\Service\Disk;

public function disk(): Disk
{
    if (!isset($this->serviceCache[__METHOD__])) {
        $this->serviceCache[__METHOD__] = new Disk($this->core, $this->log);
    }

    return $this->serviceCache[__METHOD__];
}

```

--------------------------------

### Add abstract createRepositoryFlusherImplementation method

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/plans/2026-04-15-partner-repository-flusher-design.md

Declares the abstract method that subclasses must implement to provide a flusher instance. Place after createBitrix24PartnerRepositoryImplementation().

```php
abstract protected function createRepositoryFlusherImplementation(): TestRepositoryFlusherInterface;
```

--------------------------------

### Skip Live Tests Without BITRIX24_WEBHOOK

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/resources/skills/b24phpsdk-developer/references/error-handling-and-testing.md

Make live Bitrix24 integration tests explicit and opt-in by skipping when the BITRIX24_WEBHOOK environment variable is not set. Use to verify credentials, scopes, SDK wiring, and workflows that cannot be proven with fakes.

```php
$webhookUrl = getenv('BITRIX24_WEBHOOK');
if ($webhookUrl === false || $webhookUrl === '') {
    self::markTestSkipped('BITRIX24_WEBHOOK is required for live Bitrix24 checks');
}
```

--------------------------------

### IDE autocomplete suggestions

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/src/Filters/docs/README.md

Shows the type hints that IDEs provide for different field types, improving autocomplete.

```php
$filter->id()->eq(|)       // IDE suggests: int
$filter->title()->eq(|)    // IDE suggests: string
$filter->deadline()->eq(|) // IDE suggests: DateTime|string
```

--------------------------------

### Create Disk.php service

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/superpowers/plans/2026-04-19-im-disk-folder-get.md

Implements the Disk service class with the getFolderId method that calls the im.disk.folder.get API endpoint, accepting optional chatId and dialogId parameters.

```php
<?php

declare(strict_types=1);

namespace Bitrix24\SDK\Services\IM\Disk\Service;

use Bitrix24\SDK\Attributes\ApiEndpointMetadata;
use Bitrix24\SDK\Attributes\ApiServiceMetadata;
use Bitrix24\SDK\Core\Credentials\Scope;
use Bitrix24\SDK\Services\AbstractService;
use Bitrix24\SDK\Services\IM\Disk\Result\FolderIdResult;

#[ApiServiceMetadata(new Scope(['im']))]
final class Disk extends AbstractService
{
    #[ApiEndpointMetadata(
        'im.disk.folder.get',
        'https://apidocs.bitrix24.ru/api-reference/chats/files/im-disk-folder-get.html',
        'Get the identifier of the folder where chat files are stored'
    )]
    public function getFolderId(?int $chatId = null, ?string $dialogId = null): FolderIdResult
    {
        $params = [];

        if ($chatId !== null) {
            $params['CHAT_ID'] = $chatId;
        }

        if ($dialogId !== null) {
            $params['DIALOG_ID'] = $dialogId;
        }

        return new FolderIdResult($this->core->call('im.disk.folder.get', $params));
    }
}

```

--------------------------------

### Run unit tests

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/README.md

Runs fast, in-memory unit tests without network I/O. Use this command to execute the unit test suite.

```shell
make test-unit
```

--------------------------------

### Add integration_tests_im_disk suite to phpunit.xml.dist

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/superpowers/plans/2026-04-19-im-disk-folder-get.md

Adds a dedicated PHPUnit suite named integration_tests_im_disk that points to the IM Disk integration test directory. Place it near the other IM suites in phpunit.xml.dist.

```xml
<testsuite name="integration_tests_im_disk">
    <directory>./tests/Integration/Services/IM/Disk/</directory>
</testsuite>
```

--------------------------------

### Fake ContactDirectory for Unit Tests

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/resources/skills/b24phpsdk-developer/references/error-handling-and-testing.md

Unit-test product logic against product-owned interfaces using a fake implementation. Keeps tests fast and independent from Bitrix24 network access.

```php
final class FakeContactDirectory implements ContactDirectory
{
    public function recentContacts(int $limit): array
    {
        return [
            ['id' => 1, 'name' => 'Ada Lovelace'],
        ];
    }
}
```

--------------------------------

### Run final verification commands

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/superpowers/plans/2026-04-19-im-disk-folder-get.md

Final verification set: runs targeted unit tests with warnings displayed, the full unit suite, and the IM Disk integration suite. Expected: targeted unit tests pass, full unit suite stays green, and the integration suite passes.

```bash
docker compose run --rm php-cli vendor/bin/phpunit tests/Unit/Services/IM/Disk/Service/DiskTest.php tests/Unit/Services/IM/IMServiceBuilderTest.php --display-warnings
make test-unit
make test-integration-im-disk
```

--------------------------------

### Create service builder from webhook URL

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/value-object-migration.md

Create a service builder from a webhook URL using the Url value object. Do not put production tokens in source control. Credential getters and serialized payloads still return strings.

```php
use Bitrix24\SDK\Services\ServiceBuilderFactory;

$sdk = ServiceBuilderFactory::createServiceBuilderFromWebhook(
    new Url('https://example.bitrix24.com/rest/1/YOUR_TOKEN/')
);
```

--------------------------------

### CHANGELOG entry template for skill updates

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/AGENTS.md

Use this template when adding a CHANGELOG entry for any update to a skill or agent file. Place it under `## X.Y.Z Unreleased` → `### Changed`.

```markdown
### Changed
- Updated `b24phpsdk-maintainer` skill: <one-line description of what changed>
```

--------------------------------

### Run a single test method with --filter

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/testing.md

Run a single test method inside Docker using the --filter option.

```bash
docker-compose run --rm php-cli vendor/bin/phpunit tests/Integration/Services/CRM/Deal/Service/DealTest.php --filter testAdd
```

--------------------------------

### Test directory structure

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/testing.md

Directory layout for the test suite, showing unit and integration test folders, shared helpers, and environment files. Use as a reference when adding new tests.

```text
tests/
├── Unit/
│   ├── Application/        # Application layer unit tests
│   ├── Core/               # Core (HTTP client, batch, credentials) unit tests
│   ├── Filters/            # Filter unit tests
│   ├── Infrastructure/     # Infrastructure unit tests
│   ├── OpenApi/            # OpenAPI unit tests
│   ├── Services/           # Service unit tests (mirrors src/Services/)
│   └── Stubs/              # Null/stub implementations (see below)
├── Integration/
│   ├── Core/               # Core integration tests
│   ├── Legacy/             # Legacy API v1 integration tests
│   └── Services/           # Service integration tests (mirrors src/Services/)
├── CustomAssertions/       # Shared assertion traits
├── Builders/               # Test builder helpers
├── Application/            # Application-level test helpers
├── ApplicationBridge/      # Webhook bridge for app-mode tests
├── bootstrap.php           # PHPUnit bootstrap (loads .env files)
├── .env                    # Default environment variables (committed)
└── .env.local              # Local overrides with your webhook (git-ignored)
```

--------------------------------

### Add disk() accessor test to IMServiceBuilderTest

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/superpowers/plans/2026-04-19-im-disk-folder-get.md

Adds a test method to verify that the service builder returns a Disk instance and that repeated calls return the same instance. This test will fail until the disk() method is implemented.

```php
use Bitrix24\SDK\Services\IM\Disk\Service\Disk;

public function testGetDiskService(): void
{
    $this->assertInstanceOf(Disk::class, $this->serviceBuilder->disk());
    $this->assertSame($this->serviceBuilder->disk(), $this->serviceBuilder->disk());
}
```

--------------------------------

### Run PHPStan lint

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/README.md

Runs the PHPStan static analysis tool via the project's Makefile. Use this command to check the codebase for static analysis issues.

```shell
make lint-phpstan
```

--------------------------------

### Pattern for using flusher in test methods

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/plans/2026-04-15-partner-repository-flusher-design.md

Shows the pattern to follow in test methods: obtain the flusher before save, then call flush() after save. This pattern is taken from Bitrix24AccountRepositoryInterfaceTest.

```php
$b24PartnerRepository = $this->createBitrix24PartnerRepositoryImplementation();
$flusher = $this->createRepositoryFlusherImplementation();

$b24PartnerRepository->save($b24Partner);
$flusher->flush();
```

--------------------------------

### Create DiskTest.php integration test

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/superpowers/plans/2026-04-19-im-disk-folder-get.md

Integration test for Disk::getFolderId. It creates a chat, calls getFolderId with the chat dialogId, asserts the folder ID is positive, and cleans up by leaving the chat in a finally block.

```php
<?php

declare(strict_types=1);

namespace Bitrix24\SDK\Tests\Integration\Services\IM\Disk\Service;

use Bitrix24\SDK\Core\Exceptions\BaseException;
use Bitrix24\SDK\Core\Exceptions\TransportException;
use Bitrix24\SDK\Services\IM\Disk\Service\Disk;
use Bitrix24\SDK\Tests\Integration\Factory;
use PHPUnit\Framework\Attributes\CoversClass;
use PHPUnit\Framework\TestCase;

#[CoversClass(Disk::class)]
final class DiskTest extends TestCase
{
    private Disk $diskService;

    #[[\Override]]
    protected function setUp(): void
    {
        $this->diskService = Factory::getServiceBuilder()->getIMScope()->disk();
    }

    /**
     * @throws BaseException
     * @throws TransportException
     */
    public function testGetFolderId(): void
    {
        $userId = (int)$this->diskService->core->call('PROFILE')->getResponseData()->getResult()['ID'];
        $chatId = (int)$this->diskService->core->call(
            'im.chat.add',
            [
                'USERS' => [$userId],
                'TYPE' => 'CHAT',
                'TITLE' => sprintf('IM Disk Test %s', time()),
            ]
        )->getResponseData()->getResult()[0];

        try {
            $folderId = $this->diskService->getFolderId(dialogId: 'chat' . $chatId)->getId();

            $this->assertGreaterThan(0, $folderId);
        } finally {
            $this->diskService->core->call('im.chat.leave', ['CHAT_ID' => $chatId]);
        }
    }
}
```

--------------------------------

### Result item pattern: DealItemResult with PHPDoc annotations

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/architecture.md

Shows the AbstractItem base class providing magic __get() and a result item with @property-read annotations for IDE support and static analysis. Usage demonstrates accessing fields type-safely.

```php
// AbstractItem base class provides magic __get()
// Result item only needs @property-read annotations for IDE support + static analysis

/**
 * @property-read int    $ID
 * @property-read string $TITLE
 * @property-read string $STATUS_ID
 */
class DealItemResult extends AbstractItem {}

// Usage
$deal = $dealService->get(42)->deal();
echo $deal->ID;     // int, type-safe via PHPDoc
echo $deal->TITLE;  // string
```

--------------------------------

### DateFieldConditionBuilder method signatures

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/src/Filters/docs/README.md

Lists the available methods for date/datetime fields, accepting both DateTime objects and strings.

```php
public function eq(DateTime|string $value): AbstractFilterBuilder;
public function neq(DateTime|string $value): AbstractFilterBuilder;
public function gt(DateTime|string $value): AbstractFilterBuilder;
public function gte(DateTime|string $value): AbstractFilterBuilder;
public function lt(DateTime|string $value): AbstractFilterBuilder;
public function lte(DateTime|string $value): AbstractFilterBuilder;
public function between(DateTime|string $from, DateTime|string $to): AbstractFilterBuilder;
```

--------------------------------

### Batch List CRM Contacts with Pagination

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/resources/skills/b24phpsdk-developer/references/result-handling.md

Use the batch helper for full scans of CRM contacts. It reduces boilerplate for multi-page traversal but still calls Bitix24 REST under the hood; keep limits bounded and design processing to resume safely after partial failure.

```php
foreach ($serviceBuilder->getCRMScope()->contact()->batch->list(
    ['ID' => 'ASC'],
    [],
    ['ID', 'NAME', 'LAST_NAME'],
    500,
) as $contact) {
    // Process ContactItemResult.
}
```

--------------------------------

### Check Public URL with curl and Verify Headers

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/README.md

Checks the public URL from ngrok and verifies the x-powered-by header with a 200 status code. The output shows the expected response headers.

```shell
curl https://****.ngrok-free.app -I
HTTP/2 200 
content-type: text/html; charset=UTF-8
date: Mon, 26 Aug 2024 19:09:24 GMT
host: ****.ngrok-free.app
x-powered-by: PHP/8.3.8
```

--------------------------------

### Define ContactDirectory interface for SDK boundary

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/resources/skills/b24phpsdk-developer/SKILL.md

Defines a product-owned interface for retrieving recent contacts. Domain and application services depend on this interface instead of SDK service classes, keeping SDK-specific code in an infrastructure adapter and making unit tests cheap.

```php
interface ContactDirectory
{
    /**
     * @return list<array{id: int, name: string}>
     */
    public function recentContacts(int $limit): array;
}
```

--------------------------------

### Incremental reads

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/main-user-history.md

Shows how to iterate over user history entries using a tail cursor, restoring a checkpoint and persisting the new checkpoint after processing.

```APIDOC
## Incremental reads

### Description
Iterate over user history entries using a tail cursor. Restore a previously saved checkpoint and persist a new checkpoint after processing each page.

### Method
Not applicable (SDK method call)

### Endpoint
`$main->userHistory()->tail($userId, $checkpoint)`

### Parameters
- `$userId` (int) - Required - The user ID to read history for.
- `$checkpoint` (UserHistoryTailCursor) - Required - The cursor object representing the last processed position.

### Request Example
```php
$checkpoint = new UserHistoryTailCursor(value: 0);
do {
    $page = $main->userHistory()->tail($userId, $checkpoint);
    foreach ($page->getUserHistoryItems() as $entry) {
        // Process each entry. Persist a new checkpoint only after processing succeeds.
    }

    $cursor = $page->getCursor();
    if ($cursor === null || $cursor['value'] === null) {
        break; // Retain the last checkpoint for the next poll.
    }

    $checkpoint = new UserHistoryTailCursor($cursor['value'], $cursor['field']);
    // Persist $checkpoint->toArray() here, using the validated integer request value.
} while ($page->hasMore());
```

### Response
- `$page->getUserHistoryItems()` - array of user history entries.
- `$page->getCursor()` - array with keys `field` and `value`; may be null or contain null value.
- `$page->hasMore()` - boolean indicating if more pages exist.

### Notes
- `getCursor()` preserves numeric strings, integer values, and null.
- An empty response can contain `['field' => 'id', 'value' => null]`; do not turn that value into zero or discard your last checkpoint.
- Request cursors safely normalize decimal ID strings to integers because the API rejects string ID request values.
- The API rejects null, invalid ID positions, and values exceeding PHP_INT_MAX instead of truncating them.
- The default order is ascending; a request may explicitly use `SortOrder::Descending`. Preserve the chosen order when continuing that traversal because response cursors contain only field and value.
```

--------------------------------

### Veto portal domain changes with PortalDomainUrlChangingEvent

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/portal-domain-redirects.md

Register a listener on the dispatcher passed to CoreBuilder to veto portal domain changes. The listener calls deny() to reject the transition, and the catch block handles the thrown PortalDomainChangeRejectedException, retrieving old/new URLs and the denial reason. Denial is irreversible for that event; an empty reason still denies, and retrying without changing the decision fails again.

```php
use Bitrix24\SDK\Core\CoreBuilder;
use Bitrix24\SDK\Core\Exceptions\PortalDomainChangeRejectedException;
use Bitrix24\SDK\Events\PortalDomainUrlChangingEvent;
use Symfony\Component\EventDispatcher\EventDispatcher;

$dispatcher = new EventDispatcher();
$dispatcher->addListener(
    PortalDomainUrlChangingEvent::class,
    static function (PortalDomainUrlChangingEvent $event): void {
        // This application requires reinstallation to approve any new portal address.
        $event->deny('Portal domain must be updated through reinstallation');
    }
);

// $credentials is your existing OAuth Credentials instance.
$core = (new CoreBuilder())
    ->withCredentials($credentials)
    ->withEventDispatcher($dispatcher)
    ->build();

try {
    $core->call('app.info');
} catch (PortalDomainChangeRejectedException $exception) {
    $oldUrl = $exception->getOldDomainUrl();
    $newUrl = $exception->getNewDomainUrl();
    $reason = $exception->getDenialReason();
    // Ask the application owner to approve the move or reinstall the application.
    // Retrying without changing the application's decision will fail again.
}
```

--------------------------------

### Services scope directory layout

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/architecture.md

Shows the standard directory layout for a Bitrix24 API scope under src/Services/. Each scope follows this structure with a ServiceBuilder factory, service and batch classes, and result types.

```text
src/Services/<Scope>/
├── <Scope>ServiceBuilder.php          ← factory, registered in ServiceBuilder
├── Service/
│   ├── <Entity>.php                   ← main service (extends AbstractService)
│   └── Batch.php                      ← batch wrapper (when applicable)
└── Result/
    ├── <Entity>ItemResult.php         ← single item (@property-read annotations)
    ├── <Entity>Result.php             ← single-entity response
    └── <Entity>sResult.php            ← list response
```

--------------------------------

### Read PR template with cat

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/CLAUDE.md

Use this command to read the pull request template before composing a PR body. The template's exact structure must be followed.

```bash
cat .github/PULL_REQUEST_TEMPLATE.md
```

--------------------------------

### IntFieldConditionBuilder method signatures

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/src/Filters/docs/README.md

Lists the available methods for integer fields, enforcing int parameters for equality, comparison, and range operations.

```php
public function eq(int $value): AbstractFilterBuilder;
public function neq(int $value): AbstractFilterBuilder;
public function gt(int $value): AbstractFilterBuilder;
public function gte(int $value): AbstractFilterBuilder;
public function lt(int $value): AbstractFilterBuilder;
public function lte(int $value): AbstractFilterBuilder;
public function in(array $values): AbstractFilterBuilder;
public function between(int $min, int $max): AbstractFilterBuilder;
```

--------------------------------

### Create FolderIdResult.php

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/superpowers/plans/2026-04-19-im-disk-folder-get.md

Creates the FolderIdResult wrapper class that extends AbstractResult and provides a getId() method to extract the folder ID from the core response.

```php
<?php

declare(strict_types=1);

namespace Bitrix24\SDK\Services\IM\Disk\Result;

use Bitrix24\SDK\Core\Result\AbstractResult;

final class FolderIdResult extends AbstractResult
{
    public function getId(): int
    {
        return (int)$this->getCoreResponse()->getResponseData()->getResult()['ID'];
    }
}

```

--------------------------------

### Set BITRIX24_WEBHOOK in tests/.env.local

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/testing.md

Required environment variable for integration tests. Set the incoming webhook URL for your Bitrix24 portal.

```dotenv
BITRIX24_WEBHOOK=https://your-portal.bitrix24.com/rest/1/your-webhook-token/
```

--------------------------------

### Fix coding standards with make lint commands

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/CONTRIBUTING.md

Commands to fix coding standards. Run these in order to check and fix code style issues.

```shell
make lint-phpstan
make lint-rector
make lint-rector-fix
```

--------------------------------

### BoolFieldConditionBuilder method signatures

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/src/Filters/docs/README.md

Lists the available methods for boolean fields, automatically converting to Bitrix24's Y/N format.

```php
public function eq(bool $value): AbstractFilterBuilder;
public function neq(bool $value): AbstractFilterBuilder;
```

--------------------------------

### StringFieldConditionBuilder method signatures

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/src/Filters/docs/README.md

Lists the available methods for text fields, enforcing string parameters for equality and inequality checks.

```php
public function eq(string $value): AbstractFilterBuilder;
public function neq(string $value): AbstractFilterBuilder;
public function in(array $values): AbstractFilterBuilder;
```

--------------------------------

### Add import for TestRepositoryFlusherInterface

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/plans/2026-04-15-partner-repository-flusher-design.md

Adds the use statement for TestRepositoryFlusherInterface to the test file. Place after the existing use block.

```php
use Bitrix24\SDK\Tests\Application\Contracts\TestRepositoryFlusherInterface;
```

--------------------------------

### Raw Array Fallback

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/src/Filters/docs/README.md

Shows using setRaw() to provide a raw array for edge cases or unsupported scenarios. The raw array is used directly.

```php
$filter = (new TaskFilter())
    ->title()->eq('Task')
    ->setRaw([
        ['customField', '=', 'value'],
        ['anotherField', '!=', 'test']
    ]);

// Result: raw array is used directly
```

--------------------------------

### Commit red tests

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/superpowers/plans/2026-04-19-im-disk-folder-get.md

Git commands to stage and commit the failing tests.

```bash
git add tests/Unit/Services/IM/IMServiceBuilderTest.php tests/Unit/Services/IM/Disk/Service/DiskTest.php
git commit -m "test: lock IM disk service contract"
```

--------------------------------

### Integration test environment variables

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/README.md

Environment variables required for integration tests. Set BITRIX24_WEBHOOK to your test Bitrix24 account's inbound webhook URL and INTEGRATION_TEST_LOG_LEVEL to control logging. Do not use production accounts.

```dotenv
BITRIX24_WEBHOOK=https://your-portal.bitrix24.com/rest/1/your-webhook-token/
INTEGRATION_TEST_LOG_LEVEL=100
```

--------------------------------

### Fix PHPUnit var directory permissions

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/testing.md

Fix PHPUnit permission errors by changing ownership of the var directory to the www-data user inside the php-cli container.

```bash
docker-compose run --rm php-cli chown -R www-data:www-data /var/www/html/var/
```

--------------------------------

### Run Deptrac layer checks with make lint-deptrac

Source: https://github.com/bitrix24/b24phpsdk/blob/v3/docs/testing.md

Run Deptrac layer enforcement checks. This command is also included in `make lint-all` as part of the full quality gate.

```bash
make lint-deptrac          # check only
```
Tokens:
Raw