Foursquare Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require amf/foursquare-bundle
   

   Register the bundle in config/bundles.php (Symfony 4+):

   return [
       // ...
       Amf\FourSquareBundle\AmfFourSquareBundle::class => ['all' => true],
   ];
   

2. Configuration Add Foursquare API credentials to config/packages/amf_foursquare.yaml:

   amf_foursquare:
       client_id: '%env(FOURSQUARE_CLIENT_ID)%'
       client_secret: '%env(FOURSQUARE_CLIENT_SECRET)%'
   

3. First Use Case: Scanning Venues Inject the VenueScanner service in a controller:

   use Amf\FourSquareBundle\Service\VenueScanner;
   
   class LocationController extends AbstractController
   {
       public function scanVenues(VenueScanner $scanner)
       {
           $venues = $scanner->scan('40.7128° N, 74.0060° W', 1000); // Lat/Lon + radius (meters)
           return $this->json($venues);
       }
   }
   

Implementation Patterns

Core Workflows

1. Venue Discovery

   • Use VenueScanner for proximity-based searches:

     $scanner->scan($latitude, $longitude, $radius, $limit = 20);
     

   • Filter results by category (e.g., "Food" or "Nightlife"):

     $scanner->scanWithCategory($lat, $lon, $radius, '4d4b7105d48988d1066d1fe3');
     

2. Service Integration

   • Symfony Forms: Bind venue data to form fields using VenueType (if provided by the bundle).
   • API Caching: Decorate VenueScanner to cache responses (e.g., with Symfony Cache component):

     $cache = $this->container->get('cache.app');
     $cachedVenues = $cache->get('venues_' . $lat . '_' . $lon);
     

3. Event-Driven Extensions

   • Subscribe to bundle events (if documented) to modify responses:

     // Example (hypothetical event)
     $dispatcher->addListener('amf_foursquare.venue.scanned', function ($event) {
         $event->getVenues()->filter(fn($v) => $v['price'] > 50);
     });
     

Gotchas and Tips

Pitfalls

1. Deprecated API

   • The bundle uses Foursquare’s v1 API (discontinued in 2018). Replace endpoints with Foursquare’s v2 API manually:

     $client = new \GuzzleHttp\Client();
     $response = $client->request('GET', 'https://api.foursquare.com/v2/venues/search', [
         'query' => [
             'client_id' => $this->config['client_id'],
             'client_secret' => $this->config['client_secret'],
             'v' => '20230601',
             'll' => $lat . ',' . $lon,
             'radius' => $radius,
         ]
     ]);
     

2. No Modern Symfony Support

   • The bundle targets Symfony 2.x. For Symfony 4/5/6:
     • Use a service alias or decorator to bridge the gap.
     • Example decorator:

       # config/services.yaml
       Amf\FourSquareBundle\Service\VenueScanner:
           decorates: 'amf_foursquare.venue_scanner'
           arguments: ['@Amf\FourSquareBundle\Service\VenueScanner.inner']
       

3. Missing Documentation

   • The Resources/doc folder is empty in the repo. Refer to:
     • Foursquare API v2 Docs for endpoint details.
     • Symfony 2 Service Container for dependency injection.

Debugging Tips

1. API Rate Limits

   • Foursquare’s v2 API has strict rate limits (500 requests/hour for free tier). Implement exponential backoff:

     use Symfony\Component\HttpClient\RetryableHttpClient;
     
     $client = new RetryableHttpClient(
         new \Symfony\Contracts\HttpClient\HttpClient(),
         [
             'max_retries' => 3,
             'delay' => 1000, // 1 second
         ]
     );
     

2. Response Validation

   • Validate Foursquare’s JSON response structure:

     $response = json_decode($client->getResponse()->getContent(), true);
     if (!isset($response['response']['venues'])) {
         throw new \RuntimeException('Invalid Foursquare API response');
     }
     

Extension Points

1. Custom Venue Models

   • Map Foursquare’s raw data to your domain models:

     class VenueMapper
     {
         public function map(array $foursquareData): Venue
         {
             return new Venue(
                 id: $foursquareData['id'],
                 name: $foursquareData['name'],
                 location: $foursquareData['location']['address'] ?? null
             );
         }
     }
     

2. Geocoding Integration

   • Combine with a geocoding service (e.g., Google Maps) to resolve addresses:

     $geocoder = new \Geocoder\Provider\GoogleMaps\Provider();
     $coordinates = $geocoder->geocode('1600 Amphitheatre Parkway');
     $venues = $scanner->scan($coordinates->getLatitude(), $coordinates->getLongitude(), 1000);
     

3. Testing

   • Mock the VenueScanner in tests:

     $this->container->set('amf_foursquare.venue_scanner', $this->createMock(VenueScanner::class));