Api Client Laravel Package

Technical Evaluation

Architecture Fit

• Pros:
  • Niche specialization: Directly targets 2GIS API (regions, catalogs, transport, geodata), reducing boilerplate for Russian-market geospatial features.
  • Laravel alignment: Composer-based installation integrates seamlessly with Laravel’s dependency management and service container.
  • MIT license: Permissive terms enable commercial use without legal friction.
  • Modular design: Separates API endpoints (regions, catalog, transport, geo), allowing selective adoption.
• Cons:
  • Legacy codebase: Last release in 2014 risks incompatibility with PHP 8.x/Laravel 9+ (e.g., deprecated curl usage, lack of type hints).
  • No Laravel-specific optimizations: Missing features like Eloquent models, Scout drivers, or queue-based retries.
  • Alpha-stage transport/geo APIs: Unstable interfaces may require frequent patches.
  • No built-in caching: Forces manual Redis/database caching for rate-limited endpoints.

Integration Feasibility

• Laravel Compatibility:
  • Service Provider: Can be registered as a singleton with DI container (e.g., app['2gis']).
  • Configurable: Supports config/2gis.php for API keys, endpoints, and rate limits.
  • Facade Pattern: Can wrap raw API calls (e.g., 2gis()->regions()->get()).
• Technical Debt:
  • PHP 8.x Upgrades: May need rector or manual fixes for array() → [], foreach changes, or curl deprecations.
  • HTTP Client: Underlying curl/file_get_contents may need replacement with Guzzle for modern Laravel apps.
  • Testing: Requires custom tests due to lack of built-in test suite.

Technical Risk

Key Questions

1. Is 2GIS API v2.0 still viable?
   • Verify with 2GIS support or check their API docs for deprecations.
2. What’s the PHP 8.x upgrade effort?
   • Run phpstan/rector to estimate fixes (e.g., array() → [], foreach changes).
3. Are there modern alternatives?
   • Compare with 2GIS’s official PHP SDK (if available) or community forks.
4. How will we handle rate limits?
   • Plan for Laravel queues or Redis caching to avoid throttling.
5. What’s the fallback if the package breaks?
   • Implement a Guzzle-based direct API client as a backup.

Integration Approach

Stack Fit

• Laravel Ecosystem:

  • Service Provider: Register the client as a singleton with Laravel’s container.

    // app/Providers/2gisServiceProvider.php
    public function register()
    {
        $this->app->singleton('2gis', function ($app) {
            return new \TwoGis\Client(config('2gis.key'));
        });
    }
    

  • Config File: Centralize API keys and endpoints in config/2gis.php.

    return [
        'key' => env('TWOGIS_API_KEY'),
        'endpoints' => [
            'regions' => 'https://api.2gis.com/2.0/regions',
            'catalog' => 'https://api.2gis.com/2.0/catalog',
        ],
        'rate_limit' => 1000, // requests/hour
    ];
    

  • Facade: Create a clean 2gis() helper (e.g., via laravel-shift/blueprint).
  • Eloquent Models: Extend with custom accessors for geodata (e.g., Point objects).
  • Scout Driver: Build a 2GIS-powered geospatial search driver for Laravel Scout.

• PHP Version:

  • Polyfills: Use rector to upgrade deprecated PHP features (e.g., array() → []).
  • Testing: Validate with PHP 8.1+ and Laravel 9/10 via phpunit + pest.

Migration Path

1. Phase 1: PoC (1–2 weeks)
   • Install via Composer ("2gis/api-client": "dev-master").
   • Test basic endpoints (regions, catalog) in a sandbox.
   • Document response formats vs. 2GIS API specs.
2. Phase 2: Core Integration (2–3 weeks)
   • Implement Service Provider, config, and facade.
   • Add rate limiting (e.g., spatie/laravel-rate-limiter).
   • Replace curl with Guzzle if needed.
3. Phase 3: Advanced Features (3–4 weeks)
   • Build Eloquent models for geodata (e.g., Region, Business).
   • Integrate with Laravel Scout for geospatial search.
   • Add queue-based retries for async API calls.
4. Phase 4: Monitoring (Ongoing)
   • Set up health checks (e.g., laravel-health).
   • Monitor error rates and rate limits via Sentry/New Relic.

Compatibility

• Laravel Versions:
  • Test with Laravel 9/10 (PHP 8.1+). Use composer platform-check to flag issues.
• PHP Extensions:
  • Ensure curl, json, and mbstring are enabled (required by 2GIS API).
• Database:
  • Cache responses in Redis or database to reduce API calls.
  • Use Laravel Queues for bulk operations (e.g., busy:handle).

Sequencing

1. Regions API (Highest stability)
   • Use for localization (e.g., dropdowns, filters).
2. Catalog API (Stable)
   • Power business directories or "nearby" features.
3. Transport API (Alpha)
   • Prototype route planning (expect changes).
4. Geo API (Alpha)
   • Use for geocoding (address → coordinates).

Operational Impact

Maintenance

• Short-Term:
  • High effort: Expect PHP 8.x upgrades, bug fixes, and API spec validation.
  • Documentation: Reverse-engineer usage from 2GIS docs; create internal runbooks.
• Long-Term:
  • Forking risk: If 2GIS deprecates v2.0, plan to rewrite or switch to an official SDK.
  • Dependency updates: Monitor composer audit for security advisories.

Support

• Community:
  • No active maintainers: Rely on 2GIS’s official docs or fork the repo.
  • GitHub issues: Open feature requests to gauge community interest.
• Internal:
  • Assign a tech lead to own the integration and document workarounds.
  • Create a troubleshooting guide for common failures (e.g., rate limits, auth errors).

Scaling

• Rate Limits:
  • Implement exponential backoff (e.g., spatie/backoff) or queue-based retries.
  • Cache responses in Redis (e.g., laravel-redis) or database (e.g., laravel-cache).
• Performance:
  • Use Laravel Queues for async API calls (e.g., busy:handle).
  • Batch requests where possible (e.g., fetch 100 regions in one call).
• Monitoring:
  • Track API latency and error rates via Sentry or New Relic.
  • Set up alerts for rate limit breaches.

Failure Modes

| Failure | Impact