Tabler Bundle Laravel Package

Getting Started

• Install with composer require vendor/package once the Packagist name is confirmed. Because this is the first public release, pin the constraint deliberately (^2.0 for normal use, exact pin in production if the API is still settling).
• Look first at:
  • README.md for the supported Laravel/PHP versions and primary API.
  • composer.json for require, autoload, and extra.laravel.providers / aliases.
  • src/ for the service provider, facade, contracts, and config file.
  • config/ and database/migrations/ if present.
  • tests/ for intended usage and edge cases.
• Confirm package discovery with php artisan package:discover. If the package does not support auto-discovery, register its provider manually in bootstrap/providers.php or config/app.php.
• Publish package assets before customizing:

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

  Review the published config and replace hard-coded defaults with environment-driven values.
• First use case: create a small feature test or php artisan tinker script that resolves the package’s main service from the container and performs one representative operation. This validates installation, configuration, and Laravel compatibility before wiring it into domain code.
• Treat 2.0 as the initial public contract. There is no prior 1.x upgrade path to follow, so verify backward-compatibility expectations directly from the source and tests rather than assuming semver behavior.

Implementation Patterns

• Prefer constructor injection of the package’s contracts/services over facades and helpers. Use facades at application boundaries such as controllers, console commands, and jobs where brevity matters.
• Wrap package calls behind a thin application-level adapter or service. This keeps upgrade work localized and makes it easier to replace the package later.
• Keep package configuration in config/ and avoid editing files under vendor/. Use environment variables for deployment-specific values and confirm the config works with php artisan config:cache.
• If the package exposes events, listeners, drivers, or extension interfaces, register them in a dedicated application service provider rather than scattering bindings across the app.
• For queue-aware features, configure the queue connection, timeout, and retry behavior explicitly. Test with Queue::fake() and assert dispatched jobs or events.
• In tests:
  • Use package-provided fakes if available.
  • Otherwise bind test doubles into the container for the package’s contracts.
  • Use RefreshDatabase if the package publishes migrations.
  • Assert both the package result and the application-side side effects.
• In CI, run a small matrix across the minimum and maximum supported PHP/Laravel versions. Use composer why-not vendor/package when resolving version conflicts.
• Day-to-day upgrade workflow:
  1. Read the changelog/release notes.
  2. Run composer update vendor/package --with-dependencies.
  3. Re-publish config only when needed and diff against the existing file.
  4. Run the package’s tests plus application integration tests.
• Document team conventions around the package: preferred injection style, config keys, facade usage, and any internal wrapper.

Gotchas and Tips

• Laravel package auto-discovery can hide missing provider registration in non-standard setups. If classes are not found or bindings are missing, run php artisan package:discover and verify the provider in composer.json.
• Config caching is a common source of stale behavior. After changing package config or environment values, run php artisan config:clear locally and redeploy with php artisan config:cache in production.
• vendor:publish tags are version-specific. Use php artisan vendor:publish --list or the provider flag, and do not blindly overwrite customized config on upgrade.
• Facade aliases and helper names can conflict with application or other package classes. Check registered aliases and prefer fully qualified class names when ambiguous.
• Since 2.0 is the first release, documentation may lag behind the code. Treat source and tests as the source of truth, and pin the version until the public API proves stable.
• If the package publishes migrations, publish them before running php artisan migrate, and verify rollback and table-prefix behavior.
• Avoid resolving the package repeatedly in hot loops. If the package is expensive to construct, register it as a singleton where appropriate.
• Debug with php artisan tinker, php artisan about, composer dump-autoload -o, and application logs. For container resolution problems, inspect the provider’s register() and boot() methods.
• Review default configuration for security-sensitive values such as debug flags, credentials, HTTP client options, and logging of request/response bodies.
• Prefer documented extension points—bindings, config, events, custom drivers—over extending vendor classes directly, which makes future upgrades brittle.