Flysystem Upyun Laravel Package

Getting Started

• Install with composer require vendor/package. On Laravel 5.5+ this release supports package auto-discovery, so you typically do not need to manually add the service provider or facade alias.
• First place to look is the package README and its service provider. Identify:
  • the config file name and publish tag,
  • whether a facade is registered,
  • which environment variables are required.
• Publish configuration early:

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

  If the package documents a tag instead, use --tag=package-config.
• Add required credentials to .env, keeping actual defaults in config/package.php. Never read env() directly outside config files.
• First use case: resolve the package from the container in a controller or artisan command and perform a single read-only call. For example:

  use Vendor\Package\Package;
  
  public function show(Package $package)
  {
      return $package->healthCheck();
  }
  

• For older Laravel versions, or if auto-discovery is disabled, manually register the provider in config/app.php and add any facade alias.

Implementation Patterns

• Prefer constructor injection over facades. It keeps dependencies explicit and makes unit testing simpler. Use the facade only in views or quick scripts.
• Keep package usage behind a small application service. Wrap calls in an action or service class so vendor API changes only affect one place:

  class SyncCustomer
  {
      public function __construct(private Package $package) {}
  
      public function handle(Customer $customer): void
      {
          $this->package->sync($customer->toArray());
      }
  }
  

• Use the published config as the source of truth. Set environment-specific values in .env, but expose them through config/package.php. This keeps config:cache working correctly.
• Bind interfaces in a service provider when testing. If the package exposes a contract, bind a fake implementation in tests:

  $this->app->instance(PackageContract::class, new FakePackage());
  

• Use jobs for non-trivial calls. If package operations make HTTP requests, write files, or touch external systems, dispatch a queued job rather than blocking the request.
• Auto-discovery is the default path on Laravel 5.5+. Leave the provider out of config/app.php unless you are supporting older Laravel versions. Keep the manual registration documented for legacy deployments.
• Configuration caching is part of deployment. Run php artisan config:cache after changing published config. Re-run it whenever .env or package config changes.
• Test with Laravel’s container. Resolve the package from the container in feature tests to verify the auto-discovered provider is actually loaded:

  $this->assertInstanceOf(Package::class, app(Package::class));
  

Gotchas and Tips

• Duplicate provider registration. After upgrading to a version with auto-discovery, remove any manual provider entry in config/app.php. Registering both can cause duplicate bindings, duplicate event listeners, or confusing config merges.
• Cached discovery files. If auto-discovery does not seem to work, clear cached bootstrap files:

  php artisan package:discover
  php artisan config:clear
  php artisan clear-compiled
  composer dump-autoload
  

• Config cache hides .env changes. A changed PACKAGE_API_KEY will not take effect until php artisan config:cache is re-run. This is a common “why is it still using the old value?” issue.
• Facade aliases are not guaranteed. Auto-discovery registers the provider; the facade alias is only available if the package declares it in extra.laravel.aliases. Check the package’s composer.json before relying on Package::.
• Check version constraints before deploying. The auto-discovery improvement applies to Laravel 5.5+, but the package may still support older versions. Confirm the package’s composer.json constraints against your application’s Laravel version.
• Debug resolution with tinker. Use php artisan tinker and inspect app(Package::class) or config('package') to confirm binding and configuration.
• Extension points usually live in the published config and service provider. Prefer binding your own implementation or decorating the package service over editing vendor files. Re-publishing config after upgrades can overwrite local changes, so keep customizations in application code or a separate config file.
• Watch for silent fallbacks. Many Laravel packages return null or a default value when credentials are missing. Add a startup health check or an early assertion in your own service so misconfiguration fails loudly.