Psl Laravel Package

Getting Started

Minimal Setup

1. Installation: Add via Composer:

   composer require php-standard-library/php-standard-library
   

   Requires PHP 8.4+.

2. First Use Case: Validate input data with Type combinators:

   use Psl\Type;
   
   $userType = Type\shape([
       'name' => Type\non_empty_string(),
       'age'  => Type\positive_int(),
   ]);
   
   $validated = $userType->coerce($_POST['user']);
   

3. Where to Look First:

   • Type Safety: Psl\Type for data validation/coercion.
   • Async: Psl\Async for structured concurrency (replaces Promises/callbacks).
   • Collections: Psl\Vec, Psl\Dict for functional array operations.

Implementation Patterns

1. Type-Safe Data Handling

• Validation Workflows:

  $schema = Type\shape([
      'id'    => Type\uuid(),
      'roles' => Type\vec(Type\string()),
  ]);
  $data = $schema->coerce($rawInput); // Throws on failure
  

• Integration Tip: Use in Laravel request validation (replace Validator for complex schemas):

  use Psl\Type;
  
  $requestType = Type\shape([
      'email' => Type\email_address(),
      'terms' => Type\bool(),
  ]);
  $validated = $requestType->coerce($request->all());
  

2. Async Patterns

• Structured Concurrency:

  Async\main(static fn() => Async\concurrently([
      fn() => Http\get('api/users'),
      fn() => Cache\get('config'),
  ]));
  

• Workflow Tip: Replace Laravel’s Bus/Queue for async pipelines:

  Async\run(fn() => User::find($id)->processOrder());
  

3. Collections

• Functional Style:

  $users = Vec\filter($users, fn($u) => $u['active']);
  $names = Vec\map($users, fn($u) => $u['name']);
  

• Laravel Integration:

  $activeUsers = Vec\filter($usersCollection, fn($user) => $user->active);
  

4. Networking

• TCP Server:

  $server = TCP\listen('0.0.0.0', 8080);
  while (true) {
      $conn = $server->accept();
      Async\run(fn() => handleConnection($conn));
  }
  

• Use Case: Replace Laravel’s Http facade for raw TCP/UDP.

Gotchas and Tips

Pitfalls

1. Fibers vs. Threads:

   • Async\main() uses fibers (not threads). Avoid blocking calls (e.g., sleep()).
   • Fix: Use Async\sleep() instead.

2. Type Coercion:

   • coerce() throws on failure. Use validate() for silent checks:

     if (!$userType->validate($data)) {
         // Handle error
     }
     

3. Immutable Collections:

   • Operations like Vec\map() return new collections. Avoid mutating originals.

Debugging Tips

• Async Errors: Wrap in try-catch:

  try {
      $result = Async\run(fn() => riskyOperation());
  } catch (Async\Exception\Error $e) {
      report($e);
  }
  

• Type Mismatches: Use Psl\Type\type() to inspect:

  $type = Type\type($data); // Returns Type\TypeInterface
  

Extension Points

1. Custom Types:

   Type\register('custom_type', fn($value) => /* logic */);
   

2. Async Hooks:

   Async\onError(fn($error) => Log::error($error));
   

3. Laravel Service Provider:

   // app/Providers/PslServiceProvider.php
   public function register()
   {
       $this->app->singleton(Async\Scheduler::class, fn() => new Async\FiberScheduler());
   }
   

Performance Quirks

• Fibers: Prefer Async\run() over then() for CPU-bound tasks.
• Collections: Vec\map() is faster than array_map() for large datasets.

Tooling

• Static Analysis: Use the Psalm Plugin for type hints:

  # psalm-plugin.yaml
  plugins:
      - PslPlugin