rodrigofr/bitrix24-laravel-sdk

A Laravel wrapper for the Bitrix24 PHP SDK, providing seamless integration for Bitrix24 applications.

dev-main 2025-06-04 01:30 UTC

Requires

• php: ^8.2
• bitrix24/b24phpsdk: ^5.0
• illuminate/contracts: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0
• laravel/framework: ^10.0|^11.0|^12.0

MIT

• Rodrigo Fernandez

README

A robust and easy-to-use wrapper to integrate the Bitrix24 PHP SDK into your Laravel applications. This package handles authentication, installation callbacks, and provides convenient access to Bitrix24 API services.

🌟 Features

• Simple Integration: Quick setup using a Laravel Service Provider.
• Authentication Handling: Automatically manages OAuth 2.0 flow and token retrieval during installation and usage.
• API Access: Provides a pre-configured Bitrix24 ServiceBuilder to interact with all Bitrix24 API services (CRM, Users, Tasks, etc.).
• Example Controller: Includes a controller with routes and views to quickly get started.
• Views and Config Management: Easily publish and customize the package views and config.

🚀 Installation

1. Add the package to your Laravel project:

   composer require rodrigofr/bitrix24-laravel-sdk

2. Publish the package configuration file:

   php artisan vendor:publish --provider="Rodrigofr\\Bitrix24LaravelSdk\\Bitrix24ServiceProvider" --tag="bitrix24-laravel-sdk-config"

   This will create the file config/bitrix24.php.

3. Configure your Bitrix24 credentials in your .env file:

   BITRIX24_CLIENT_ID="YOUR_BITRIX24_CLIENT_ID"
   BITRIX24_CLIENT_SECRET="YOUR_BITRIX24_CLIENT_SECRET"
   BITRIX24_SCOPE="user,crm,telephony,disk,bizproc"

4. Configure your Bitrix24 application:

   In the Bitrix24 Developer Portal, set the following URLs:

   • Install URL: https://your-app-domain.com/bitrix24/install
   • Redirect URL / Application URL: https://your-app-domain.com/bitrix24/app

5. Clear route cache (important):

   php artisan optimize:clear

💡 Basic Usage

1. Included Routes

The package registers the following essential routes:

• POST /bitrix24/install: Handles installation callback from Bitrix24.
• GET|POST /bitrix24/app: Main entry point of your Bitrix24 app.
• POST /bitrix24/api/create-lead: Example route to create a CRM lead.
• GET /bitrix24/users: Example route to get Bitrix24 users (e.g. /bitrix24/users?ids=1,5,10).

If your domain is mi-app-laravel.com, the URLs would look like:

• https://mi-app-laravel.com/bitrix24/install
• https://mi-app-laravel.com/bitrix24/app
• https://mi-app-laravel.com/bitrix24/users

2. API Access in Controllers

Inject Bitrix24ServiceProvider into any controller or service class:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Rodrigofr\Bitrix24LaravelSdk\Bitrix24ServiceProvider;
use Psr\Log\LoggerInterface;

class MyCustomController extends Controller
{
    protected Bitrix24ServiceProvider $bitrix24ServiceProvider;
    protected LoggerInterface $logger;

    public function __construct(Bitrix24ServiceProvider $bitrix24ServiceProvider, LoggerInterface $logger)
    {
        $this->bitrix24ServiceProvider = $bitrix24ServiceProvider;
        $this->logger = $logger;
    }

    public function fetchBitrix24Data()
    {
        try {
            $b24Service = $this->bitrix24ServiceProvider->getServiceBuilder();

            $userProfileResult = $b24Service->getMainScope()->main()->getCurrentUserProfile();

            if ($userProfileResult->isSuccess()) {
                $userProfile = $userProfileResult->getUserProfile();
                return response()->json($userProfile->toArray());
            } else {
                $error = $userProfileResult->getError();
                $this->logger->error('Bitrix24 API Error: ' . $error->toJson());
                return response()->json(['error' => 'Could not retrieve user profile'], 500);
            }

        } catch (\Throwable $e) {
            $this->logger->error('Error communicating with Bitrix24: ' . $e->getMessage());
            return response()->json(['error' => 'Unexpected error occurred.'], 500);
        }
    }
}

3. Publish Views

To customize the default package views:

php artisan vendor:publish --provider="Rodrigofr\\Bitrix24LaravelSdk\\Bitrix24ServiceProvider" --tag="bitrix24-laravel-sdk-views"   `

This will copy the views to:

resources/views/vendor/bitrix24-laravel-sdk   `

⚠️ Important Considerations

Token Persistence:

To use Bitrix24 API from outside Bitrix24's iframe context (e.g., background jobs, Artisan commands), implement a mechanism to securely store and retrieve access and refresh tokens. The SDK handles token refreshing, but persistence is your responsibility.

Error Handling:

Always check ->isSuccess() on SDK results and handle errors via ->getError().

Scope Management:

Ensure the BITRIX24_SCOPE values in your .env match those set in your Bitrix24 app config. Changing scopes often requires reinstalling the app in Bitrix24.

🤝 Contributing

Contributions are welcome! If you discover a bug or have suggestions for improvement, feel free to open an issue or submit a pull request.

📄 License

This package is open-sourced software licensed under the MIT license.