Squarespace Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require beloop/squarespace
   

   • Verify composer.json for PHP 7.2+ compatibility and Symfony dependencies.

2. Service Provider Setup: Since the package lacks Laravel-native integration, manually bind the Symfony-based SquarespaceManager in AppServiceProvider:

   use Beloop\Squarespace\SquarespaceManager;
   use Symfony\Component\HttpClient\HttpClient;
   
   public function register()
   {
       $this->app->singleton(SquarespaceManager::class, function ($app) {
           return new SquarespaceManager(
               HttpClient::create(['base_uri' => config('squarespace.api_url')]),
               config('squarespace.api_key')
           );
       });
   }
   

3. Configuration: Add to config/services.php or a new config/squarespace.php:

   'squarespace' => [
       'api_url' => 'https://api.squarespace.com/1.0',
       'api_key' => env('SQUARESPACE_API_KEY'),
       'site_id' => env('SQUARESPACE_SITE_ID'),
   ],
   

4. First Use Case: Fetch a Squarespace site’s collections (e.g., courses):

   use Beloop\Squarespace\SquarespaceManager;
   
   public function getCollections(SquarespaceManager $squarespace)
   {
       $response = $squarespace->get('/collections');
       return json_decode($response->getContent(), true);
   }
   

   (Note: Replace /collections with the actual endpoint from the package’s docs.)

Implementation Patterns

1. API Client Wrapper

Pattern: Use the package as a Symfony HTTP client wrapper for Squarespace’s REST API.

• Example: Sync users between Laravel and Squarespace:

  public function syncUsers(SquarespaceManager $squarespace)
  {
      $laravelUsers = User::all();
      foreach ($laravelUsers as $user) {
          $squarespace->post('/users', [
              'email' => $user->email,
              'name' => $user->name,
          ]);
      }
  }
  

• Tip: Chain requests with Laravel’s Http client if the package’s abstraction is too rigid.

2. Event-Driven Workflows

Pattern: Leverage Symfony’s EventDispatcher (if available) to trigger Laravel events.

• Adapter Example:

  use Symfony\Component\EventDispatcher\EventDispatcher;
  use Illuminate\Support\Facades\Event;
  
  $eventDispatcher = new EventDispatcher();
  $eventDispatcher->addListener('squarespace.webhook.received', function ($event) {
      Event::dispatch(new SquarespaceWebhookReceived($event->getData()));
  });
  

• Use Case: Convert Squarespace webhooks into Laravel events for queue processing.

3. Command-Line Tasks

Pattern: Use Symfony’s Console component (if present) for CLI tasks.

• Example: Run a daily sync via Artisan:

  use Symfony\Component\Console\Command\Command;
  use Symfony\Component\Console\Input\InputInterface;
  use Symfony\Component\Console\Output\OutputInterface;
  
  class SyncSquarespaceCourses extends Command
  {
      protected function execute(InputInterface $input, OutputInterface $output)
      {
          $squarespace = app(SquarespaceManager::class);
          $courses = $squarespace->get('/courses');
          // Process courses...
      }
  }
  

• Register in AppServiceProvider:

  $this->app->singleton(SyncSquarespaceCourses::class);
  

4. Queue-Based Async Operations

Pattern: Offload long-running tasks (e.g., bulk data sync) to Laravel queues.

• Example:

  public function syncCourses(SquarespaceManager $squarespace)
  {
      SyncCoursesJob::dispatch($squarespace)->onQueue('squarespace');
  }
  

• Job Implementation:

  class SyncCoursesJob implements ShouldQueue
  {
      use Dispatchable, InteractsWithQueue;
  
      public function handle(SquarespaceManager $squarespace)
      {
          $courses = $squarespace->get('/courses');
          // Process and store courses...
      }
  }
  

5. Webhook Handling

Pattern: Expose a Laravel route to receive Squarespace webhooks and delegate to the package.

• Route:

  Route::post('/squarespace/webhook', [SquarespaceWebhookController::class, 'handle']);
  

• Controller:

  public function handle(Request $request, SquarespaceManager $squarespace)
  {
      $webhookData = $request->json()->all();
      $squarespace->processWebhook($webhookData); // Hypothetical method
  }
  

6. Data Transformation

Pattern: Use Laravel’s Collection or Transformer packages to map Squarespace responses to Eloquent models.

• Example:

  use Illuminate\Support\Collection;
  
  public function transformCourses(Collection $squarespaceCourses)
  {
      return $squarespaceCourses->map(function ($course) {
          return new Course([
              'title' => $course['title'],
              'slug' => $course['url'],
              'squarespace_id' => $course['id'],
          ]);
      });
  }
  

Gotchas and Tips

Pitfalls

1. Symfony Dependency Hell:

   • The package may pull in unnecessary Symfony components (e.g., HttpClient, EventDispatcher).
   • Fix: Use composer why-not symfony/* to identify conflicts and replace with Laravel equivalents.

2. Deprecated API Endpoints:

   • Squarespace’s API has evolved since 2019 (e.g., OAuth 2.0, v2 endpoints).
   • Fix: Override the package’s HTTP client to use modern endpoints:

     $squarespace->setClient(HttpClient::create(['base_uri' => 'https://api.squarespace.com/2.0']));
     

3. No Laravel Facades:

   • The package lacks facades (e.g., Squarespace::get()), forcing manual DI.
   • Fix: Create a facade in app/Facades/Squarespace.php:

     namespace App\Facades;
     
     use Illuminate\Support\Facades\Facade;
     
     class Squarespace extends Facade
     {
         protected static function getFacadeAccessor() { return 'squarespace.manager'; }
     }
     

4. Event System Mismatch:

   • Symfony’s EventDispatcher won’t integrate seamlessly with Laravel’s Events.
   • Fix: Convert Symfony events to Laravel events in the adapter layer:

     $eventDispatcher->addListener('squarespace.user.created', function ($event) {
         event(new UserCreated($event->getUser()));
     });
     

5. Missing Error Handling:

   • The package may not handle HTTP errors (e.g., 404, 500) gracefully.
   • Fix: Wrap calls in try-catch:

     try {
         $response = $squarespace->get('/nonexistent');
     } catch (\Symfony\Contracts\HttpClient\Exception\ClientException $e) {
         Log::error('Squarespace API error: ' . $e->getMessage());
     }
     

6. No Webhook Verification:

   • Squarespace webhooks require signature verification.
   • Fix: Implement manual verification in the controller:

     public function handle(Request $request)
     {
         $signature = $request->header('X-Squarespace-Signature');
         if (!hash_equals($signature, $this->generateSignature($request->getContent()))) {
             abort(403);
         }
         // Process webhook...
     }
     

Debugging Tips

1. Log API Requests/Responses: Add a middleware to log Squarespace API calls:

   $squarespace->getClient()->setOptions([
       'on_request' => function ($request) {
           Log::debug('Squarespace Request:', [
               'url' => $request->getUri(),
               'method' => $request->getMethod(),
           ]);
       },
       'on_response' => function ($response) {
           Log::debug('Squarespace Response:', [
               'status' => $response->getStatusCode(),
               'body' => $response->getContent(false),
           ]);
       },
   ]);
   

2. Test with Postman: Manually test endpoints using Postman to isolate whether issues are with the package or Squarespace’s API.

3. Symfony Debug Dump: Use Symfony’s var_dump() or dump() (if available) for debugging:

   $data = $squarespace->get('/collections');
   \Symfony\Component\VarDumper\VarDumper::dump($data);
   

Extension Points

1. **Custom HTTP