Php Utilities Laravel Package

Getting Started

Minimal Setup

1. Installation Add to composer.json:

   {
       "require": {
           "anglemx/php-utilities": "^1.0"
       }
   }
   

   Run composer update.

2. First Use Case Quickly validate a Git repository structure in a Laravel command:

   use Angle\Utilities\Git;
   
   public function handle()
   {
       $git = new Git();
       if ($git->isGitRepo()) {
           $this->info('Valid Git repo detected.');
       }
   }
   

3. Key Entry Points

   • Git class: Validate Git repos, check status, or parse .gitignore.
   • File helper: File operations (e.g., File::ensureDirectoryExists()).
   • String helper: String manipulation (e.g., String::slugify()).
   • Array helper: Array utilities (e.g., Array::deepMerge()).

Implementation Patterns

Common Workflows

1. Git Operations in Laravel

   • Repo Validation: Use Git::isGitRepo() in boot() to enforce Git in deployments.
   • Status Checks: Integrate Git::getStatus() into a command:deploy hook:

     $status = Git::getStatus();
     if ($status->hasChanges()) {
         $this->error('Uncommitted changes detected!');
         return 1;
     }
     

2. File System Utilities

   • Safe Directory Creation: Replace Storage::makeDirectory() with:

     File::ensureDirectoryExists(storage_path('app/cache'));
     

   • File Existence Checks: Use File::exists() in service providers:

     if (File::exists(config_path('custom.php'))) {
         $this->mergeConfigFrom(config_path('custom.php'), 'custom');
     }
     

3. String/Array Helpers

   • Slug Generation: Replace Str::slug() with:

     $slug = String::slugify('My Awesome Post');
     

   • Deep Merging: Merge configs without overwriting:

     $merged = Array::deepMerge($defaultConfig, $userConfig);
     

4. Integration with Laravel Services

   • Validation Rules: Extend Laravel’s validator:

     use Angle\Utilities\Validation\Rules\GitRepoExists;
     
     'repo_path' => ['required', new GitRepoExists],
     

   • Middleware: Check Git status before allowing edits:

     public function handle($request, Closure $next)
     {
         if (!Git::isGitRepo() || Git::getStatus()->hasChanges()) {
             abort(403, 'Git repo required and clean.');
         }
         return $next($request);
     }
     

Gotchas and Tips

Pitfalls

1. Git Path Assumptions

   • The Git class assumes the current working directory is the repo root. Explicitly pass paths:

     $git = new Git(__DIR__); // For project-specific repos
     

   • Fix: Use Git::setPath() or pass the path to methods.

2. File Permissions

   • File::ensureDirectoryExists() may fail silently on restricted systems. Add error handling:

     try {
         File::ensureDirectoryExists($path);
     } catch (Exception $e) {
         Log::error("Failed to create directory: {$e->getMessage()}");
     }
     

3. String Slugification

   • String::slugify() uses a basic regex. For multilingual support, combine with Laravel’s Str::ascii():

     $slug = String::slugify(Str::ascii($title));
     

4. Array Deep Merge

   • Array::deepMerge() overwrites arrays by default. Use Array::deepMergeRecursive() for non-destructive merges:

     $merged = Array::deepMergeRecursive($a, $b, true); // Preserve arrays
     

Debugging Tips

• Git Status Issues: Use Git::getStatus()->getOutput() to inspect raw CLI output.
• File Operations: Enable Laravel’s storage/logs/laravel.log to catch permission errors.
• String/Array Helpers: Test edge cases (e.g., null inputs) with:

  $result = String::slugify(null); // Returns empty string
  

Extension Points

1. Custom Git Commands Extend the Git class to add commands (e.g., Git::run('branch -a')).

2. Validation Rules Create reusable rules by extending GitRepoExists:

   class ValidGitignore extends GitRepoExists
   {
       public function validateAttribute($attribute, $value, $fail)
       {
           if (!File::exists($value . '/.gitignore')) {
               $fail('Gitignore file missing.');
           }
       }
   }
   

3. File System Events Hook into Laravel’s filesystem events to log file changes using File helpers.

4. String Templates Combine with Laravel’s Blade for dynamic content:

   {{ String::template('Hello, {name}!', ['name' => $user->name]) }}