Statamic Private Media Laravel Package

Getting Started

This is a Statamic addon (v0.1.1) that registers a delivery route, a prune command, and publishable assets through Statamic’s AddonServiceProvider. Start here:

1. Install the package:

   composer require vendor/package
   

   Statamic addons are usually auto-discovered; if not, add the provider to config/app.php.

2. Publish config/assets if the addon exposes publishables:

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

   In v0.1.1 publishables are registered once through bootPublishables(), so you should not see duplicate publish groups.

3. Inspect the addon service provider first. It should extend Statamic’s AddonServiceProvider and put custom logic in bootAddon(), not in boot().

4. First real use case: configure the delivery route and schedule the prune command. Check the addon config file for route prefix/middleware and command cadence, then verify:

   php artisan route:list
   php artisan list | grep prune
   

   You should see one delivery route and one prune command registration.

Implementation Patterns

• Let the base provider boot Statamic concerns. AddonServiceProvider::boot() already calls bootRoutes(), bootCommands(), and bootPublishables() before bootAddon(). Put only addon-specific setup in bootAddon():

  protected function bootAddon(): void
  {
      // custom bindings, view composers, etc.
  }
  

• Register routes through the addon’s route file, not by calling Route::get() again inside bootAddon(). The delivery route should come from the provider’s route registration. If you need to customize it, prefer config-driven prefix/middleware over re-registering it.

• Use the provided prune command as a scheduled task. In app/Console/Kernel.php or the Statamic scheduler config:

  $schedule->command('package:prune')->daily();
  

  Avoid registering the command manually if the addon already auto-loads it.

• Treat publishables as config-driven. Publish once, then edit the published config. Do not add the same publish group manually in your app provider; v0.1.1 fixed duplicate publishable registration.

• Integration tip: if you need conditional route registration, do it inside the addon’s route file using config values. This keeps the route count stable and avoids duplicate route names.

• When overriding boot() yourself, always call parent::boot() and keep Statamic’s boot sequence intact:

  public function boot(): void
  {
      parent::boot();
  
      // only logic that truly cannot live in bootAddon()
  }
  

Gotchas and Tips

• Do not override bootRoutes(), bootCommands(), or bootPublishables() unless you fully replace the base behavior. v0.1.1 exists because those methods were being called twice: once by AddonServiceProvider::boot() and once by the addon. The symptoms are duplicate routes, duplicate command listings, and duplicate publishables.

• Debug duplicate registration with Artisan. After upgrading, run:

  php artisan route:list
  php artisan list
  php artisan vendor:publish --list
  

  If you still see the delivery route or prune command twice, clear caches:

  php artisan route:clear
  php artisan config:clear
  php artisan cache:clear
  composer dump-autoload
  

• Route name collisions are the most common failure mode. Duplicate delivery routes may not fail immediately, but route:cache can fail or the wrong route may be matched. Keep the addon’s route name stable and do not re-register it in app code.

• Command duplication is easy to miss in local development. A duplicated prune command may still run, but scheduled tasks can execute twice. Check php artisan schedule:list if available in your Laravel version.

• Publishable duplication shows up as repeated asset groups. If vendor:publish lists the same tag twice, you are likely on a version before v0.1.1 or you have manually re-registered the publishable.

• This is a v0.1.x package. Expect API and config changes. Pin the version in composer.json if you depend on exact boot behavior, and review release notes before upgrading.

• Extension point: use bootAddon() for custom behavior, config for route/command customization, and the addon’s published assets for overrides. Avoid monkey-patching the service provider’s boot sequence.