spackleso/spackle-php

Spackle is the easiest way to integrate your PHP app with Stripe Billing. See https://www.spackle.so for details.

0.0.8 2024-03-21 15:16 UTC

Requires

• stripe/stripe-php: ^10.12

Requires (Dev)

• phpunit/phpunit: ^10.0

MIT

• Hunter Clarke

README

The Spackle PHP library provides optimized access to billing aware flags created on the Spackle platform.

Documentation

See the PHP API docs.

Setup

Install the Spackle library

composer require spackleso/spackle-php

To use the bindings use Composer's autoload:

require_once('vendor/autoload.php');

Configure your environment

In order to use Spackle, you need to configure your secret key on the Spackle singleton. You can find your secret key in Spackle app settings page.

\Spackle\Spackle::setApiKey('<api key>');

Usage

Pricing tables

Fetch a pricing table

\Spackle\PricingTable::retrieve("abcde123");

Pricing table object

{
  id: string
  name: string
  intervals: string[]
  products: {
    id: string
    name: string
    description: string
    features: {
      id: string
      name: string
      key: string
      type: number
      value_flag: boolean
      value_limit: number | null
    }[]
    prices: {
      month?: {
        id: string
        unit_amount: number
        currency: string
      }
      year?: {
        id: string
        unit_amount: number
        currency: string
      }
    }
  }[]
}

Entitlements

Fetch a customer

Spackle uses stripe ids as references to customer features.

$customer = \Spackle\Customer::retrieve("cus_000000000");

Verify feature access

$customer->enabled("feature_key");

Fetch a feature limit

$customer->limit("feature_key");

Examine a customer's subscriptions

A customer's current subscriptions are available on the subscriptions method. These are valid \Stripe\Subscription objects as defined in the Stripe PHP library.

$customer->subscriptions();

Waiters

There is a brief delay between when an action takes place in Stripe and when it is reflected in Spackle. To account for this, Spackle provides a Waiters class with static methods that can be used to wait for a Stripe object to be updated and replicated.

1. Wait for a customer to be created

   \Spackle\Waiters::waitForCustomer("cus_00000000");

2. Wait for a subscription to be created

   \Spackle\Waiters::waitForSubscription("cus_000000000", "sub_00000000");

3. Wait for a subscription to be updated

   \Spackle\Waiters::waitForSubscription("cus_000000000", "sub_00000000", array("status" => "active"));

These will block until Spackle is updated with the latest information from Stripe or until a timeout occurs.

Usage in development environments

In production, Spackle requires a valid Stripe customer. However, that is not development environments where state needs to be controlled. As an alternative, you can use a file store to test your application with seed data.

/app/spackle.json

{
  "cus_000000000": {
    "features": [
      {
        "type": 0,
        "key": "flag_feature",
        "value_flag": true
      },
      {
        "type": 1,
        "key": "limit_feature",
        "value_limit": 100
      }
    ],
    "subscriptions": [
      {
        "id": "sub_000000000",
        "status": "trialing",
        "quantity": 1
      }
    ]
  }
}

Then configure the file store in your application:

\Spackle\Spackle::setStore(new \Spackle\Stores\FileStore("/app/spackle.json"));

Usage in testing environments

In production, Spackle requires a valid Stripe customer. However, that is not ideal in testing or some development environments. As an alternative, you can use an in-memory store to test your application with seed data.

\Spackle\Spackle::setStore(new \Spackle\Stores\MemoryStore());
\Spackle\Spackle::getStore()->set_customer_data("cus_000000000", array(
  "features" => array(
    array(
      "type" => 0,
      "key" => "flag_feature",
      "value_flag" => true
    ),
    array(
      "type" => 1,
      "key" => "limit_feature",
      "value_limit" => 100
    )
  ),
  "subscriptions" => array(
    array(
      "id" => "sub_000000000",
      "status" => "trialing",
      "quantity" => 1
    )
  )
);

Note: The in-memory store is not thread-safe and state will reset on each application restart.