README

A Symfony bundle for integrating with the SimpleCirc subscription management service.

Warning: This bundle is not yet fully-featured. May not support all possible fields for publications, subscribers, and subscriptions, nor all possible API functions.

Features

API Client: Complete interface to the SimpleCirc REST API
Webhook Support: Secure webhook verification and parsing
Event Consumer: Automatic handling of subscription lifecycle events
Entity Abstractions: Base classes and interfaces for subscribers, subscriptions, and publications
Flexible Architecture: Use as much or as little as you need

Requirements

PHP 8.2 or higher
Symfony 6.4 or 7.x
Doctrine ORM 2.x or 3.x

Installation

composer require jakepenguins/simplecirc-bundle

Configuration

# config/packages/simplecirc.yaml
simplecirc:
    api:
        api_key: '%env(SIMPLECIRC_API_KEY)%'
        base_url: 'https://simplecirc.com/api/v1.2/'  # optional, this is the default
    
    # Optional: Configure entity classes if using the webhook consumer
    entities:
        subscriber_class: 'App\Entity\User'
        subscription_class: 'App\Entity\Subscription'
        publication_class: 'App\Entity\Publication'
    
    # Optional: Configure webhook endpoints
    webhooks:
        endpoints:
            - name: 'my-endpoint'
              secret: '%env(WEBHOOK_SECRET)%'

Usage

API Client

use SimplecircBundle\Service\SimplecircApiClient;

class MyController 
{
    public function __construct(
        private SimplecircApiClient $simplecirc
    ) {}
    
    public function getSubscriber(string $accountId): array
    {
        return $this->simplecirc->getSubscriber($accountId);
    }
    
    public function updateSubscriber(string $accountId, array $data): array
    {
        return $this->simplecirc->updateSubscriber($accountId, $data);
    }
}

Webhooks

Configure webhook routing in config/packages/webhook.yaml:

framework:
    webhook:
        routing:
            simplecirc/my-endpoint:
                service: SimplecircBundle\Webhook\SimplecircRequestParser
                secret: '%env(WEBHOOK_SECRET)%'

Implement the required interfaces in your entities:

use SimplecircBundle\Entity\SimplecircSubscriberInterface;
use SimplecircBundle\Entity\AbstractSimplecircSubscriber;

class User extends AbstractSimplecircSubscriber implements UserInterface
{
    // Your user entity implementation
}

Create a consumer to handle webhook events:

use SimplecircBundle\Consumer\SimplecircWebhookConsumer;
use Symfony\Component\RemoteEvent\Attribute\AsRemoteEventConsumer;

#[AsRemoteEventConsumer('simplecirc/my-endpoint')]
class MyWebhookConsumer extends SimplecircWebhookConsumer
{
    protected string $endpointName = 'my-endpoint';
}

Implement the required services:
- SimplecircBundle\Repository\SubscriberRepositoryInterface
- SimplecircBundle\Repository\SubscriptionRepositoryInterface
- SimplecircBundle\Publication\PublicationResolverInterface
- SimplecircBundle\Factory\EntityFactoryInterface
Wire them up in config/services.yaml:

services:
    SimplecircBundle\Repository\SubscriberRepositoryInterface:
        alias: App\Repository\UserRepository
    
    SimplecircBundle\Repository\SubscriptionRepositoryInterface:
        alias: App\Repository\SubscriptionRepository
    
    SimplecircBundle\Publication\PublicationResolverInterface:
        alias: App\Service\PublicationResolver
    
    SimplecircBundle\Factory\EntityFactoryInterface:
        alias: App\Factory\EntityFactory

Architecture

Interfaces

The bundle provides interfaces for maximum flexibility:

SimplecircSubscriberInterface - For your user/subscriber entity
SimplecircSubscriptionInterface - For your subscription entity
SimplecircPublicationInterface - For your publication entity
SubscriberRepositoryInterface - For subscriber lookups
SubscriptionRepositoryInterface - For subscription lookups
PublicationResolverInterface - For publication validation
EntityFactoryInterface - For creating new entities

Abstract Classes

Optionally extend these to get ORM mappings for free:

AbstractSimplecircSubscriber - Mapped superclass with Simplecirc fields
AbstractSimplecircSubscription - Mapped superclass with subscription fields

Event Types

The bundle handles these SimpleCirc webhook events:

subscription_purchased.new - New subscription created
subscription_purchased.renewal - Subscription renewed
subscription_updated - Subscription details changed
subscriber_updated - Subscriber details changed
subscription_deleted - Subscription deleted
subscriber_deleted - Subscriber deleted

Events not yet supported:

merchandise_purchased - Merchandise purchased

Testing

This bundle includes comprehensive unit tests and provides helpers for writing integration tests in your application.

Running Bundle Tests

# Run all unit tests
vendor/bin/phpunit vendor/crownandcovenant/simplecirc-bundle/tests

# Specific test suites
vendor/bin/phpunit vendor/crownandcovenant/simplecirc-bundle/tests/Service
vendor/bin/phpunit vendor/crownandcovenant/simplecirc-bundle/tests/Consumer

Writing Your Own Tests

The bundle provides:

AbstractWebhookConsumerTest - Base class for integration tests
WebhookConsumerTestTrait - Reusable assertions and helpers
Test fixtures - Sample webhook payloads

See TESTING.md for comprehensive testing guide including:

Unit vs integration testing strategies
Using test helpers and assertions
Code examples and best practices
CI/CD integration

License

This bundle is released under the MIT License. See LICENSE for details.

"SimpleCirc" and all related trademarks are copyright (c) SimpleCirc LLC.

jakepenguins / simplecirc-bundle

Maintainers

Details