Common Laravel Package

Getting Started

Install the package via Composer in your Laravel project:

composer require gpupo/common:^5.9

First Steps:

1. Review the unit tests (primary documentation) in the package’s tests/ directory to understand usage patterns.
2. Generate test cases for your existing classes (if needed) using the CLI tool:

   vendor/bin/developer-toolbox developer-toolbox:tests:generate --class 'App\Models\YourClass'
   

3. Start with core utilities like:
   • Gpupo\Common\Tools\Datetime\TimeShift for date/time manipulations.
   • Gpupo\Common\Support\Str for string operations (snake_case/camelCase conversions).
   • Gpupo\Common\Validation\Rules for custom validation logic.

Quick Example:

use Gpupo\Common\Tools\Datetime\TimeShift;

// Shift a date by 5 days
$shiftedDate = TimeShift::shift('2024-01-01', 5, 'days');

Implementation Patterns

1. Core Utility Integration

Pattern: Use traits and base classes to reduce boilerplate.

use Gpupo\Common\Traits\SingletonTrait;
use Gpupo\Common\Traits\GettersTypeTrait;

class YourService
{
    use SingletonTrait, GettersTypeTrait;

    // Singleton ensures one instance; GettersTypeTrait adds typed getters.
}

When to Use:

• For service classes needing singleton behavior.
• To auto-generate getters/setters with type safety.

2. CLI Tooling for Development

Pattern: Automate test generation and debugging.

# Generate test stubs for a class
vendor/bin/developer-toolbox developer-toolbox:tests:generate --class 'App\Services\PaymentService'

# Debug configuration (dev-only)
vendor/bin/developer-toolbox developer-toolbox:config:dump

Use Cases:

• Onboarding: Quickly scaffold tests for legacy classes.
• Debugging: Inspect package configurations without digging into source.

3. Laravel-Specific Adaptations

Pattern: Extend Laravel’s built-in features with gpupo/common utilities.

// In AppServiceProvider
use Gpupo\Common\Http\ResponseFactory;

public function boot()
{
    Response::macro('api', function ($data, $status = 200) {
        return ResponseFactory::json($data, $status);
    });
}

// Usage in controllers
return response()->api(['message' => 'Success'], 201);

Why:

• Standardize API responses across controllers.
• Leverage ResponseFactory for consistent JSON/API formats.

4. Validation and Rules

Pattern: Reuse or extend validation rules.

use Gpupo\Common\Validation\Rules\CustomRule;

$validator = Validator::make($request->all(), [
    'email' => ['required', new CustomRule],
]);

Tip:

• Override CustomRule to add project-specific logic (e.g., domain validation).

5. Configuration Management

Pattern: Override defaults via Laravel’s config.

// config/gpupo.php
return [
    'datetime_format' => 'Y-m-d H:i:s', // Override package defaults
];

Use Case:

• Customize behavior (e.g., date formats, response structures) without modifying the package.

Gotchas and Tips

Pitfalls

1. Symfony 6 Dependency Conflicts

   • Issue: If your project uses Symfony components (e.g., HttpFoundation) from v5.x, conflicts may arise.
   • Fix: Update all Symfony packages to ^6.x or pin versions:

     "symfony/http-foundation": "^6.0"
     

2. PHP 8.3 Strict Typing

   • Issue: The package uses PHP 8.3 features (e.g., typed class constants). Older PHP versions will fail.
   • Fix: Ensure your project uses PHP 8.3+ and update composer.json:

     "require": {
         "php": "^8.3"
     }
     

3. CLI Tools Are Dev-Only

   • Issue: Commands like developer-toolbox are for debugging and won’t work in production.
   • Fix: Ignore them in production environments or wrap usage in if (app()->environment('local')).

4. Unit Tests Are the Documentation

   • Issue: The package lacks traditional docs; critical usage examples are in tests.
   • Fix: Study tests/ directory for patterns (e.g., TimeShiftTest.php).

Debugging Tips

1. Enable Debug Mode

   // In AppServiceProvider
   \Gpupo\Common\Support\Debug::enable();
   

   • Logs detailed errors to storage/logs/gpupo-debug.log.

2. Dump Configurations

   vendor/bin/developer-toolbox developer-toolbox:config:dump
   

   • Outputs current package settings for troubleshooting.

3. Check for Deprecated Methods

   • Run PHPStan or Psalm to catch Symfony 6 deprecations:

     vendor/bin/phpstan analyse --level 8
     

Extension Points

1. Custom Traits

   • Extend SingletonTrait or GettersTypeTrait for project-specific logic:

     trait YourCustomTrait extends GettersTypeTrait {
         public function customMethod(): string { ... }
     }
     

2. Override Validation Rules

   • Create a custom rule by extending Gpupo\Common\Validation\Rules\AbstractRule:

     class UniqueDomainRule extends AbstractRule {
         public function passes($attribute, $value) { ... }
     }
     

3. Modify Response Factory

   • Override ResponseFactory in AppServiceProvider:

     $this->app->singleton(\Gpupo\Common\Http\ResponseFactory::class, function () {
         return new CustomResponseFactory();
     });
     

Performance Considerations

• Singleton Caching: Overuse of SingletonTrait can lead to memory bloat. Prefer dependency injection where possible.
• Validation Rules: Complex rules may slow down request processing. Cache compiled rules if reused frequently:

  $validator = Validator::make($data, $rules, [], [], ['rules' => Cache::remember('validator_rules', ...));
  

Laravel-Specific Quirks

1. Service Provider Binding

   • If the package’s service provider conflicts with Laravel’s, manually rebind:

     $this->app->rebinding(\Gpupo\Common\Contracts\Example::class, function ($app, $abstract, $concrete) {
         return new CustomExample();
     });
     

2. Blade Directives

   • The package may include Blade helpers. Register them in AppServiceProvider:

     Blade::directive('gpupo', function () {
         return "<?php echo Gpupo\Common\Support\Blade::render(); ?>";
     });
     

3. Queue Jobs

   • If using gpupo/common in queue jobs, ensure the SingletonTrait is not overused (jobs are stateless by design).