Sidekick Laravel Package

Getting Started

Install the package via Composer:

composer require orchestra/sidekick

No service provider or config needed — helpers are auto-registered. Start with these core utilities:

• model_diff($model) — Compare current vs. original attributes (excludes $appends).
• model_state($model) — Returns 'new', 'existing', or 'trashed'.
• Env::get('key', 'default') — Safe, type-coerced environment access (avoiding env() cache issues).
• package_path('vendor/package', 'relative/path') — Get absolute paths within your package directory.

First use case: Detect user model changes before saving:

use function Orchestra\Sidekick\Eloquent\model_diff;

$user = User::find(1);
$user->email = 'new@example.com';
$changes = model_diff($user); // ['email' => ['old' => 'old@example.com', 'new' => 'new@example.com']]

Implementation Patterns

• Model Change Auditing: Use model_diff() in observers or middleware to reliably log attribute changes — especially useful when targeting multiple Laravel versions where getOriginal() behavior varies.
• Test Environment Handling: Use is_testbench_cli() to distinguish CLI test runs (e.g., Testbench Dusk) from web requests, and working_path() to build absolute test paths:

  $configPath = working_path('tests/stubs/config/app.php');
  

• Environment Safety in Config: Replace env('KEY') in config files with Env::bool(), Env::int(), or Env::string() to avoid null after config:cache.
• Package Version Logic: Conditionally enable features using package_version_compare('vendor/package', '^11.0') for robust cross-version support.
• PSR-4 Filename Generation: Use filename_from_classname(Some\Namespace\ClassName::class) to derive class_name.php for stub generation or code analysis tools.
• Deferred Setup Hooks: Attach post-resolution logic with after_resolving($app, SomeClass::class, fn($instance) => $instance->boot()) — ideal for testing fixtures or optimizing hot-path initialization.

Gotchas and Tips

• Appends Exclusion: model_diff() and model_state() deliberately exclude $appends and accessors. This avoids misleading diffs from dynamic attributes — don’t use them to track accessor-modified values.
• @internal Classes: Watcher, Concerns\HasPreviousAttributes (in older Laravel), and related traits may change without warning. Avoid direct dependency.
• Laravel Version Gaps: Traits like HasPreviousAttributes polyfill newer functionality (e.g., Model::getPrevious()), but edge cases (e.g., cascading deletes, touch relations) may differ. Always validate against your exact target Laravel version.
• is_testbench_cli() Scope: Only detects CLI contexts used by Orchestra/Testbench — it won’t identify Artisan, Pest, or PHPUnit CLI runs outside Testbench environments.
• Path Functions: join_paths() and is_symlink() live in Orchestra\Sidekick\Filesystem\*, not root namespace — ensure correct use statements in PHP 8+.
• Performance Note: model_diff() computes diffs by comparing getAttributes() and getOriginal(). For large models or high-frequency use (e.g., batch updates), consider caching or manual field checks.