Getting Started

Laravel Spark is a commercial, closed-source SaaS starter kit for subscription billing, teams, invoices, and billing settings. It is not a conventional open-source Composer package: the GitHub repository is primarily informational, and installation requires a purchased license and private Composer credentials. The last release date shown is 2018, so treat Spark as a legacy system and verify PHP/Laravel compatibility before committing to it.

Minimal setup path:

Confirm the Spark version supports your Laravel/PHP version. Older Spark releases target older Laravel, Vue, and Stripe APIs; many are incompatible with modern PHP/Laravel.
Add the Spark Composer repository and authentication credentials to composer.json / auth.json, then require the matching laravel/spark version.
Run the installer:

composer require laravel/spark
php artisan spark:install

Configure Stripe or Braintree keys in .env, run migrations, and register at /register.
Define plans and optional team billing in app/Providers/SparkServiceProvider.php.
Create matching plans/prices in Stripe or Braintree, then test registration, subscription, plan swap, cancellation, and invoice download.

Look first at:

config/spark.php for currency, billable model, and package configuration.
app/Providers/SparkServiceProvider.php for plans, trials, teams, and add-ons.
Published Spark views/assets under resources/views/vendor/spark and the frontend asset pipeline.
The routes Spark registers; use php artisan route:list to see the actual endpoints rather than assuming them.

First practical use case: gate a paid feature behind a subscription. Register a user, subscribe them to a defined plan, then check subscription state in controllers, middleware, policies, or Blade views.

Implementation Patterns

Define plans centrally. Plans usually live in SparkServiceProvider and must use the exact plan/price identifiers from your billing provider:

Spark::useStripe()->noCardUpFront()->trialDays(14);

Spark::freePlan()
    ->name('Free')
    ->features(['Basic access']);

Spark::plan('Pro Monthly', 'price_xxx')
    ->price(29)
    ->features(['Pro access', 'Priority support']);

Spark::plan('Pro Yearly', 'price_yyy')
    ->price(290)
    ->yearly()
    ->features(['Pro access', 'Priority support']);

After changing this provider, clear cached configuration and routes:

php artisan config:clear
php artisan route:clear

Use the Billable trait for subscription checks. Spark’s billable model exposes common subscription operations. The exact method surface depends on the Spark version, but day-to-day checks typically look like:

if ($user->subscribed('default')) {
    // active subscription
}

if ($user->onPlan('price_xxx')) {
    // specific plan
}

if ($user->onTrial()) {
    // trial period
}

Common billing operations:

$user->subscription('default')->swap('price_yyy');
$user->subscription('default')->cancel();
$user->subscription('default')->resume();

$invoices = $user->invoices();
return $user->downloadInvoice($invoiceId);

Wrap these calls in your own service or policy layer so future migration away from Spark is easier.

Model team billing deliberately. If teams are enabled, the billable entity is usually the team, not the individual user. Add team configuration in the provider, then check subscription state against the current team:

Spark::team()->name('Team')->trialDays(14);

$team = $user->currentTeam;

if ($team->subscribed('default')) {
    // team has active billing
}

Be consistent: decide early whether users, teams, or both can own subscriptions. Mixing $user->subscribed() and $team->subscribed() without a clear rule is a common source of authorization bugs.

Gate features with explicit entitlement logic. Spark plans can declare feature labels for display, but production authorization should be explicit. Use subscription/plan checks, policies, middleware, or your own entitlement table. Avoid scattering raw plan ID checks throughout views; centralize them:

class CanUseProFeature
{
    public function handle($request, Closure $next)
    {
        abort_unless(
            $request->user()->currentTeam->onPlan('price_xxx'),
            403
        );

        return $next($request);
    }
}

Customize by publishing, not editing vendor files. Publish Spark views, assets, language files, and configuration, then override in application-level code. Keep custom Vue components and views outside the vendor path. If you need behavior changes, prefer events/listeners, route overrides, or calling Spark model methods from your own controllers rather than modifying package internals.

Handle billing webhooks outside the request path. Spark expects your billing provider’s webhook endpoint to keep local subscription state in sync. Register the correct endpoint in Stripe/Braintree, use the provider’s CLI or tunneling tool locally, and verify webhook logs when state looks stale. For side effects such as welcome emails, provisioning, or analytics, listen to Spark subscription events or your provider’s webhooks and dispatch queued jobs.

Use billing tests as regression tests. At minimum, test:

Registration with and without a trial.
Subscription creation with a valid plan ID.
Plan swap and cancellation.
Team ownership and team billing authorization.
Invoice listing/download authorization.
Webhook-driven state changes in a test or staging environment.

Gotchas and Tips

This is legacy software. A 2018 last release means no modern Laravel/PHP support, no recent Stripe API support, and no security maintenance. Spark predates Strong Customer Authentication and PaymentIntents; card payments in regions requiring SCA may fail. Do not choose Spark for a new SaaS. For new projects, use Laravel Cashier with Jetstream/Breeze/Fortify or a custom billing layer.
Installation is license-gated. You cannot simply composer require laravel/spark from public Packagist. Composer authentication must be configured, and package availability depends on the vendor continuing to serve the repository. Mirror or archive the package internally if you must maintain a legacy installation.
Version compatibility is the first blocker. Check the Spark release’s composer.json constraints against your Laravel and PHP versions before estimating work. Upgrading Laravel often requires abandoning or heavily patching Spark.
Plan IDs must match exactly. Monthly/yearly IDs, test/live mode keys, and provider-side archived plans are frequent causes of “plan not found” or subscription failures. Keep plan IDs in config or environment-specific mappings, not hard-coded in many places.
Test mode and live mode drift. A Spark installation configured with test keys will not see live plans, customers, or webhooks. Verify STRIPE_KEY, STRIPE_SECRET, webhook secrets, and APP_URL together.
Teams change the billing subject. If team billing is enabled, checking $user->subscribed() can produce misleading results. Resolve the billable entity first, then check subscription state on that entity. Enforce team membership before allowing billing changes.
Vendor route and middleware collisions. Spark registers its own routes and middleware. If your application also defines /settings, /billing, or similar paths, inspect php artisan route:list and resolve conflicts explicitly. Route caching can hide stale route assumptions; clear caches after provider changes.
Vendor publishing can overwrite customizations. Track published views/assets in version control and avoid re-publishing blindly during upgrades. Prefer extending published files from app-level components where possible.
Do not edit vendor migrations. Add new migrations for schema changes. Spark’s migrations may conflict with newer Laravel schema conventions or with your own users/teams tables.
Trials and card-up-front behavior are easy to misread. noCardUpFront() permits registration without a payment method, but you still need a clear flow for converting trials to paid subscriptions. Test what happens when a trial ends without a card and how your UI communicates that state.
Invoices and tax are not automatic. Spark provides invoice access, but tax/VAT handling, currency rules, and invoice branding depend on provider configuration and your own implementation. Validate invoice authorization; never expose another user’s or team’s invoice by ID.
Debug with provider logs first. When subscription state is wrong, compare your database records, storage/logs/laravel.log, and the Stripe/Braintree dashboard webhook/event logs. Most “Spark is broken” issues are webhook, key-mode, or plan-ID mismatches.
Extension points are limited by the closed source model. You can define plans, publish views/assets, use the billable model methods, and react to events, but deep framework-level changes require working around package internals. Keep an exit plan: isolate billing checks behind application services so migrating to Cashier is a bounded refactor rather than a rewrite.

Spark Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips