Common Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require axstrad/common
   

   Publish the config (if applicable) with:

   php artisan vendor:publish --provider="Axstrad\Common\CommonServiceProvider"
   

2. First Use Case The package provides utility classes for common Laravel workflows. Start with the Axstrad\Common\Helpers\ArrayHelper for array manipulations:

   use Axstrad\Common\Helpers\ArrayHelper;
   
   $array = ['a' => 1, 'b' => 2, 'c' => 3];
   $flattened = ArrayHelper::flatten($array); // Returns [1, 2, 3]
   

3. Where to Look First

   • Documentation: Check the src/ directory for class-level PHPDoc comments.
   • Tests: Browse tests/ for usage examples and edge cases.
   • Service Provider: Review CommonServiceProvider.php for package registration and bindings.

Implementation Patterns

Core Workflows

1. Array Manipulation Use ArrayHelper for nested array operations (e.g., pluck, flatten, dotNotation):

   $data = ['user' => ['name' => 'John', 'age' => 30]];
   $name = ArrayHelper::get($data, 'user.name'); // "John"
   

2. String Utilities Leverage StringHelper for common string operations:

   use Axstrad\Common\Helpers\StringHelper;
   
   $slug = StringHelper::slugify('Hello World'); // "hello-world"
   

3. Collection Extensions Extend Laravel Collections with CollectionHelper:

   use Axstrad\Common\Helpers\CollectionHelper;
   
   $collection = collect([1, 2, 3]);
   $sum = $collection->sumWithDefault(0); // 6
   

4. API Response Handling Use ApiResponse for consistent API responses:

   use Axstrad\Common\Responses\ApiResponse;
   
   return ApiResponse::success(['data' => $data]);
   

5. Event Dispatching Integrate with Laravel events via EventHelper:

   use Axstrad\Common\Helpers\EventHelper;
   
   EventHelper::dispatch('user.created', $user);
   

Integration Tips

• Service Container Bindings: Register custom bindings in CommonServiceProvider for reusable logic.
• Middleware: Use Axstrad\Common\Http\Middleware\* for cross-cutting concerns (e.g., logging, validation).
• Artisan Commands: Extend Axstrad\Common\Console\Command for CLI tools.

Gotchas and Tips

Pitfalls

1. Namespace Collisions The package uses Axstrad\Common namespace. Ensure your project doesn’t shadow this (e.g., avoid App\Common). Fix: Alias classes in imports or use fully qualified names.

2. Undocumented Methods Some helper methods lack PHPDoc. Verify behavior via tests or source code:

   // Example: Check if `ArrayHelper::mergeRecursive` handles null values as expected.
   

3. Configuration Overrides If publishing config, ensure keys match your .env (e.g., AXSTRAD_COMMON_*).

4. Collection Macros Be cautious with CollectionHelper macros—they may conflict with existing Laravel macros. Tip: Use Collection::macro() to check registered macros before extending.

Debugging

• Log Helpers: Use LogHelper for structured logging:

  use Axstrad\Common\Helpers\LogHelper;
  
  LogHelper::debug('Key', $value, ['context' => 'array']);
  

• Dump Utilities: DumpHelper::dump() includes Laravel’s dd() but with additional formatting.

Extension Points

1. Custom Helpers Extend Axstrad\Common\BaseHelper to add project-specific utilities:

   namespace App\Helpers;
   
   use Axstrad\Common\BaseHelper;
   
   class AppHelper extends BaseHelper {
       public static function customMethod() { ... }
   }
   

2. Service Provider Extensions Override the provider in your AppServiceProvider:

   public function register()
   {
       $this->app->extend('axstrad.common', function ($service) {
           return new CustomCommonService($service);
       });
   }
   

3. Testing Mock helpers in tests using Laravel’s partialMock:

   $mock = $this->partialMock(ArrayHelper::class, ['flatten']);
   $mock->shouldReceive('flatten')->andReturn([1, 2, 3]);
   

Config Quirks

• Default Values: Some helpers use config('axstrad-common.defaults'). Override in config/axstrad-common.php:

  'defaults' => [
      'locale' => 'en_US',
      'timezone' => 'UTC',
  ],