Runtime Check Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require atoolo/runtime-check-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Atoolo\RuntimeCheckBundle\AtooloRuntimeCheckBundle::class => ['all' => true],
   ];
   

2. First Use Case: Run a basic runtime check via CLI:

   php bin/console runtime:check
   

   This triggers a full environment validation (PHP version, extensions, FPM, etc.).

3. Quick Check in Code: Inject the RuntimeCheckService and run checks programmatically:

   use Atoolo\RuntimeCheckBundle\Service\RuntimeCheckService;
   
   public function __construct(private RuntimeCheckService $runtimeCheck)
   {}
   
   public function checkEnvironment()
   {
       $result = $this->runtimeCheck->checkAll();
       if (!$result->isValid()) {
           throw new \RuntimeException('Environment misconfiguration detected.');
       }
   }
   

Where to Look First

• Documentation: Official Docs
• CLI Commands:

  php bin/console list atoolo:runtime-check
  

• Default Checks: config/packages/atoolo_runtime_check.yaml (auto-generated).

Implementation Patterns

Common Workflows

1. Pre-Deployment Checks: Integrate with CI/CD pipelines (e.g., GitHub Actions) to block deployments:

   # .github/workflows/deploy.yml
   jobs:
     check-environment:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: composer install
         - run: php bin/console runtime:check --fail-on-error
   

2. Dynamic Validation in Controllers: Use middleware to validate runtime before serving requests:

   // src/Kernel.php
   protected function build(RequestContext $requestContext): void
   {
       $this->addRuntimeCheckMiddleware();
   }
   
   private function addRuntimeCheckMiddleware(): void
   {
       $this->middleware(function (Request $request, Closure $next) {
           $runtimeCheck = $this->container->get(RuntimeCheckService::class);
           if (!$runtimeCheck->checkAll()->isValid()) {
               abort(503, 'Environment not ready.');
           }
           return $next($request);
       });
   }
   

3. Custom Checks: Extend the bundle’s check system by creating a custom validator:

   // src/Validator/CustomCheckValidator.php
   use Atoolo\RuntimeCheckBundle\Validator\RuntimeCheckValidatorInterface;
   
   class CustomCheckValidator implements RuntimeCheckValidatorInterface
   {
       public function validate(): bool
       {
           return file_exists('/custom/required/file');
       }
   
       public function getName(): string
       {
           return 'Custom File Check';
       }
   }
   

   Register in config/packages/atoolo_runtime_check.yaml:

   atoolo_runtime_check:
       validators:
           - Atoolo\RuntimeCheckBundle\Validator\PhpVersionValidator
           - App\Validator\CustomCheckValidator
   

4. Scheduled Checks: Use Symfony’s scheduler to run periodic validations (e.g., nightly):

   # config/packages/messenger.yaml
   framework:
       messenger:
           transports:
               async: '%env(MESSENGER_TRANSPORT_DSN)%'
           routing:
               'Atoolo\RuntimeCheckBundle\Message\RuntimeCheckMessage': async
   

   Dispatch a message:

   $this->messageBus->dispatch(new RuntimeCheckMessage());
   

Integration Tips

• Logging: Results are logged via Monolog (configure in config/packages/monolog.yaml).
• Error Handling: Use --fail-on-error flag in CLI for strict validation.
• Performance: Cache results if running checks frequently (e.g., in a warm-up command):

  $this->runtimeCheck->checkAll(true); // Cache results
  

Gotchas and Tips

Pitfalls

1. FPM Socket Paths:

   • The bundle checks FPM socket locations (e.g., /run/php-fpm.socket). On SUSE, use the custom path:

     # config/packages/atoolo_runtime_check.yaml
     atoolo_runtime_check:
         fpm_socket_path: '/var/run/php-fpm.socket' # Override if needed
     

   • Debugging: If FPM checks fail, verify socket permissions:

     ls -la /run/php-fpm.socket
     

2. PHP Version Mismatch:

   • The bundle enforces PHP 8.1–8.5 by default. If using 8.4+, ensure ext-posix and opcache are enabled:

     php -m | grep -E 'posix|opcache'
     

   • Fix: Add to php.ini:

     extension=posix
     opcache.enable=1
     

3. Lock Contention:

   • Checks use Symfony’s LockStore (default: file). In shared environments, configure a robust store:

     # config/packages/atoolo_runtime_check.yaml
     atoolo_runtime_check:
         lock_store: 'symfony.lock.store.redis'
     

4. Custom Validators:

   • Avoid blocking: Ensure custom validators return false gracefully (e.g., log warnings instead of throwing exceptions).
   • Testing: Mock validators in unit tests:

     $validator = $this->createMock(RuntimeCheckValidatorInterface::class);
     $validator->method('validate')->willReturn(false);
     $validator->method('getName')->willReturn('Test Validator');
     $this->runtimeCheck->addValidator($validator);
     

Debugging

• Verbose Output:

  php bin/console runtime:check --verbose
  

• Check Logs:

  tail -f var/log/dev.log | grep "RuntimeCheck"
  

• Isolate Failures: Run individual checks:

  php bin/console runtime:check php-version
  php bin/console runtime:check fpm
  

Extension Points

1. Override Default Checks: Disable built-in validators in config/packages/atoolo_runtime_check.yaml:

   atoolo_runtime_check:
       enabled_validators: ['php_version', 'fpm'] # Whitelist
   

2. Custom Error Responses: Extend the RuntimeCheckResult class to add metadata:

   // src/Result/CustomRuntimeCheckResult.php
   class CustomRuntimeCheckResult extends RuntimeCheckResult
   {
       public function addMetadata(string $key, mixed $value): void
       {
           $this->metadata[$key] = $value;
       }
   }
   

   Bind the service in services.yaml:

   services:
       Atoolo\RuntimeCheckBundle\Service\RuntimeCheckService:
           arguments:
               $resultClass: App\Result\CustomRuntimeCheckResult
   

3. Webhook Notifications: Dispatch events when checks fail:

   // src/EventListener/RuntimeCheckListener.php
   use Atoolo\RuntimeCheckBundle\Event\RuntimeCheckFailedEvent;
   
   class RuntimeCheckListener
   {
       public function onCheckFailed(RuntimeCheckFailedEvent $event)
       {
           // Send Slack/email alert
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\RuntimeCheckListener:
           tags:
               - { name: 'kernel.event_listener', event: 'runtime_check.failed', method: 'onCheckFailed' }
   

Configuration Quirks

• Environment Variables: Prefix runtime checks with RUNTIME_CHECK_ to override defaults:

  export RUNTIME_CHECK_FPM_SOCKET_PATH=/custom/path.socket
  

• Symfony 7.x: Ensure symfony/scheduler is installed if using scheduled checks (added in Symfony 6.3+).
• Docker: Mount socket files explicitly in docker-compose.yml:

  services:
      php:
          volumes:
              - /run/php-fpm.socket:/run/php-fpm.socket