Commons Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require develia/commons
   

   Add to composer.json under require-dev if only needed for development:

   "require-dev": {
       "develia/commons": "^1.0"
   }
   

2. First Use Case: Logging & Debugging Import the Logger helper in your controller or service:

   use Develia\Commons\Logger;
   
   public function index()
   {
       Logger::info('User accessed the dashboard', ['user_id' => auth()->id()]);
   }
   

   • Where to look first: Check src/Logger.php for available log levels (debug, info, warning, error, critical).
   • Default config: Logs to storage/logs/develia.log (configurable via config/develia.php).

Implementation Patterns

1. Helper Utilities in Controllers/Services

• String Manipulation Use Develia\Commons\StringHelper for common operations:

  use Develia\Commons\StringHelper;
  
  $slug = StringHelper::slugify('Laravel 10 Best Practices');
  // Output: "laravel-10-best-practices"
  

  • Pattern: Centralize string transformations (e.g., slugs, truncation) in a base service.

• Array/Collection Helpers

  use Develia\Commons\ArrayHelper;
  
  $filtered = ArrayHelper::filterByKey($array, ['active', 'published']);
  

2. Middleware Integration

• Request Validation Extend Develia\Commons\Http\RequestValidator to enforce custom rules:

  use Develia\Commons\Http\RequestValidator;
  
  class ApiValidator extends RequestValidator
  {
      protected $rules = [
          'api_token' => 'required|api_token_valid',
      ];
  }
  

  • Workflow: Attach to routes:

    Route::middleware([ApiValidator::class])->group(function () {
        // Protected routes
    });
    

• Response Wrapping Use Develia\Commons\Http\ResponseWrapper to standardize API responses:

  return ResponseWrapper::success($data, 'Data fetched successfully');
  

3. Database & Eloquent Extensions

• Query Scoping Add reusable scopes to models:

  use Develia\Commons\Database\Eloquent\Scopes\ActiveScope;
  
  class Post extends Model
  {
      public function scopeActive($query)
      {
          return $query->apply(new ActiveScope());
      }
  }
  

  • Usage:

    Post::active()->get();
    

• Soft Deletes with Custom Logic Override Develia\Commons\Database\Eloquent\SoftDeletes:

  class User extends Model
  {
      use SoftDeletes, DeletesWithLog;
  
      protected $logMessage = 'User deleted by {user}';
  }
  

4. Event Handling

• Custom Event Listeners Extend Develia\Commons\Events\BaseEvent:

  class UserRegistered extends BaseEvent
  {
      public $user;
      public $plan;
  
      public function __construct($user, $plan)
      {
          $this->user = $user;
          $this->plan = $plan;
      }
  }
  

  • Dispatch:

    event(new UserRegistered($user, 'premium'));
    

  • Listen:

    Event::listen(UserRegistered::class, function ($event) {
        Logger::info('New user registered', ['plan' => $event->plan]);
    });
    

5. Testing Utilities

• Mocking Helpers Use Develia\Commons\Testing\MockHelper in PHPUnit:

  $mock = MockHelper::mock(User::class, [
      'name' => 'Test User',
      'email' => '[email protected]',
  ]);
  

Gotchas and Tips

Pitfalls

1. Logger Configuration Overrides

   • If config/develia.php is missing, logs default to storage/logs/develia.log. Tip: Publish config first:

     php artisan vendor:publish --provider="Develia\Commons\CommonsServiceProvider" --tag="config"
     

   • Debugging: Check if LOG_CHANNEL in .env conflicts with the package’s logger.

2. Middleware Priority

   • RequestValidator must be placed before auth middleware to validate tokens early.
   • Fix: Order middleware in app/Http/Kernel.php:

     'api' => [
         \App\Http\Middleware\CheckForApiToken::class,
         \Develia\Commons\Http\RequestValidator::class,
         // ...
     ],
     

3. Soft Deletes Race Conditions

   • DeletesWithLog uses a queue job. Ensure queue:work is running or set sync in config:

     'deletes' => [
         'queue' => env('QUEUE_CONNECTION', 'sync'),
     ],
     

4. StringHelper Edge Cases

   • slugify() removes all non-alphanumeric characters by default. Use slugify($str, '-', true) to preserve hyphens/spaces.

Debugging Tips

• Enable Debug Mode Set APP_DEBUG=true in .env to log stack traces for Logger errors.
• Clear Published Config If changes to config/develia.php don’t apply, clear config cache:

  php artisan config:clear
  

• Check for Method Conflicts If extending SoftDeletes, ensure your model doesn’t already define bootSoftDeletes().

Extension Points

1. Custom Log Handlers Extend Develia\Commons\Logger\Handler\BaseHandler to add Slack/Email alerts:

   class SlackHandler extends BaseHandler
   {
       public function log($level, $message, array $context)
       {
           // Send to Slack API
       }
   }
   

   Register in config/develia.php:

   'handlers' => [
       \Develia\Commons\Logger\Handler\SlackHandler::class,
   ],
   

2. Dynamic Request Rules Override Develia\Commons\Http\RequestValidator::rules() to fetch rules from a database:

   public function rules()
   {
       return Cache::remember('api_rules', 60, function () {
           return ApiRule::all()->pluck('rule');
       });
   }
   

3. Event Payload Serialization For complex events, implement JsonSerializable in your event class:

   class OrderProcessed extends BaseEvent implements JsonSerializable
   {
       public function jsonSerialize()
       {
           return [
               'order_id' => $this->order->id,
               'total' => $this->order->total,
           ];
       }
   }
   

Performance Considerations

• Avoid Eager Loading in Scopes Scopes like ActiveScope should not eager-load relationships unless necessary:

  // Bad: Loads all relations for every active record
  Post::active()->with(['author', 'comments'])->get();
  
  // Good: Load only what you need
  Post::active()->get()->load(['author']);
  

• Logger Batch Writing For high-volume logging, batch writes by implementing Develia\Commons\Logger\BatchableInterface.