Laravel Billing Laravel Package

Getting Started

• Install with composer require <vendor>/<package> (check the release's composer.json constraints), then publish assets/config/migrations:

  php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
  php artisan migrate
  

• Look first at:
  • config/<package>.php — table names, model bindings, feature flags.
  • database/migrations/*_create_plans_table.php — schema, including the new icon column in v1.1.2.
  • src/Models/Plan.php — fillable/casts and any accessors.
  • The package service provider — bindings you can override.
• First use case: create a plan with an icon and render it on a pricing/billing page:

  Plan::create([
      'name' => 'Pro',
      'price' => 2900,
      'icon' => 'heroicon-o-rocket-launch', // or an image URL, depending on your convention
  ]);
  

  Then expose it through your API resource or Blade view.

v1.1.2 note: icon is a new nullable column on plans. Existing installs must publish and run the new migration (or add the column manually if migrations are already tracked).

Implementation Patterns

• Seeding plans with icons: keep icons in seeders or a config map so marketing copy and billing UI stay in sync.

  Plan::updateOrCreate(
      ['slug' => 'pro'],
      ['name' => 'Pro', 'price' => 2900, 'icon' => 'rocket']
  );
  

• Rendering in Blade: wrap icon output in a small component so you can swap icon libraries later.

  <x-plan-icon :icon="$plan->icon" :fallback="'heroicon-o-sparkles'" />
  

• API resources: include icon explicitly so UI clients can render plan cards without extra lookups.

  return [
      'id' => $this->id,
      'name' => $this->name,
      'price' => $this->price,
      'icon' => $this->icon,
  ];
  

• Admin forms: add icon to validation rules and form requests. Prefer a constrained format (icon name, enum, or URL) rather than free-form HTML/SVG.
• Factories and tests: update the plan factory with a sensible default icon and assert it survives serialization.
• Fallbacks: treat icon as nullable; render a default icon when it is missing so older plans created before v1.1.2 still look correct.

Gotchas and Tips

• Existing databases: the new column arrives via migration. If you have already published migrations, run php artisan vendor:publish again with the migration tag or copy the additive migration manually. Check with php artisan migrate:status.
• Mass assignment: confirm icon is in the package model's $fillable, or add it in your own subclass. If the package uses guarded attributes, Plan::create(['icon' => ...]) may silently drop it.
• Icon format drift: decide early whether icon stores a Heroicon name, a CSS class, a file path, or a URL. Mixing conventions leads to broken rendering and unsafe raw SVG output.
• Caching: if you cache plan payloads, API responses, or pricing pages, the new field will not appear until caches are cleared. Add icon to any cached serialization whitelist.
• API contracts: adding a field is usually non-breaking, but strict clients using schema validation may need their expected response shape updated.
• Debugging: verify the column exists (Schema::hasColumn('plans', 'icon')), inspect a model instance (Plan::first()->icon), and check whether your resource/view actually references the attribute.
• Extension points: publish and override the Plan model, API resources, or Blade views if you need custom icon rendering; avoid editing vendor files directly.