Foundation Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require php-standard-library/foundation
   

2. Basic Usage: Import the core utilities in your Laravel project:

   use Foundation\Helpers\StringHelper;
   use Foundation\Collections\Collection;
   use Foundation\Contracts\Arrayable;
   

3. First Use Case: Replace ad-hoc string manipulation with standardized helpers:

   $cleaned = StringHelper::slugify('My Awesome Post');
   // Output: "my-awesome-post"
   

Where to Look First

• Core Helpers: Foundation\Helpers namespace (e.g., StringHelper, ArrayHelper)
• Collections: Foundation\Collections\Collection (Laravel-like but framework-agnostic)
• Contracts: Foundation\Contracts (e.g., Arrayable, Jsonable) for type safety
• Conventions: Check Foundation\Conventions for project-wide standards (e.g., naming, file structures)

Implementation Patterns

Workflows

1. Centralized Utilities: Replace duplicated logic (e.g., array flattening, deep merging) with package methods:

   use Foundation\Helpers\ArrayHelper;
   
   $merged = ArrayHelper::deepMerge($array1, $array2);
   

2. Framework-Agnostic Abstractions: Use Arrayable/Jsonable contracts in Laravel models/services:

   use Foundation\Contracts\Arrayable;
   
   class User implements Arrayable {
       public function toArray(): array {
           return ['id' => $this->id, 'name' => $this->name];
       }
   }
   

3. Composable Building Blocks: Extend Foundation\Collections\Collection for custom logic:

   $collection = new Collection([1, 2, 3]);
   $filtered = $collection->filter(fn($item) => $item > 1);
   

4. Laravel Integration:

   • Service Providers: Bind interfaces to implementations:

     $this->app->bind(Arrayable::class, function () {
         return new LaravelArrayableAdapter();
     });
     

   • Helpers: Replace Laravel’s Str::, Arr:: with Foundation\Helpers where conventions align.

5. Testing: Use Foundation\Testing\TestCase as a base for PHPUnit tests to enforce consistent assertions.

Integration Tips

• Autoloading: Ensure autoload-dev includes test helpers if using Foundation\Testing.
• Configuration: Override defaults via config/foundation.php (if provided) or environment variables.
• IDE Support: Add @mixin in PHPDoc for IDE autocompletion:

  /** @mixin \Foundation\Collections\Collection */
  class LaravelCollection extends \Illuminate\Support\Collection {}
  

• Migration Path: Gradually replace custom utilities with package equivalents (e.g., swap app/Helpers with Foundation\Helpers).

Gotchas and Tips

Pitfalls

1. Framework Assumptions:

   • Avoid mixing Laravel-specific logic (e.g., Request objects) with framework-agnostic helpers. Use adapters if needed.
   • Example: Don’t pass Illuminate\Http\Request to StringHelper::slugify()—extract the string first.

2. Performance Overhead:

   • Some helpers (e.g., deep recursion) may impact performance. Benchmark critical paths.
   • Example: ArrayHelper::deepMerge() uses recursion; prefer iterative methods for large arrays.

3. Contract Conflicts:

   • Laravel already defines Arrayable/Jsonable. Use fully qualified namespaces to avoid collisions:

     use Foundation\Contracts\Arrayable as FoundationArrayable;
     

4. Configuration Quirks:

   • If the package lacks config, define defaults in bootstrap/app.php:

     $app->singleton(\Foundation\Helpers\StringHelper::class, function () {
         return new StringHelper(config('foundation.string.default_locale', 'en'));
     });
     

Debugging

• Enable Debug Mode: Set FOUNDATION_DEBUG=true in .env to log helper invocations (if supported).
• Type Errors: Use phpstan or psalm to catch type mismatches with Foundation\Contracts.
• Collection Issues: Verify Collection methods match Laravel’s (e.g., pluck() vs. map()). Check the Collections API docs.

Extension Points

1. Custom Helpers: Extend base classes (e.g., StringHelper) via traits or decorators:

   use Foundation\Helpers\StringHelper;
   
   trait CustomStringHelper {
       public function customMethod(string $input): string {
           return $this->slugify($input) . '-suffix';
       }
   }
   

2. New Contracts: Add interfaces to Foundation\Contracts for project-specific needs:

   namespace Foundation\Contracts;
   
   interface Cacheable {
       public function toCacheArray(): array;
   }
   

3. Testing Extensions: Override Foundation\Testing\TestCase to add Laravel-specific assertions:

   class LaravelTestCase extends TestCase {
       protected function assertModelExists($modelClass, $attributes) {
           $this->assertDatabaseHas($modelClass::class, $attributes);
       }
   }
   

4. Package Composition: Use Foundation as a dependency for your own packages to enforce shared conventions:

   {
       "require": {
           "php-standard-library/foundation": "^1.0"
       },
       "extra": {
           "laravel": {
               "providers": ["Foundation\Providers\FoundationServiceProvider"]
           }
       }
   }
   

Pro Tips

• Naming Conventions: Prefix custom helpers with Foundation to avoid conflicts (e.g., FoundationStringHelper).
• Documentation: Generate API docs with phpDocumentor to share conventions across teams.
• CI/CD: Add a composer validate check to enforce package constraints in PRs.
• Legacy Code: Use Foundation\Legacy\Compatibility to wrap old utilities for gradual migration.