Common Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require codemitte/common
   

   Publish the config file (if available) with:

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

2. First Use Case Check the src/Helpers directory for immediately usable utility functions. For example, if the package includes string manipulation helpers:

   use Codemitte\Common\Helpers\StringHelper;
   
   $snakeCase = StringHelper::snakeCase('CamelCaseString');
   

3. Where to Look First

   • src/Helpers/: Core utility functions (e.g., StringHelper, ArrayHelper).
   • src/Traits/: Reusable traits for models or controllers.
   • src/Exceptions/: Custom exceptions if the package includes them.
   • config/common.php: Configuration options (if published).

Implementation Patterns

Usage Patterns

1. Helper Functions Use static helper methods for one-off tasks (e.g., formatting, validation):

   // Example: Convert array keys to snake_case
   $formatted = ArrayHelper::snakeKeys($array);
   

2. Traits in Models/Classes Extend Eloquent models or services with traits for reusable logic:

   use Codemitte\Common\Traits\HasSoftDeletesWithAudit;
   
   class User extends Model
   {
       use HasSoftDeletesWithAudit;
   }
   

3. Middleware or Service Providers Register package-specific bindings or macros in AppServiceProvider:

   public function boot()
   {
       // Extend Laravel's Str helper
       \Str::macro('customMethod', function () {
           return \Codemitte\Common\Helpers\StringHelper::customMethod();
       });
   }
   

4. Configuration-Driven Behavior Customize package behavior via config (if supported):

   // config/common.php
   'default_locale' => 'en_US',
   

Workflows

• Data Transformation: Use helpers to normalize API responses or form inputs.
• Validation: Leverage custom validation rules (if provided) in Form Requests:

  use Codemitte\Common\Rules\CustomRule;
  
  public function rules()
  {
      return [
          'field' => ['required', new CustomRule],
      ];
  }
  

• Logging/Auditing: Integrate traits for automatic audit logs in models.

Integration Tips

• Laravel Facades: If the package provides facades, use them for cleaner syntax:

  use Codemitte\Common\Facades\Common;
  
  $result = Common::doSomething();
  

• Service Container: Bind custom interfaces to package implementations in register():

  $this->app->bind(
      \App\Contracts\CustomInterface::class,
      \Codemitte\Common\Services\CustomService::class
  );
  

• Testing: Mock package dependencies in PHPUnit tests:

  $this->partialMock(Codemitte\Common\Services\CustomService::class, ['method']);
  

Gotchas and Tips

Pitfalls

1. Undocumented Features

   • The package lacks stars/dependents, so assume minimal documentation. Explore src/ directly for undocumented helpers.
   • Fix: Check tests/ for usage examples or raise issues for clarification.

2. Namespace Collisions

   • Static helpers might conflict with Laravel’s built-ins (e.g., ArrayHelper vs. Laravel’s Arr).
   • Fix: Prefix calls or alias namespaces:

     use Codemitte\Common\Helpers\{StringHelper as CMStringHelper};
     

3. Configuration Overrides

   • If the package publishes config, ensure your .env or config/ doesn’t override critical defaults silently.
   • Fix: Compare vendor/codemitte/common/config/common.php with your published file.

4. Trait Method Conflicts

   • Traits may assume method signatures that conflict with Laravel’s conventions (e.g., boot() in models).
   • Fix: Use as in use statements or override methods:

     use Codemitte\Common\Traits\HasSoftDeletesWithAudit as HasAuditTrait;
     

5. No Facade Support

   • If the package lacks facades, static calls may feel verbose.
   • Fix: Create a facade wrapper in your app:

     namespace App\Facades;
     
     use Illuminate\Support\Facades\Facade;
     
     class Common extends Facade
     {
         protected static function getFacadeAccessor() { return 'codemitte.common'; }
     }
     

Debugging

• Enable Debugging: Add this to AppServiceProvider to log helper calls:

  if (app()->environment('local')) {
      \Codemitte\Common\Helpers\LogHelper::enableDebug();
  }
  

• Check for Deprecations: Use php artisan package:discover to ensure the package is loaded.
• Test Edge Cases: Validate helpers with empty inputs or edge cases (e.g., null, arrays with mixed types).

Tips

1. Extend the Package

   • Override helpers in your app’s app/Helpers/ directory to avoid forks:

     // app/Helpers/StringHelper.php
     namespace App\Helpers;
     
     use Codemitte\Common\Helpers\StringHelper as BaseStringHelper;
     
     class StringHelper extends BaseStringHelper
     {
         public static function snakeCase(string $string): string
         {
             return parent::snakeCase($string) . '_custom';
         }
     }
     

   • Update Composer’s autoload to include your overrides:

     "autoload": {
         "files": ["app/Helpers/StringHelper.php"]
     }
     

2. Performance

   • Cache repeated helper calls in a service:

     $cache = new \Symfony\Component\Cache\Adapter\FilesystemAdapter();
     $result = $cache->get('key', function() use ($helper) {
         return $helper->expensiveOperation();
     });
     

3. Type Safety

   • Add PHP 8 attributes to helpers for better IDE support:

     #[ReturnTypeWillChange]
     public static function snakeCase(string $string): string { ... }
     

4. Contributing Back

   • If the package is useful, consider forking and submitting PRs to improve documentation or add missing features.

5. Fallback Logic

   • Gracefully handle missing helpers with fallback logic:

     if (method_exists(\Codemitte\Common\Helpers\StringHelper::class, 'snakeCase')) {
         $result = \Codemitte\Common\Helpers\StringHelper::snakeCase($str);
     } else {
         $result = Str::snake($str);
     }