Common Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require comsave/common
   

   Add to config/app.php under providers:

   Comsave\Common\CommonServiceProvider::class,
   

2. Publish Config (if needed)

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

   Check config/comsave.php for defaults.

3. First Use Case: Basic Helper Usage

   use Comsave\Common\Helpers\StringHelper;
   
   $sanitized = StringHelper::sanitizeInput('user_input');
   $slug = StringHelper::toSlug('Example Title');
   

4. Facade Access

   use Comsave\Common\Facades\Common;
   
   $result = Common::helper()->sanitize('raw_input');
   

Implementation Patterns

Core Workflows

1. String Manipulation

   • Slug Generation: Convert titles to SEO-friendly URLs.

     $slug = Common::helper()->toSlug('Laravel 10 Guide');
     

   • Sanitization: Clean user input for storage/display.

     $clean = Common::helper()->sanitize('<script>alert(1)</script>');
     

2. Data Validation

   • Custom Rules: Extend Laravel validation with package rules.

     use Comsave\Common\Rules\ValidEmailDomain;
     
     $request->validate([
         'email' => ['required', new ValidEmailDomain(['gmail.com'])]
     ]);
     

3. API Response Handling

   • Standardized Responses:

     return Common::response()->success(['data' => $model]);
     return Common::response()->error('Invalid input', 422);
     

4. Event Handling

   • Custom Events: Dispatch package-provided events.

     event(new \Comsave\Common\Events\LogActivity('User updated'));
     

Integration Tips

• Service Container Binding: Bind custom classes to the package’s container.

  $this->app->bind('custom.helper', function () {
      return new \App\Services\CustomHelper();
  });
  

• Middleware: Use package-provided middleware for global sanitization.

  Route::middleware(['sanitize.input'])->group(function () {
      // Routes requiring input sanitization
  });
  

• Blade Directives: Extend Blade with package helpers.

  Blade::directive('sanitize', function ($expression) {
      return "<?php echo Comsave\\Common\\Helpers\\StringHelper::sanitize({$expression}); ?>";
  });
  

  Usage:

  @sanitize($userInput)
  

Gotchas and Tips

Pitfalls

1. Deprecated Methods

   • The package was last updated in 2020. Check for deprecated methods (e.g., StringHelper::clean() may alias to sanitize()).
   • Workaround: Override methods in a trait or extend the class.

2. Configuration Overrides

   • Default config may not align with Laravel 10+. Override in config/comsave.php:

     'sanitize' => [
         'allowed_tags' => '<p><a><strong>', // Update for Laravel 10's HTML parsing
     ],
     

3. Event Listeners

   • Events may not fire if the EventServiceProvider isn’t registered. Ensure:

     protected $listen = [
         \Comsave\Common\Events\LogActivity::class => [
             \App\Listeners\LogActivityListener::class,
         ],
     ];
     

4. Facade Caching

   • Facades cache bindings. Clear the cache after binding custom classes:

     php artisan config:clear
     php artisan cache:clear
     

Debugging

• Log Helpers: Use Common::logger()->debug() for debugging.
• Validation Errors: Enable debug mode in config/comsave.php:

  'debug' => env('APP_DEBUG', false),
  

  This logs validation rules and sanitization steps.

Extension Points

1. Custom Helpers

   • Extend the StringHelper trait or create a new helper class:

     use Comsave\Common\Traits\StringHelperTrait;
     
     class AppStringHelper {
         use StringHelperTrait;
     
         public function customMethod($input) {
             return $this->sanitize($input) . ' (custom)';
         }
     }
     

2. Response Macros

   • Add custom response macros:

     Common::response()->macro('customResponse', function ($data) {
         return response()->json(['custom' => $data]);
     });
     

3. Middleware Extensions

   • Extend the SanitizeInput middleware:

     namespace App\Http\Middleware;
     
     use Comsave\Common\Http\Middleware\SanitizeInput as BaseSanitize;
     
     class CustomSanitize extends BaseSanitize {
         protected $customRules = ['extra_rule' => 'custom_validation'];
     }
     

Performance

• Disable Sanitization for Trusted Input:

  Common::helper()->sanitize($input, false); // Skip sanitization
  

• Cache Slugs:

  $slug = Common::helper()->toSlug('Title', true); // Cache the slug