Squarespace Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer (though note the read-only warning):

   composer require beloop/squarespace-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Beloop\SquarespaceBundle\BeloopSquarespaceBundle::class => ['all' => true],
   ];
   

2. Configuration Locate the default config in config/packages/beloop_squarespace.yaml (if auto-generated) or manually define:

   beloop_squarespace:
       api_key: '%env(SQUARESPACE_API_KEY)%'
       base_url: 'https://api.squarespace.com/1.0'
   

3. First Use Case Inject the SquarespaceClient service and fetch a site’s content:

   use Beloop\SquarespaceBundle\Client\SquarespaceClient;
   
   class MyController extends AbstractController {
       public function __construct(private SquarespaceClient $client) {}
   
       public function index() {
           $siteId = 'YOUR_SITE_ID';
           $response = $this->client->get('/sites/{$siteId}/content');
           return $this->json($response);
       }
   }
   

Implementation Patterns

Core Workflows

1. API Integration

   • Use the SquarespaceClient to interact with Squarespace’s REST API. Wrap calls in a service layer for reusability:

     class SquarespaceService {
         public function __construct(private SquarespaceClient $client) {}
     
         public function fetchSiteContent(string $siteId): array {
             return $this->client->get("/sites/{$siteId}/content");
         }
     }
     

2. Event-Driven Updates

   • Poll Squarespace for changes (e.g., via a cron job) and sync with your Laravel app:

     $lastUpdated = Cache::get('squarespace_last_sync');
     $changes = $this->client->get("/sites/{$siteId}/content?updated_after={$lastUpdated}");
     // Process changes...
     Cache::put('squarespace_last_sync', time());
     

3. Model Mapping

   • Map Squarespace API responses to Eloquent models. Example:

     class SquarespaceContentMapper {
         public function map(array $apiData): Content {
             return Content::create([
                 'title' => $apiData['title'],
                 'url' => $apiData['url'],
                 'squarespace_id' => $apiData['id'],
             ]);
         }
     }
     

4. Authentication

   • Store the API key securely in .env and use dependency injection:

     # config/services.yaml
     services:
         Beloop\SquarespaceBundle\Client\SquarespaceClient:
             arguments:
                 $apiKey: '%env(SQUARESPACE_API_KEY)%'
     

Gotchas and Tips

Pitfalls

1. Read-Only Warning

   • The package is archived and read-only. Expect no updates or issue resolution. Fork or extend locally if needed.

2. Deprecated API

   • Squarespace’s API has evolved since 2019. The bundle may rely on outdated endpoints (e.g., /1.0). Verify compatibility with current docs.

3. Error Handling

   • The bundle lacks built-in retry logic for rate limits or failures. Implement middleware:

     $this->client->setHandlerStack(
         HandlerStack::create([
             new RetryMiddleware(),
             new \GuzzleHttp\HandlerStack::create(),
         ])
     );
     

4. Configuration Overrides

   • The bundle may not support Symfony Flex auto-configuration. Manually define services in config/services.yaml if needed.

Tips

1. Logging

   • Enable Guzzle logging to debug API calls:

     $this->client->setLogger(new \Monolog\Logger('squarespace'));
     

2. Testing

   • Mock the SquarespaceClient in tests:

     $mock = $this->createMock(SquarespaceClient::class);
     $mock->method('get')->willReturn(['data' => 'test']);
     $this->app->instance(SquarespaceClient::class, $mock);
     

3. Extending

   • Override the client class to add features (e.g., caching):

     class CachedSquarespaceClient extends SquarespaceClient {
         public function get($url) {
             $cacheKey = "squarespace_{$url}";
             return Cache::remember($cacheKey, 3600, fn() => parent::get($url));
         }
     }
     

4. Rate Limits

   • Squarespace enforces rate limits. Implement exponential backoff in your service layer.

5. Webhooks

   • For real-time updates, use Squarespace’s webhooks instead of polling, then route events to Laravel via a dedicated endpoint.