B24Phpsdk Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Laravel/PHP Compatibility: The SDK targets PHP 8.2+ for v1 and PHP 8.4+ for v3, aligning with modern Laravel releases. Release 3.7.0 continues to build on Symfony HttpClient and typed DTOs, which fit Laravel’s service-container and dependency-injection patterns.
  • Abstraction Layers: The ApiClient → Services/* structure remains compatible with Laravel’s repository/service patterns. The expanded service coverage reduces the need for custom Bitrix24 API wrappers.
  • New in 3.7.0 — Incremental Sync: REST v3 user history, field-change, and metadata services with cursor-based incremental reads are a strong fit for Laravel scheduled jobs and queue workers. This enables efficient delta sync instead of full polling.
  • New in 3.7.0 — Batch Coverage: Batch support for Services\Landing and Services\Sale scopes improves bulk-operation performance for CRM, e-commerce, and landing-page workflows. This is directly relevant to Laravel queue-driven integrations.
  • New in 3.7.0 — Security Control: PortalDomainUrlChangingEvent with irreversible deny() and PortalDomainChangeRejectedException allows the application to veto portal redirects before credentials change or tokens are sent to the destination. This is important for multi-portal and marketplace-style Laravel applications.
  • Expanded API Coverage: New legacy coverage for Pull, Voximplant callback, timeman, SonetGroup, Disk search/sharing, and log endpoints reduces custom endpoint development.
  • Modern PHP Features: Typed method signatures, immutable DTOs, and strict typing align with Laravel’s evolving codebase.

• Cons:

  • v3 Migration Still Requires Work: The /rest/ → /rest/api/ endpoint change remains a consideration when migrating from v1. Release 3.7.0 improves v3 maturity but does not remove the v1-to-v3 migration cost.
  • Legacy IMBot Deprecations: The release documents legacy IMBot method deprecations and replacements. Existing Laravel integrations using IMBot should plan migration work.
  • Monolithic Service Surface: The SDK remains broad. Laravel teams may still prefer splitting domain-specific integrations into smaller internal packages (e.g., CRM, Sale, Landing).
  • No Laravel-Specific Integrations: The SDK still does not provide Laravel-native queue jobs, Eloquent models, or Scout integration out of the box. These must be built on top.

Integration Feasibility

• Laravel Service Provider:
  • The SDK can be bound into Laravel’s container via a Service Provider, enabling dependency injection in controllers, jobs, and services.
  • Example:

    public function register(): void
    {
        $this->app->singleton(Bitrix24Service::class, function ($app) {
            return ServiceBuilderFactory::createServiceBuilderFromToken(
                config('bitrix24.token'),
                config('bitrix24.portal')
            );
        });
    }
    

• Configuration:
  • Laravel’s config/bitrix24.php can centralize credentials (token, portal URL, scopes). Environment variables (.env) can override sensitive values.
• Authentication:
  • Supports token-based auth and webhooks. OAuth2 flows for marketplace apps can be integrated with Laravel’s auth or custom OAuth2 logic.
• New Security Integration Point:
  • PortalDomainUrlChangingEvent should be wired into Laravel’s event system or a dedicated listener to reject unsafe portal redirects before credential changes occur.
• New Sync Integration Point:
  • REST v3 user history and field-change services with cursor-based reads can be wrapped in queued Laravel jobs for incremental synchronization.

Technical Risk

• Version Selection:
  • v1: Lower migration risk for existing production integrations but lacks newer v3 capabilities.
  • v3 (3.7.0): Risk has decreased due to broader service coverage, batch support, incremental sync, and portal-redirection security controls. However, migration from v1 still requires endpoint changes and regression testing.
  • Mitigation: Keep v1 in production where already stable; pilot v3 3.7.0 in staging, especially for new integrations requiring incremental sync, Sale/Landing batch operations, or portal-redirection controls.
• Deprecation Risk:
  • Legacy IMBot methods are documented as deprecated. Teams using IMBot should inventory usage and plan replacements.
• Error Handling:
  • Symfony ResponseInterface can be translated into Laravel exceptions and logged via Laravel’s log channels.
• Rate Limiting:
  • Bitrix24 API rate limits remain relevant. New batch support for Sale and Landing reduces request volume, but Laravel queues should still handle retries and backoff.
• Testing:
  • Unit tests can mock SDK services. End-to-end tests still require a Bitrix24 sandbox account.

Key Questions

1. Use Case Scope:
   • Is the integration read-heavy, write-heavy, or event-driven?
   • Does the application require incremental user/field-change synchronization via the new REST v3 services?
2. Data Model Mapping:
   • How will Bitrix24 entities map to Laravel models or DTOs?
   • Will raw SDK responses be used directly, or will custom domain models be created?
3. Batch Operations:
   • Can Sale or Landing workflows leverage the new batch services to reduce API calls?
4. Security Requirements:
   • Does the application need to veto portal domain changes before tokens or credentials are sent to a new destination?
5. Deprecations:
   • Does the existing integration rely on legacy IMBot methods? If so, what is the replacement timeline?
6. Maintenance Ownership:
   • Who owns SDK upgrades, v1-to-v3 migration, and custom Laravel integrations?
7. Token Storage:
   • How will tokens be stored: Laravel config, Vault, or another secrets manager?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • HTTP Client: Symfony HttpClient is compatible with Laravel applications. Laravel’s Http facade can be used alongside or around custom wrappers where consistency is needed.
  • Queues: Laravel queues can handle Bitrix24 API retries, backoff, and bulk synchronization.
  • Events: Bitrix24 webhooks can trigger Laravel events via a webhook controller.
  • New Security Events: PortalDomainUrlChangingEvent can be handled in a Laravel listener to enforce credential-safety policy.
  • Testing: Pest/PHPUnit can mock SDK services; integration tests require a Bitrix24 sandbox.
• Database:
  • Bitrix24 data can be cached or synced into Laravel tables. New cursor-based incremental reads simplify sync-state tracking.
  • Custom tables may be needed for sync cursors, metadata, and entity mapping.

Migration Path

1. Pilot Phase (v3 3.7.0):
   • Install the SDK in a Laravel module.
   • Implement a Service Provider to bind SDK services.
   • Build a minimal integration, such as CRM lead sync or Sale batch operations.
   • Test with mocked responses and a sandbox account.
2. Stable Integration:
   • Add error handling, logging, and queued jobs for write operations.
   • Implement incremental sync using REST v3 user history/field-change services where applicable.
   • Wire PortalDomainUrlChangingEvent if the application manages multiple portals or marketplace flows.
3. Deprecation Cleanup:
   • Inventory IMBot usage and replace deprecated methods with documented alternatives.
4. Advanced Features:
   • Adopt Sale/Landing batch services for bulk operations.
   • Add webhook listeners for event-driven workflows.

Compatibility

• PHP Version:
  • Ensure Laravel and PHP versions match the selected SDK major version. v3 requires PHP 8.4+; v1 targets PHP 8.2+.
• Dependencies:
  • The SDK relies on common Symfony components and standard PHP extensions such as ext-json and ext-curl, which are typically enabled in Laravel.
• Laravel Features:
  • Eloquent can be used alongside the SDK for local persistence.
  • Laravel Horizon can monitor queued Bitrix24 sync jobs.
  • Laravel Telescope can assist with SDK call observability.

Sequencing

1. Phase 1: Core Integration (2–4 weeks):
   • Install and configure the SDK.
   • Implement authentication and Service Provider bindings.
   • Build basic CRUD for 1–2 entities.
2. Phase 2: Data Sync (3–6 weeks):
   • Implement queued jobs for bulk operations.
   • Adopt cursor-based incremental reads for user/field-change sync.
   • Add caching where frequent reads are required.
3. Phase 3: Real-Time and Security (2–4 weeks):
   • Set up webhook endpoints and Laravel event listeners.
   • Integrate PortalDomainUrlChangingEvent if portal redirect controls are needed.
4. Phase 4: Optimization (Ongoing):
   • Adopt Sale/Landing batch services.
   • Profile API usage, queue throughput, and error rates.
   • Address IMBot deprecations and monitor future SDK releases.

Operational Impact

Maintenance

• SDK Updates:
  • Track GitHub releases for breaking changes, deprecations, and new batch coverage.
  • Pin SDK versions in composer.json and test updates in staging before production.
• Deprecation Management:
  • Legacy IMBot methods are now explicitly deprecated. Maintain an inventory and migration backlog.
• Custom Extensions:
  • If the SDK lacks Laravel-specific features, keep custom Eloquent, Scout, or queue integrations in separate internal packages.

Support

• Security Support:
  • The new portal-domain-change veto improves supportability for multi-portal and marketplace scenarios by preventing unsafe credential forwarding.
• Observability:
  • Log SDK exceptions through Laravel’s logging stack. Use Horizon and Telescope for queue and API visibility.
• Documentation:
  • New endpoints and deprecations should be reflected in internal integration docs.

Scaling

• Batch Operations:
  • Sale and Landing batch support reduces request volume and improves throughput for bulk workflows.
• Incremental Sync:
  • Cursor-based REST v3 reads reduce full-polling load and support scalable delta synchronization.
• Queue Design:
  • Rate-limit-sensitive operations should run through Laravel queues with backoff and retry policies.

Failure Modes

• Migration Regression:
  • v1-to-v3 endpoint changes and DTO differences can cause integration regressions without adequate test coverage.
• Deprecated IMBot Calls:
  • Reliance on deprecated IMBot methods may create future breakage.
• Portal Redirect Risk:
  • Without handling PortalDomainUrlChangingEvent, multi-portal applications may forward credentials or tokens to an unintended destination.
• API Rate Limits:
  • Poorly queued bulk operations can still hit Bitrix24 rate limits despite batch support.

Ramp-up

• Team Learning:
  • Engineers need familiarity with the SDK’s service structure, DTOs, batch services, and cursor-based sync patterns.
• Security Review:
  • The portal-domain-change event should be reviewed by the team responsible for credentials and marketplace security.
• Documentation:
  • Internal runbooks should cover SDK upgrades, deprecation tracking, queue retries, and sandbox testing.